adm_embed_api

This document contains the API documentation for the adm_embed_api package.

Functions and Procedures

get_item_values

Generates secure URL parameters for embedding functionality

The username is checksum-signed here and accepted as proof of identity by the embed page, so who may be named is restricted: the caller’s own context username, anybody at all when the caller is an administrator, and - for a token whose permissions carry "identity": "HOST" - whoever the parent application says. That last case is what lets an embedded browser run as a user of the host application who has no adm_users row of their own; the token still bounds everything they can reach.

Signature:

function get_item_values (
  p_embed_token in adm_embed_tokens.embed_token%type,
  p_username in varchar2,
  p_session in number default nv('APP_SESSION'
);

Parameters:

Name	Direction	Type	Description
`p_embed_token`	in	`adm_embed_tokens.embed_token%type`	The embed token to include in the parameters
`p_username`	in	`varchar2`	The username to include in the parameters
`p_session`	in	`number default nv('APP_SESSION'`	The session ID to include in the parameters

Returns: varchar2 - A formatted string containing the URL parameters for embedding

get_or_create_document_token

Gets an existing embed token for a document or creates a new one if none exists It will create a new one if it expires in the next hour

A token is only reused when its GRANTS match what you asked for, not merely its read-only bit. Two tokens with different grant sets are indistinguishable on is_read_only alone, so matching on that would hand a caller asking for an upload-only token the existing fully-writable one.

Signature:

function get_or_create_document_token (
  p_document_id in adm_documents.document_id%type,
  p_description in adm_embed_tokens.description%type default null,
  p_expires_at in adm_embed_tokens.expires_at%type default systimestamp + 1,
  p_is_readonly in adm_embed_tokens.is_read_only%type default 'Y',
  p_permissions in clob default null
) return adm_embed_tokens.embed_token%type;

Parameters:

Name	Direction	Type	Description
`p_document_id`	in	`adm_documents.document_id%type`	The ID of the document to get/create a token for
`p_description`	in	`adm_embed_tokens.description%type default null`	Optional description for the embed token (only used when creating)
`p_expires_at`	in	`adm_embed_tokens.expires_at%type default systimestamp + 1`	Optional expiration date for the embed token (only used when creating)
`p_is_readonly`	in	`adm_embed_tokens.is_read_only%type default 'Y'`	Whether the embed token should be read-only (only used when creating)
`p_permissions`	in	`clob default null`	Optional granular permissions as JSON (see adm_embed_perm_api). Null keeps the coarse p_is_readonly behaviour; when given it determines p_is_readonly rather than the other way round. A payload carrying `"identity": "HOST"` lets get_item_values sign the URL for a user the parent application names rather than for the caller, and takes ADMIN to create.

Returns: adm_embed_tokens.embed_token%type - The embed token for the document

get_or_create_folder_token

Gets an existing embed token for a folder or creates a new one if none exists It will create a new one if it expires in the next hour

Reuse matches on the grant set, not just the read-only bit - see get_or_create_document_token.

Signature:

function get_or_create_folder_token (
  p_folder_id in adm_folders.folder_id%type,
  p_description in adm_embed_tokens.description%type default null,
  p_expires_at in adm_embed_tokens.expires_at%type default systimestamp + 1,
  p_is_readonly in adm_embed_tokens.is_read_only%type default 'Y',
  p_permissions in clob default null
) return adm_embed_tokens.embed_token%type;

Parameters:

Name	Direction	Type	Description
`p_folder_id`	in	`adm_folders.folder_id%type`	The ID of the folder to get/create a token for
`p_description`	in	`adm_embed_tokens.description%type default null`	Optional description for the embed token (only used when creating)
`p_expires_at`	in	`adm_embed_tokens.expires_at%type default systimestamp + 1`	Optional expiration date for the embed token (only used when creating)
`p_is_readonly`	in	`adm_embed_tokens.is_read_only%type default 'Y'`	Whether the embed token should be read-only (only used when creating)
`p_permissions`	in	`clob default null`	Optional granular permissions as JSON (see adm_embed_perm_api). Null keeps the coarse p_is_readonly behaviour. A payload carrying `"identity": "HOST"` lets get_item_values sign the URL for a user the parent application names rather than for the caller, and takes ADMIN to create.

Returns: adm_embed_tokens.embed_token%type - The embed token for the folder

generate_token

Creates a new embed token and stores it in the database Generates a secure token for embedding specific assets or content types. Runs as an autonomous transaction so that you can generate tokens on the fly

Minting is a publishing act, so it takes the same rights as sharing the asset: EDIT. A grant that DISPOSES of something takes more - a p_permissions payload containing DELETE requires OWNER, because you cannot grant what you do not hold.

That OWNER requirement is load-bearing at RUN time too, not only here. A trashed document goes into /users//trash, which is outside every embed scope, and the name an embed session uses is this token’s creator (adm_access_control_api.embed_trash_owner). Parking a row under somebody’s home hands them view and owner rights on it, so that would be an escalation for anybody but a person who already holds them over the subtree - which is exactly what this check establishes. Take it out and the delete path becomes one.

Signature:

function generate_token (
  p_embed_type in adm_embed_tokens.embed_type%type,
  p_asset_path in adm_embed_tokens.asset_path%type,
  p_description in adm_embed_tokens.description%type default null,
  p_expires_at in adm_embed_tokens.expires_at%type default null,
  p_is_readonly in adm_embed_tokens.is_read_only%type default 'Y',
  p_permissions in clob default null
) return adm_embed_tokens.embed_token%type;

Parameters:

Name	Direction	Type	Description
`p_embed_type`	in	`adm_embed_tokens.embed_type%type`	The type of embedding: ‘DOCUMENT’ or ‘FOLDER’
`p_asset_path`	in	`adm_embed_tokens.asset_path%type`	The path to the asset being embedded
`p_description`	in	`adm_embed_tokens.description%type default null`	Optional description of what this embed token is for
`p_expires_at`	in	`adm_embed_tokens.expires_at%type default null`	Optional expiration date for the embed token
`p_is_readonly`	in	`adm_embed_tokens.is_read_only%type default 'Y'`	Whether the embed token should be read-only
`p_permissions`	in	`clob default null`	Optional granular permissions as JSON (see adm_embed_perm_api). Validated here; an unknown or unenforceable grant is refused.

Returns: adm_embed_tokens.embed_token%type - The generated embed token