adm_link_shares_api

Public link shares: a URL that grants access to one document to whoever holds it, with no ADM account involved. Optionally protected by a password, optionally with an expiry.

A link is a bearer token. Anyone who has the URL has the access, and the only two guards are the expiry date and the password - neither of which is mandatory, which is why the guide recommends always setting an expiry.

Publishing or changing a link takes the same rights as any other kind of sharing: EDIT on the document. Without that check any user could publish any document id, with role EDIT and no expiry.

There is no delete procedure. The application removes a link by deleting its adm_document_link_shares row, and trashing or deleting the document revokes its links automatically via adm_shares_api.

Every operation here is audited: CREATE_SHARE_LINK, MODIFY_SHARE_LINK and - unlike an internal share - USE_SHARE_LINK each time the link is redeemed.

Functions and Procedures

get_share_url

Builds the absolute URL to hand out for a share token.

Points at the public share-entry page, with no session, so the URL survives being mailed and bookmarked.

Signature:

function get_share_url (
  p_share_url_token in varchar2
) return varchar2 deterministic ;

Parameters:

Name	Direction	Type	Description
p_share_url_token	in	varchar2	The token of the link share

Returns: varchar2 deterministic - The absolute, session-less URL for the share

---

create_document_link_share

Publishes a new link share for a document.

Requires EDIT rights on the document, and raises adm_error.c_err_no_permission otherwise. The token is 32 random bytes, and the password - when one is given - is stored only as a hash. A share created without a password stays open to anyone holding the URL.

Signature:

procedure create_document_link_share (
  p_document_id in adm_document_link_shares.document_id%type,
  p_expiration_date in adm_document_link_shares.expiration_date%type,
  p_share_role in adm_document_link_shares.share_role%type,
  p_password in varchar2
);

Parameters:

Name	Direction	Type	Description
p_document_id	in	adm_document_link_shares.document_id%type	The document to publish
p_expiration_date	in	adm_document_link_shares.expiration_date%type	When the link stops working. Null means it never expires,

                     which is rarely what you want |

| p_share_role | in | adm_document_link_shares.share_role%type | adm_access_control_api.c_view or c_edit. An EDIT link lets an anonymous holder upload a new version of the document | | p_password | in | varchar2 | Optional password. Null publishes an unprotected link |

---

modify_document_link_share

Changes the expiry and role of an existing link share. The URL and token stay the same, so a link already handed out keeps working under the new terms.

Because this can raise the role to EDIT and push the expiry out indefinitely, it takes the same EDIT rights as creating the link. Raises adm_error.c_err_share_not_found for an unknown id and adm_error.c_err_no_permission without the rights. The password cannot be changed here - delete the link and publish a new one.

Signature:

procedure modify_document_link_share (
  p_doc_link_share_id in adm_document_link_shares.doc_link_share_id%type,
  p_expiration_date in adm_document_link_shares.expiration_date%type,
  p_share_role in adm_document_link_shares.share_role%type
);

Parameters:

Name	Direction	Type	Description
p_doc_link_share_id	in	adm_document_link_shares.doc_link_share_id%type	The link share to change
p_expiration_date	in	adm_document_link_shares.expiration_date%type	The new expiry. Null means it never expires
p_share_role	in	adm_document_link_shares.share_role%type	adm_access_control_api.c_view or c_edit

---

check_credentials

Redeems a share token: validates it, resolves the document behind it, and records the use in the audit log.

Raises adm_error.c_err_invalid_credentials for an unknown token or a wrong password, and adm_error.c_err_expired past the expiry date. All three paths delay before raising, so the endpoint cannot be used to enumerate tokens or guess passwords quickly, and the unknown-token and wrong-password cases are indistinguishable.

Signature:

procedure check_credentials (
  p_share_url_token in adm_document_link_shares.share_url_token%type,
  p_password in varchar2,
  po_document_id out adm_document_link_shares.document_id%type,
  po_doc_link_share_id out adm_document_link_shares.doc_link_share_id%type
);

Parameters:

Name	Direction	Type	Description
p_share_url_token	in	adm_document_link_shares.share_url_token%type	The token from the URL
p_password	in	varchar2	The password supplied by the visitor, or null
po_document_id	out	adm_document_link_shares.document_id%type	The document the token grants access to
po_doc_link_share_id	out	adm_document_link_shares.doc_link_share_id%type	The link share that was redeemed

---