Create external actions

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

Note: External actions are available as 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 space admin permissions. For details, see Roles and permissions.

Custom toolbar button overview

You can create a custom action that is added to the toolbar of an item in ValueEdge. 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

External action's structure

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 operates on.

For details, see Define external actions in ValueEdge.

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 embeds a web page in designated ValueEdge sidebars.

  • You can upload the code to ValueEdge, or host it on an external server.

  • To interact with data from ValueEdge, the code can include REST API requests. For details, see REST API.

Back to top

Define external actions in ValueEdge

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 ValueEdge'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 ValueEdge.
  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.

Note: If you upload a zip bundle, and not define the JSON object directly in the External action editor, do not use square brackets [...] to introduce an array. You cannot define arrays of configurations when uploading a zip bundle.

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:

  • name: "side_panel" or "dialog"

  • modules: The modules in which to show the sidebar plugin. Available modules are: defects, vulnerabilities, requirements, model_based_testing, backlog, team_backlog, quality, pipelines, releases, milestones, processes, my_work_entityType

title

For toolbars where the icon and label are displayed, this value is used as the button label.

For toolbars where only the icon is displayed, this value is used as the button tooltip.

For sidebar plugins, this value is used as the sidebar name.

entity_type

List of entity types to which the external action is 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 is 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:

  • true. To determine that the action is enabled only when a single item is selected in the grid and disabled when multiple items are selected.

  • false. To determine that the action is enabled both when a single or multiple items are selected.

  • null. To determine that the action is enabled regardless of the selection, including when nothing is selected.

dialog

For custom buttons only: By default, the referenced website or application opens in a new tab.

To embed an application inside an ValueEdge 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 ValueEdge 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 is open inside the dialog box.

The embedded application can trigger events that control its dialog box, via "messages". A message is handled by ValueEdge 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 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:

  • A website, using either the https: or http: protocol.
  • For custom buttons only: A protocol handler URI, such as mailto: or any custom application that has a registered protocol handler on the user's machine.

    By default, URI is restricted to common web-based protocols such as https and mailto. To allow additional protocols, update the ENTITY_EXTERNAL_ACTIONS_SUPPORTED_PROTOCOLS site parameter. For details, see Configuration parameters.

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, ValueEdge 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:

https://server.domain.com/some-application?entity_ids={entity_ids}&foo_bar={entity.foo_udf}&entity_type={entity_type}&shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&action=defect-details

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 action=defect-details as a query parameter. It allows the target application to recognize the custom action that was activated.

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: "workspaces": [1002, 1004]

Note: workspaces can be supplied only if exclude_workspaces is not supplied.

exclude_workspaces

Optional. When present, designates the workspaces to which the action does not apply.

Syntax: Number array of workspace IDs. Example: "exclude_workspaces": [1002, 1004]

Note: exclude_workspaces can be supplied only if workspaces is not supplied.

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.

Supported URL tokens

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 ValueEdge URL.

"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}"

Where my_folder is the folder located under the root of the zip file uploaded as the external actions bundle.

For more details, see Host external actions in ValueEdge.

{entity.foo_field}

Any of the entity's fields (including UDF) of type String, Number, Boolean, and Date.

Relevant only if single_entity=true.

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 ValueEdge, 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 work on single entities only.

Two levels are supported, for example {entity.release.name}.

{entity_type} Aggregated type of the selected entity. For example, for a defect, this is replaced with work_item.
{entity_ids}

Comma-delimited list of IDs of the entity or entities selected by the user.

Note: When using the entity_ids token in a grid or board view with no selected items, or when the Select all option is active, the token returns only the IDs of the first 500 items.

{query}

The query token represents a REST filter. ValueEdge sends this filter to the server as part of a GET request that is responsible for displaying the data in a grid or board view.

External actions can use this token to construct a REST request to ValueEdge to fetch the items displayed in a grid or board view.

This token is particularly useful when invoking an external action in a grid or board view with no selected items, or when the Select all option is active. The reason is that when using the entity_ids token, and all the items are selected, the token returns only the IDs of the first 500 items, while the whole selection can include thousands of items.

{all_selected}

External actions can use the all_selected={all_selected} query parameter as part of the url property to understand whether an external action is invoked on all selected items in ValueEdge's grid or board view.

The all_selected parameter has a boolean value of true or false. This value indicates whether all items are selected in the current view.

This parameter is useful in the following case:

When an external action is invoked, and there are more than 500 selected items, only the first 500 item IDs are returned as part of the entity_ids parameter.

If you receive 500 item IDs, this may indicate that more than 500 items can be selected in the view. You can verify this with the all_selected parameter value. If all_selected returns true, then the current view probably includes more than 500 selected items.

In this case, the all_selected parameter value helps determine whether to use the entity_ids parameter or the query parameter. For example, to get a full list of selected item IDs, that exceeds 500 IDs, use the query parameter to issue a request to ValueEdge. It will fetch a full list of item IDs that should be affected by the external action.

{octane_url}

URL of the ValueEdge 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 ValueEdge. For more details, see Create external actions.

{shared_space} ID of the space in which the action was triggered.
{user_email} Email address of a user as recorded in ValueEdge.
{user_login} Login name with which the user connected to ValueEdge.
{user_identity_token}

Use this token to enable external applications to validate the identity of the ValueEdge user that invoked an external action. For details, see Verify ValueEdge user identity.

{workspace}

ID of a workspace in which the action was triggered.

{xsrf_token}

Use this token in the following scenarios:

  • If you are hosting the external action on another domain and are planning to use CORS to communicate with the ValueEdge server. For details, see Use CORS for external actions.

  • If you are hosting the external action in ValueEdge and are making PUT, POST, or DELETE REST requests, you need to pass this token value back to ValueEdge.

Back to top

Supported events

You can send the following ValueEdge events from the web application to the action:

Event Description
octane_refresh_entity

Instruct ValueEdge to refresh specified items after they have been updated in the external application.

octane_display_entity Instruct ValueEdge to display details of a specified item.
octane_entity_was_added

Notify ValueEdge that a new item was created. ValueEdge displays and takes into account the new item where relevant, the same as it would had it been created inside ValueEdge.

For example, when adding a new defect, if the defects grid is displayed, the defect is displayed at the top of the grid.

octane_refresh_list

Instruct ValueEdge to refresh the full grid after an update was made in the external application.

octane_select_entity Instruct ValueEdge 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 ValueEdge 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 ValueEdge settings. The value will be stored in the "text" key.
octane_report_error Instructs ValueEdge 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 ValueEdge 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.

Back to top

Icons

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

Tip: To view in full detail, click to zoom in, then right-click the image and open in a new tab.

Back to top

Verify ValueEdge user identity

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

External actions can do the following:

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 ValueEdge 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.

Note: For GDPR compliance, when using the {user_identity_token}, an ValueEdge user must agree to share their identity information.

The {user_identity_token} contains the following information:

Property Details
name Username of the ValueEdge user.
email Email of the ValueEdge user.
iat Unix time, in seconds, that represents the token issue date.
exp Unix time, in seconds, that represents the token expiration date.

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: Enable ValueEdge to support CORS by setting the CORS_ENABLED parameter to true. This lets an external action make requests to ValueEdge 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 ValueEdge 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 ValueEdge 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 ValueEdge 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 ValueEdge can verify an ValueEdge user's identity using the CORS request.

To verify the user identity using the CORS request:

  1. Enable ValueEdge 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 enable an external action to send requests from the external action's web application to the ValueEdge 's server using the current authentication context, established when the user signed in ValueEdge.

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.

Example: {"id": "<userid>", "email": "<user@email.com>", "name": "<username>" //user name in ValueEdge}

Back to top

Use CORS for external actions

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

Copy code
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 ValueEdge

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

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 ValueEdge:

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

  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.

    ValueEdge creates an internal guid for the action and adds the guid to the external action definition in the JSON.

  1. 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 ValueEdge'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.

Back to top

See also: