JSON structure

This page includes JSON examples for all types of external actions. It also describes the properties and the supported URL tokens.

Toolbar button notes

Note the particular JSON property usages for custom toolbar buttons:

Property	Details
title	The button's label or tooltip.
url	The address of the web application that runs when the button is pressed.

For a full list of the JSON object properties, see JSON properties.

JSON example for a custom toolbar button

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

Aviator chip notes

Note the particular JSON property usages for custom Aviator chips:

Property	Details
title	The chip's display label.
tooltip	An extended description of the chip that displays on hover over.
mode.name	Enter aviator_chat.
mode.prompt	The prompt text that is fed to Aviator. The text in the mode.prompt property can be up to 1500 characters long. For longer prompts, you can save the prompt in a text file, and reference the uploaded file in the url property.
url	If you use an external text file for the prompt, the property refers to the file's path in the bundle. In a custom Aviator chip JSON object, use either the url or the mode.prompt property for the prompt.

For a full list of the JSON object properties, see JSON properties.

JSON example for a custom Aviator chip

Copy code

[
  {
    "name": "perform-coverage-analysis",
    "title": "Perform coverage analysis",
    "entity_type": [
      "feature"
    ],
    "views": [
      "details"
    ],
    "tooltip": "Analyze existing tests coverage on feature functionality including all related entities",
    "mode": {
      "name": "aviator_chat",
      "prompt": "perform coverage analysis, specify which test is covering which backlog item and whether there is a functionality specified that is not covered by any test."
    },
    "single_entity": true
  },
  {
    "name": "suggest-feature-specification-completions-demo-action",
    "title": "Suggest feature specification completions",
    "entity_type": [
      "feature"
    ],
    "views": [
      "details"
    ],
    "url": "{bundle_url}/whats-new-section.txt",
    "tooltip": "Suggest missing sections in the Feature specification",
    "mode": {
      "name": "aviator_chat"
    },
    "single_entity": true
  }
]

Sidebar plugin notes

Note the particular JSON property usages for sidebar plugins:

Property	Details
title	The sidebar's display label.
mode.name	Enter side_panel.
mode.modules	The modules in which the sidebar is made available.
url	The address of the web application that loads in the sidebar.

For a full list of the JSON object properties, see JSON properties.

JSON example for a sidebar plugin

Copy code

[
  {
    "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"
      ]
    }
  }
]

JSON 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: Includes the following properties: "name": "side_panel" or "dialog" "modules": The modules in which to display the sidebar plugin. Available modules are: defects, vulnerabilities, requirements, model_based_testing, backlog, team_backlog, quality, pipelines, releases, milestones, processes, my_work_entityType For Aviator chips: Includes the following properties: "name": "aviator_chat" "prompt": "<text prompt for Aviator to process>"
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: list, details
icon	The icon to be displayed for the button or sidebar. See the list of possible JSON structure.
single_entity	Use one of the following values: true. To determine that the action is available only when a single item is selected in the grid and unavailable when multiple items are selected. false. To determine that the action is available both when a single or multiple items are selected. null. To determine that the action is available 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 a 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 users if the embedded application is not properly secured. If dialog is defined, the url property 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, through "messages". A message is handled 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 JSON structure.
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, the tokens are replaced with the actual values which are hen transferred 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, `action=defect-details` was added 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 JSON structure.
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.

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 OpenText Core Software Delivery Platform 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 JSON structure.
`{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 browse 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. If you synchronize entities from OpenText Application Quality Management to OpenText Core Software Delivery Platform, and the OpenText Application Quality Management IDs are stored in a UDF, you can compose an external action that uses the OpenText Application Quality Management TD:// protocol in the URL to open the item directly in OpenText Application Quality Management. 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. This filter is sent 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 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 the 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. It will fetch a full list of item IDs that should be affected by the external action.
`{octane_url}`	URL of the OpenText Core Software Delivery Platform 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 OpenText Core Software Delivery Platform. For more details, see JSON structure.
`{shared_space}`	ID of the space in which the action was triggered.
`{user_email}`	Email address of a user as recorded in OpenText Core Software Delivery Platform.
`{user_login}`	Login name with which the user connected to OpenText Core Software Delivery Platform.
`{user_identity_token}`	Use this token to allow external applications to validate the identity of the OpenText Core Software Delivery Platform user that invoked an external action. For details, see JSON structure.
`{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 OpenText Core Software Delivery Platform server. For details, see JSON structure. If you are hosting the external action in OpenText Core Software Delivery Platform and are making PUT, POST, or DELETE REST requests, you must pass this token value back to OpenText Core Software Delivery Platform.