Custom toolbar buttons

You can add custom buttons to entity toolbars so users can launch external behavior in context of selected items.

In this topic:

Overview

A custom button can open an external web app (HTTP/HTTPS) or another registered desktop protocol-handler URI, such as mailto:.

The custom button passes runtime context from OpenText Core Software Delivery Platform to the target app through URL query parameters, for example: selected IDs, workspace, user info.

The web app invoked by the custom button can either open in a separate tab or be embedded as an iframe in an OpenText Core Software Delivery Platform dialog box.

The web app can use OpenText Core Software Delivery Platform's REST API to update data, and trigger UI behavior in OpenText Core Software Delivery Platform using a set of supported events.

Top-level workflow

1. Build the target implementation

   Implement the target web app or handler endpoint that receives query parameters/tokens.

2. Handle supported events

   Optionally, implement message posting logic in the target app using window.opener or window.parent. See Supported events.

3. Create the custom button JSON configuration object

   Add required and optional properties, including the tokenized URL that calls the target web app or endpoint. See JSON object.

4. Add runtime URL query parameters

   Optionally include URL tokens for runtime context, such as selected entity IDs, workspace, and user info. See Runtime URL query parameters.

5. Deploy the custom button

   Register the button as an external action, either by uploading a bundle or defining it in the external action editor. See External actions.

The external app

The custom button launches a browser-based external application.

Architecture context

• The external app runs independently from OpenText Core Software Delivery Platform.

• It can include UI logic, data processing, and integrations with other systems.

• To interact with data from OpenText Core Software Delivery Platform, the code can include REST API requests.

• If the external app is intended to open in a dialog box, it must be suitable for iframe embedding.

• The host passes runtime context (selection, workspace, user, URL tokens) to the app at launch time.

• The app can run in one of two ways:

  • Frontend-only: Suitable when required operations can be handled from client-side code.

  • External app with backend: Preferred for privileged operations, aggregation across systems, and restricted/internal integrations.

• Hosting model: The following hosting options are available:

  • UI-only apps with no backend can be uploaded to OpenText Core Software Delivery Platform or hosted on an external server.

  • Apps with a backend can only be hosted externally.

  • If hosted externally, trust must be established between the OpenText Core Software Delivery Platform server and the external server. For details, see CORS for external actions.

  • If the external app has a backend and needs to verify the invoking user, see User verification for external actions.

Supported events

The external application can send instructions back to OpenText Core Software Delivery Platform using a set of supported events.

In practice, this means:

• The custom button opens your target web app.

• Your app performs an action on an item, such as updating data or creating an item.

• Your app posts an event message so that OpenText Core Software Delivery Platform refreshes the UI, navigates, or closes/updates the dialog box.

Preconditions and transport

• In the custom button JSON, set events: true.

• For actions opened in a new browser tab, post messages using window.opener.

• For actions embedded in a dialog, post messages using window.parent.

• Include the expected context values in each message (shared_space, workspace, and dialog/panel identifier when relevant), so the host can accept and route the message.

Supported events for custom buttons

Code examples

Use these examples as implementation starters. Replace hardcoded values with runtime values in your app.

Your custom button opens in a dialog and sets a contextual title.

var message = {
  event_name: 'octane_set_dialog_title',
  shared_space: params.shared_space,
  workspace: params.workspace,
  data: {
    dialog_id: params.dialog_id,
    title: 'Defect Review',
  },
};

window.parent.postMessage(message, '*');

The action completes inside a dialog and refreshes the originating view.

var message = {
  event_name: 'octane_close_dialog',
  shared_space: params.shared_space,
  workspace: params.workspace,
  data: {
    dialog_id: params.dialog_id,
    refresh: true,
  },
};

window.parent.postMessage(message, '*');

The action opens in a separate tab and updates specific entities that should be refreshed in the host.

var message = {
  event_name: 'octane_refresh_entity',
  shared_space: params.shared_space,
  workspace: params.workspace,
  data: {
    entity_type: 'work_item',
    entity_ids: ['1003', '4005'],
  },
};

window.opener.postMessage(message, '*');

JSON object

The JSON object is the action definition that tells OpenText Core Software Delivery Platform how a custom button should be exposed and executed. It defines where the button appears, what it launches, what runtime context is passed, and whether the target app can send supported events back to the host UI.

The JSON object can either be part of the external application's locally hosted bundle, or added to the external action editor. For details, see External actions.

Dialog-based custom button example

{
  "name": "defect-review-dialog",
  "title": "Defect Review",
  "entity_type": ["defect"],
  "views": ["list", "details"],
  "icon": "details",
  "url": "https://server.domain.com/review?entity_ids={entity_ids}&workspace={workspace}&shared_space={shared_space}&dialog_id={dialog_id}",
  "single_entity": true,
  "events": true,
  "dialog": "large",
  "workspaces": [1002, 1004]
}

JSON property reference

By default, URL/URI use is restricted to common protocols like https and mailto. To allow additional protocols, configure site parameter ENTITY_EXTERNAL_ACTIONS_SUPPORTED_PROTOCOLS.

Runtime URL query parameters

The parameterized URL is the handoff contract between the custom button definition and your target application.

You write the parameterized url once in the button JSON. At runtime, OpenText Core Software Delivery Platform replaces these placeholders with actual context values before invoking the target URL. Your target application then receives a regular URL with concrete query values.

Example parameterized url value:

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

Supported URL parameters

Icons

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