Create external actions

You can create external actions and embed them in the ValueEdge and 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 will be added to the toolbar of an entity 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, we added a custom action labeled General Details 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 the external action in ALM Octane

You add external actions by configuring a JSON file in the External Action editor.

To define an external action:

1. Log in to ALM Octane as a Shared Space admin.

2. From the main ALM Octane user area, select Settings > Management > External action editor.

   The editor allows you to write or paste JSON code that represents the custom buttons or sidebar plugins that you are adding to ALM Octane.

   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.

3. 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 are described in the table 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 ValueEdge and 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

Use CORS for external actions

If your external actions are hosted on a domain other than ValueEdge and 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:

• Set CORS configuration parameters.
• Send 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 on working with parameters, 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.

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 on working with parameters, 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 the external action in ALM Octane.

2. Click Upload Bundle.

   Version 16.0.300: 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.

   Version 16.0.300: 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:

   • Actions in individual files:

     Copy code

     "url": {bundle_url}/api/sharedspaces/1001/external_actions/<action_name>/bundle/foo.html

   • Actions in bundled files: 

     Copy code

     "url": {bundle_url}/api/sharedspaces/1001/external_actions/bundle/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