Embedding ADM into Other Applications

Set Up

Step 1: Grant execute privileges

If you want to embed ADM into another application that lives in a different schema, you need to grant execute privileges on the adm_embed_api package to the schema of the application where you want to embed ADM.

GRANT EXECUTE ON adm_embed_api TO <target_schema>;

Step 2: Create Embed Token

We do recommend dynamically creating tokens by the document or folder ID. You can use the adm_embed_api package to achieve this. The get_or_create_ functions will create an expiring token if there currently is none.

:P1_TOKEN := adm_embed_api.get_or_create_document_token (
  p_document_id => :P1_DOCUMENT_ID
);

:P1_TOKEN := adm_embed_api.get_or_create_folder_token (
  p_folder_id => :P1_FOLDER_ID
);

-- both have optional parameters:
-- 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'

Alternatively you can manually create an embed token using the ADM interface. Log-in to the ADM application as administrator and go to the administration page. Click the menu entry Embed Tokens and create a new embed token.

You need to choose whether you want to embed a file or a folder and then enter the path to the asset. When done copy the generated embed token to your clipboard.

Step 3: Import Plug-In

You need to import the UC Nested Pages Pro plug-in into the application where you want to embed ADM. This plug-in is essential for the integration process.

Also compile the uc_dynamic_dashboard package in the schema of the application where you want to embed ADM.

Step 4: Create the region

Go to a page where you want to embed ADM and create a new region of type UC Nested Pages Pro.

As a source for the region, select SQL Query and enter the following SQL query:

SELECT
     'https://your-domain/ords/r/ws/acm/embed-folder-view?' || adm.adm_embed_api.get_item_values('{EMBED_TOKEN}', :APP_USER)
     as iframe_url
FROM
    dual

Note

If you embed from the same workspace, add ‘?session=’ || :APP_SESSION to the end.

Make sure to replace the url with the correct URL of your ADM instance and the embed token with the one you copied earlier.

In the Attributes section of the region plug-in, set the following attributes:

• Page URL Column: iframe_url
• Loading template: <div>Loading...</div>

Now when you run the page, you should see the ADM interface embedded within your application.

Security

The embeds open a portal into the ADM application. Because of that, you should be cautious about which users have access to the embedded content. When you embed from another workspace there is no authentication taking place.

The security model relies on parameter validation instead. The get_item_values function in the adm_embed_api package generates a URL with parameters that also include checksums computed with a secret key. This ensures that the parameters cannot be easily tampered with.

We highly recommend keeping the default expiration settings in the get_or_create_document_token and get_or_create_folder_token functions. This ensures that the tokens expire after a certain period, reducing the risk of unauthorized access.