Create external actions

You can create external actions and embed them in the ALM Octane UI. External actions can launch external websites or applications that interact with ALM Octane.

In this topic:

Overview

You can create two types of external actions: custom toolbar buttons and sidebar plugins.

The current topic provides information that applies to both types of external actions. For specific sidebar plugin guidelines, see Create sidebar plugins.

Custom toolbar button overview

You can create a custom action that is added to the toolbar of an item in ALM Octane. The button can be added either to the grid view, to operate on a single or multiple items, or to the details view, to operate on a single item.

Example:

In this case, a custom action labeled General Details was added to the defects grid toolbar. When clicked, the action opens an external website that lists the defects selected in the grid.

Back to top

Back to top

Define external actions in ALM Octane

You can define external actions in the following ways:

• By uploading a zip bundle with a pre-configured JSON file
• By configuring a JSON file directly in the External action editor

Define an external action with a zip bundle

Add an external action by uploading a zip bundle with a pre-configured JSON file to the ALM Octane's External action editor.

Prerequisites:

• Ensure that a zip bundle includes a pre-configured JSON file named action-configuration.

  The file must contain the configuration that you could paste in the External action editor when using the alternative method of defining an action directly in the editor.

• Ensure that the configuration file includes only one valid configuration. This means that when defining a JSON configuration object, you cannot use square brackets [...] to introduce an array. You cannot define arrays of configurations when uploading a zip bundle.

To upload a zip bundle:

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

2. In the External action editor, click Upload Bundle .
3. In the Upload Bundle for Action dialog box, in the Upload Purpose field, select Upload New Action.
4. Click Select bundle .

5. Locate and add a zip bundle of a new action, and click OK.

   The configuration of a new action is displayed in the external editor.

Define an external action in the editor

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

To define an external action in the editor:

1. In the External action editor, write or paste the JSON code that represents a custom button or a sidebar plugin that you are adding to ALM Octane.
2. Click Save .

   Tip: Click Load Demo to load JSON code with examples of various configuration options for the external actions.

   The JSON file can include code for one or more external actions. For details on the JSON properties, see JSON structure.

Back to top

JSON structure

Following are JSON samples for a custom button and a sidebar plugin. The properties and the supported URL tokens are described in the tables below.

Custom toolbar button JSON sample

Copy code

[
    {
        "name": "defect-details",
        "title": "Defect Details",
        "entity_type": ["defect"],
        "views": ["list", "details"],
        "icon": "rss",
        "url": "https://server.domain.com/some-application?entity_ids={entity_ids}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&action=defect-details",
        "single_entity": true,
        "events": false,
        "dialog": "large"
    }
]

Sidebar plugin JSON sample

Copy code

[
  {
    "name": "general-details-in-panel",
    "title": "Custom Preview",
    "entity_type": [
      "work_item",
      "test"
    ],
    "views": [
      "list"
    ],
    "icon": "details",
    "url": "{bundle_url}/external-details/external-details.html?shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&octane_url={octane_url}&context_release={context_release}&context_sprint={context_sprint}&context_milestone={context_milestone}&context_program={context_program}#entity_ids={entity_ids}&entity_type={entity_type}&query={query}",
    "mode": {
      "name": "side_panel",
      "modules": [
        "backlog",
        "team_backlog"
      ]
    }
  },
  {
    "name": "pipeline-details",
    "title": "Pipeline Preview",
    "entity_type": [
      "run_history"
    ],
    "views": [
      "list"
    ],
    "icon": "details",
    "url": "{bundle_url}/external-details/external-details.html?shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&octane_url={octane_url}&context_program={context_program}&context_pipeline={context_pipeline}&context_pipeline_run={context_pipeline_run}#entity_ids={entity_ids}&entity_type={entity_type}&query={query}",
    "mode": {
      "name": "side_panel",
      "modules": [
        "pipelines"
      ]
    }
  }
]

Custom action properties

Include the following properties in the action definition:

Supported URL tokens

You can include the following tokens in the URL property:

Back to top

Supported events

You can send the following ALM Octane 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, messages should be posted using window.opener.
• For actions embedded inside an ALM Octane dialog box, messages should be posted 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 via the url parameter.

octane_set_dialog title

Copy code

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, '*');

octane_close_dialog

Copy code

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

Set refresh: true in the message to instruct ALM Octane to refresh the displayed view. This can cause either the grid view or the details view to refresh, depending on the view from which the action was triggered.

octane_refresh_entity

Copy code

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, '*');

octane_display_entity

Copy code

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

octane_entity_was_added

Copy code

{
    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 ALM Octane user identity

Applications that interact with ALM Octane can verify if the user that invoked an external action is a user currently signed in ALM Octane.

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 ALM Octane user that invoked an external action.

The {user_identity_token} is a JSON Web Token (JWT). For details about the JSON Web Token data standard, see JSON Web Token.

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 ALM Octane to support CORS by setting the CORS_ENABLED parameter to true. This lets an external action make requests to ALM Octane 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 ALM Octane 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 ALM Octane 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. For details about JWTs and examples of JWT libraries, see JWT.
   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 from ALM Octane 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

Applications that interact with ALM Octane can verify an ALM Octane user's identity using the CORS request.

To verify the user identity using the CORS request:

1. Allow ALM Octane to support 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 ALM Octane 's server using the current authentication context, established when the user signed in ALM Octane.

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 ALM Octane, 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 ALM Octane 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 ALM Octane 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 in ALM Octane

As an alternative to storing external action code on an external server and establishing trust with ALM Octane, you can upload the external action code to ALM Octane.

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 to ALM Octane:

1. Define the action in the external action editor, using the JSON syntax. For details, see Define external actions in ALM Octane.

2. Click Upload Bundle.

   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.

   ALM Octane creates an internal guid for the action and adds the guid 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 ALM Octane'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

Copy code

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

Update external actions

Copy code

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:

• Create sidebar plugins