External actions

You can create external actions and embed them in the UI. External actions can launch external websites or applications that interact with OpenText Core Software Delivery Platform.

In this topic:

External action types

External actions can be created to add the following elements to the application: custom toolbar buttons, custom Aviator chips, and sidebar plugins.

The current topic provides information that applies to all types of external actions. For additional guidelines on creating sidebar plugins, see Sidebar plugins.

Back to top

Back to top

Create an external action

You can define external actions in the following ways:

• Upload a zip bundle that includes a JSON file and any accompanying code files.
• Add a JSON object in the External action editor in the UI, and reference remote code files.

Upload a zip bundle

The zipped bundle must include the following files:

• A JSON file named action-configuration. The file must include a single external action configuration.

  The JSON file must be at the top level of the zip.

• Code files implementing the external action. The executable file should be referenced from the url property in the JSON object.

To upload a zip bundle:

1. As a Shared Space admin, select Settings > Management > External action editor.

2. In the External action editor, click the Upload Bundle button .

   The Upload Bundle for Action dialog box opens.

3. In the Upload Purpose field, select Upload New Action.
4. Click the Select bundle button .

5. Locate the zip file, and click OK.

   The configuration of the new action is added to the existing objects in the external action editor.

Define an external action in the editor

Add an external action by creating a JSON object directly in the External action editor.

To define an external action in the editor:

1. As a Shared Space admin, select Settings > Management > External action editor.

2. Add a JSON external action object.

3. Click Save.

Back to top

Supported events

You can send the following OpenText Core Software Delivery Platform events from the web application to the action.

Implementation notes

• The code should be implemented in the target web application.
• For actions opened in a new browser tab, post messages using window.opener.
• For actions embedded inside a dialog box, post messages using window.parent.
• If the code fails on "opener undefined", check that the action is configured with "events": true.
• If a refresh event or a message is sent for an entity that is currently being edited by the user and has changes unsaved to the server, the UI will not refresh to prevent data loss.

Code examples

The following examples assume that params holds parameters that were sent to the external application using the url parameter.

var message = {
    event_name: 'octane_set_dialog_title',
    shared_space: '1004',
    workspace: '1006',
    data: {
        dialog_id: params.dialog_id,
        title: 'Our custom dialog title',
    },
};
window.parent.postMessage(message, '*');

var message = {
    event_name: 'octane_close_dialog',
    shared_space: '1004',
    workspace: '1006',
    data: {
        dialog_id: params.dialog_id,
        refresh: true,
    },
};
window.parent.postMessage(message, '*');

var message = {
    event_name: 'octane_refresh_entity',
    shared_space: '1004',
    workspace: '1006',
    data: {
        entity_type: 'work_item',
        entity_ids: ['1003', '4005'],
    },
};
window.opener.postMessage(message, '*');

{
    event_name: 'octane_display_entity',
    shared_space: '1004',
    workspace: '1006',
    data: {
        entity_type: 'work_item',
        entity_id: '1050',
    },
}

{
    event_name: 'octane_entity_was_added',
    shared_space: '1004',
    workspace: '1006',
    data: {
        entity_type: 'defect',
        entity_id: '1050',
    },
}

Back to top

Icons

Choose an icon from the list below to use for the custom button or sidebar.

Back to top

Verify user identity

Applications that interact with OpenText Core Software Delivery Platform can verify if the user that invoked an external action is a user currently signed in to OpenText Core Software Delivery Platform.

External actions can do the following:

• Verify user identity with a token

• Verify user identity using CORS authentication

Verify user identity with a token

You can configure an external action to send the {user_identity_token} to a target application as a query parameter. The target application can then use the token information to verify the identity of an OpenText Core Software Delivery Platform user that invoked an external action.

The {user_identity_token} is a JSON Web Token (JWT).

When using the token information, an external action does not need to send authentication requests to confirm the user identity.

The {user_identity_token} contains the following information:

To verify user identity with the token:

1. If you are verifying the token validity from an external action's web application, and not from the server, allow OpenText Core Software Delivery Platform to support CORS by setting the CORS_ENABLED parameter to true. This lets an external action make requests to OpenText Core Software Delivery Platform from the hosted iFrame.

   Skip this step when verifying the token validity from the server.

2. Configure an external action to support user identity tokens by adding the {user_identity_token} URL token to the action's url property.

   Following is a sample url configuration that uses the user_identity_token property:

   Example: "url": "{bundle_url}/my_folder/index.html?entity_ids={entity_ids}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&octane_url={octane_url}&dialog_id={dialog_id}&user_identity_token={user_identity_token}"

   When an OpenText Core Software Delivery Platform user clicks an action button, or a tab that displays the external action in an iFrame, a user identity token is generated and added to the external action invocation URL.

3. Confirm the identity of an OpenText Core Software Delivery Platform user:

   1. Extract user_identity_token from the request.
   2. Parse the user_identity_token and decode the token information using the Base64 decoder or any other third-party library that fits your programming paradigm.
   3. Verify the token expiration date.

   4. Verify the user_identity_token validity with the help of a public key. You can retrieve the key using the following API request: https://<octane.example.com>/api/jwt/key.

      Technical preview: This API is technical preview. When calling it, use the ALM-OCTANE-TECH-PREVIEW header.

      The RSA public key is returned as a Base64-encoded string.

   5. Using the public key, verify the token signature.

      Depending on the library you are using to verify the token signature, you may need to convert the key to the PEM format by adding the header and footer strings. Below is an example of JavaScript for the key PEM format.

      Example:  

      const {key: publicKey} = await response.json();

      const publicKeyInPEMFormat = '-----BEGIN PUBLIC KEY-----' + publicKey + '-----END PUBLIC KEY-----';

Verify user identity using CORS authentication

Interacting applications can verify a user's identity using the CORS request.

To verify the user identity using the CORS request:

1. Allow support for CORS by setting the CORS_ENABLED parameter to true.
2. Ensure the CORS_AUTH_ALLOW_ORIGIN parameter lists the external action server base URL.

3. Ensure the SAME_SITE_COOKIE_ATTRIBUTE parameter controlling cookies is set to none.

   For details, see Configuration parameters.

These settings allow an external action to send requests from the external action's web application to the OpenText Core Software Delivery Platform's server using the current authentication context, established when the user signed in to OpenText Core Software Delivery Platform.

To get the details of a currently signed-in user, such as a user ID and email, the external action can call https://octane.example.com/api/current_user.

Back to top

Use CORS for external actions

If your external actions are hosted on a domain other than OpenText Core Software Delivery Platform, you can establish trust by either using an API key in the code, or using the CORS mechanism.

This section discusses using the CORS mechanism for external actions.

The CORS mechanism for external actions involves the following:

• Setting CORS configuration parameters
• Sending an anti-CSRF cookie in requests

To enable CORS actions:

1. Make sure the following CORS parameters are enabled and configured: CORS_ENABLED, CORS_ALLOW_ORIGIN, CORS_AUTH_ALLOW_ORIGIN, CORS_MAX_AGE

2. Set the following site parameter:

   Parameter	Value
   SAME_SITE_COOKIE_ATTRIBUTE	None

   For details, see Configuration parameters.

To send an XSRF cookie in requests:

To prevent non-authorized servers from accessing the OpenText Core Software Delivery Platform server, requests from external servers need to include an XSRF header that sends a unique cookie.

Following is a sample code snippet for an XSRF header:

const xsrf = new URL(document.location.href).searchParams.get('xsrf_token')

await fetch(url, {
    headers: {
        "XSRF-HEADER": xsrf,
        "content-type": "application/json",
    },
    method: "PUT",
    ...
});

Back to top

Host external actions

As an alternative to storing external action code on an external server and establishing trust with OpenText Core Software Delivery Platform, you can upload the external action code to OpenText Core Software Delivery Platform.

You can upload all the external actions in the same zip file, or upload each external action in a separate file.

With bundled files, the different external actions can also use shared code. For example, if you have external actions foo and bar that reference shared code common, structure the folders as follows:

Prerequisites

• Make sure that the parameter SUPPORT_EXTERNAL_ENTITY_ACTIONS_BUNDLE is enabled.
• Configure the other external action parameters as required: EXTERNAL_ENTITY_ACTIONS_BUNDLE_MAX_SIZE, EXTERNAL_ENTITY_ACTIONS_FILE_EXTENSION_WHITE_LIST

For details, see Configuration parameters.

To upload external actions:

1. Define the action in the external action editor, using the JSON syntax. For details, see Create an external action.

2. Click the Upload Bundle button .

   In the Select Action dropdown list, select the name of the action whose code you want to upload, or select Common to upload a bundled file.

   Note: To replace a bundled zip that contains multiple actions, select Common.

3. Locate the zip file and upload it.

   An internal guid is created for the action, and the guid is added to the external action definition in the JSON.

4. In the external action editor, update the "url" property to point to the uploaded file, as follows: "url": {bundle_url}/foo.html

   {bundle_url} is a token denoting OpenText Core Software Delivery Platform's server address.

Back to top

REST API for external actions

The following examples demonstrate GET and PUT scripts for reading and updating external actions.

Get external actions

GET https://alm-octane.example.com/api/shared_spaces/1001/external-entity-actions
HEADERS:
 - ALM-OCTANE-TECH-PREVIEW: true

Update external actions

const entity = {
    fieldName: fieldValue,
};

const xsrf = new URL(document.location.href).searchParams.get('xsrf_token')

fetch(
    '/api/shared_spaces/' +
    sharedSpaceId +
    '/workspaces/' +
    workspaceId +
    '/work_items/' +
    entityId,
    {
        headers: {
            'content-type': 'application/json',
            'XSRF-HEADER': xsrf,
        },
        body: JSON.stringify(entityData) ,
        method: 'PUT',
        credentials: 'include',
    }
);

Back to top

See also:

• Sidebar plugins

• JSON structure