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.
Note: External actions is available as a technical preview.
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.
Note: Work with external actions requires relevant permissions. For details, see Roles and permissions.
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.
Steps for creating an external action
An external action consists of two parts: A JSON configuration object and the code.
JSON configuration object
The action's configuration is defined by a JSON object. The object describes the external action's properties, such as the entity type that the external action operates on, and the icon that represents the action in the UI. Some properties are relevant to custom toolbar buttons and sidebar plugins, while some properties are relevant to only one of the external action types.
The JSON structure also specifies the entities and fields that the external action will operate on.
For details, see Define the external action in ALM Octane.
The external action code
-
In the case of a custom button, the external action may open the item on another tool or launch an organizational website.
In the case of a sidebar plugin, the external action will embed a web page in designated ALM Octane sidebars.
-
You can upload the code to ALM Octane, or host it on an external server.
-
For details on uploading the code to ValueEdge and ALM Octane, see Host external actions in ALM Octane.
-
If you host the code on an external server, you need to establish trust between the ALM Octane server and the external server. For details, see Use CORS for external actions.
-
-
To interact with data from ALM Octane, the code can include REST API requests. For details, see The REST API.
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:
- Log in to ALM Octane as a Shared Space admin.
-
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.
-
For details on the JSON properties, see JSON structure.
JSON structure
Following are JSON samples for a custom button and a sidebar plugin. The properties are described in the table below.
[
{
"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"
}
]
[
{
"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:
Property | Description |
---|---|
name | Unique action or tab name, used for identification in logs and errors. |
mode |
For sidebars only, optional: Includes two properties:
|
title |
For toolbars where the icon and label are displayed, this value will be used as the button label. For toolbars where only the icon is displayed, this value will be used as the button tooltip. For sidebar plugins, this value will be used as the sidebar name. |
entity_type |
List of entity types to which the external action will be applied. The entity type names are same as in the REST API. For example: defect, test, release You can use also aggregated types, such as work_item. The action will be applied to all subtypes of the aggregated type. For example: Define the type work_item to apply the action to user stories, defects. |
views |
The view types in which the action or sidebar should be displayed. Allowed values for custom buttons: list, details Allowed values for sidebar plugins: list |
icon | The icon to be displayed for the button or sidebar. See the list of possible Icons. |
single_entity |
Use one of the following values:
|
dialog |
For custom buttons only: By default, the referenced website or application opens in a new tab. To embed an application inside an ValueEdge and ALM Octane dialog box, rather than a new tab, define the dialog property. Allowed values: small, medium, large Caution: Embedding an action can pose security risks for ALM Octane users if the embedded application is not properly secured. If dialog is defined, the url property (see below) needs to contain the source of an iframe that will open inside the dialog box. The embedded application can trigger events that control its dialog box, via "messages". A message will be handled by ValueEdge and ALM Octane only if the values of workspace, shared_space and dialog_id are identical to those that were provided to the embedded application. Any other values will cause the message to be ignored. For message examples, see Create external actions. |
url |
Custom button: The URL or URI to be activated when a user interacts with the custom button. Sidebar or dialog box: The source of the iframe. Provide one of the following:
In addition to the URL or URI of the target application, you can also include tokens. Tokens represent information regarding the selected entities. During runtime, ALM Octane replaces the tokens with the actual values and transfers them to the target application. The following example demonstrates the usage of tokens that you can include in the url property:
You can include part or all of the supported tokens in the URL. It is best to include only the tokens that are required by the invoked application. In addition, you can add other query parameters to the URL to send additional information to the target application. In the example above, we added For a list of the supported URL parameters, see Supported URL tokens. |
events |
Optional. Indicate whether the action supports receiving events back from the target web application. Allowed values: true / false Default: false. This functionality poses a potential security risk. For a list of supported events and code examples, see Supported events. |
workspaces |
Optional. When present, designates the workspaces to which the action applies. Syntax: Number array of workspace IDs. Example: Note: |
exclude_workspaces |
Optional. When present, designates the workspaces to which the action does not apply. Syntax: Number array of workspace IDs. Example: Note: |
modules | For sidebars only: The modules in which to show the sidebar plugin. For a list of the available modules, see the mode row above. |
You can include the following tokens in the URL
property:
Parameter | Details |
---|---|
{bundle_url}
|
When uploading the external action bundle as a zip, use this token as a replacement for the ALM Octane URL.
Where For more details, see Host external actions in ALM Octane. |
{entity.foo_field}
|
Any of the entity's fields (including UDF) of type String or Number. Relevant only if By including a field in the action's URL, you can navigate to specific items in external systems. For example, if you store in a UDF the ID of a ticket from an external system, you can use an external action to compose a URL to that ticketing system and include the ticket ID in the URL. Or if you synchronize entities from ALM to ALM Octane, and the ALM IDs are stored in a UDF, you can compose an external action that uses the ALM TD:// protocol in the URL to open the item directly in ALM. External actions that include fields will work on single entities only. |
{entity_ids}
|
Comma delimited list of IDs of the entity or entities selected by the user. |
{entity_type}
|
Aggregated type of the selected entity. For example, for a defect, this will be replaced with work_item. |
{octane_url}
|
URL of the ALM Octane site from which the external action is invoked. |
{panel_id}
|
In case of an action embedded in a dialog box or a panel, this value is required to post messages from the action back to ALM Octane. For more details, see Create external actions. |
{shared_space}
|
ID of space in which the action was triggered. |
{user_email}
|
Email address of user as recorded in ALM Octane. |
{user_login}
|
Login name with which the user connected to ALM Octane. |
{workspace}
|
ID of workspace in which the action was triggered. |
{xsrf_token}
|
Use this token in the following scenarios:
|
Supported events
You can send the following ValueEdge and ALM Octane events from the web application to the action:
Event | Description |
---|---|
octane_refresh_entity
|
Instruct ALM Octane to refresh specified items after they have been updated in the external application. |
octane_display_entity
|
Instruct ALM Octane to display details of a specified item. |
octane_entity_was_added
|
Notify ALM Octane that a new item was created. ALM Octane will display and take into account the new item where relevant, the same as it would had it been created inside ALM Octane. For example, when adding a new defect, if the defects grid is displayed, the defect will be displayed at the top of the grid. |
octane_refresh_list
|
Instruct ALM Octane to refresh the full grid after an update was made in the external application. |
octane_select_entity
|
Instruct ALM Octane to select specified entities in the grid. |
octane_set_dialog_title
|
If the external action opens a dialog box, use this event to set the dialog box's title. |
octane_close_dialog
|
If the external action opens a dialog box, use this event to close the dialog box. |
octane_read_settings
|
Query ALM Octane for the current user's settings for the application or a specified module. The results are returned in JSON format. |
octane_update_settings
|
Add a new value to the ALM Octane settings. The value will be stored in the "text" key. |
octane_report_error
|
Instructs ALM Octane to add an entry to its errors log. |
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.
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, '*');
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.
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',
},
}
Icons
Choose an icon from the list below to use for the custom button or sidebar.
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:
- Make sure the following CORS parameters are enabled and configured: CORS_ENABLED, CORS_ALLOW_ORIGIN, CORS_AUTH_ALLOW_ORIGIN, CORS_MAX_AGE
-
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",
...
});
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.
Version availability: In versions 16.0.100 and 16.0.200 all the uploaded external actions need to be bundled in the same zip file. From version 16.0.300, you can 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 on working with parameters, see Configuration parameters.
To upload external actions to ALM Octane:
-
Define the action in the external action editor, using the JSON syntax. For details, see Define the external action in ALM Octane.
-
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.
-
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.
-
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. -
REST API for external actions
The following examples demonstrate GET and PUT scripts for reading and updating external actions.
GET https://alm-octane.example.com/api/shared_spaces/1001/external-entity-actions
HEADERS:
- ALM-OCTANE-TECH-PREVIEW: true
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',
}
);
See also: