Share this page

# Sidebar plugins

You can develop sidebar plugins and display them in custom sidebars alongside grids and in the details view.

In this topic:

## Sidebar plugins overview

A sidebar plugin is a web page embedded in a sidebar pane that can interact with a single or multiple items in the grid view, or with a single item in the details view.

The sidebar plugin receives runtime context from OpenText Software Delivery Management through URL parameters, such as selected entity IDs, workspace, and user info.

The plugin can use OpenText Software Delivery Management's REST API to read and update data, and trigger UI behavior in OpenText Software Delivery Management using a set of supported events.

All main entity types are supported, including requirements, features, and tests.

You can add them to all grid and details views that already include pane sidebars, such as Filter and Preview. For example, you can develop a plugin that contains a link to a Teams channel related to the selected feature, or a sketch board whose contents are added as attachments to the feature.

Sidebar plugins are a type of external action. For general external action guidelines, see External actions.

## Top-level workflow

1. Build the sidebar plugin

   Implement the plugin as a web page suitable for iframe embedding.

2. Integrate with the REST API

   To interact with OpenText Software Delivery Management data, include REST API calls in the plugin code. See REST API integration.

3. Handle supported events

   If posting events back to OpenText Software Delivery Management, implement message posting logic using `window.parent`. See Supported events.

4. Create the sidebar plugin JSON configuration object

   Add required and optional properties, including the URL that loads the plugin web page. See JSON object.

5. Add runtime URL parameters

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

6. Deploy the sidebar plugin

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

## The external app

The sidebar plugin is a web page loaded in the sidebar pane.

### Architecture context

- To interact with data from OpenText Software Delivery Management, the plugin code can include REST API requests.

- If the plugin is hosted on an external server, trust must be established between OpenText Software Delivery Management and the external server using the CORS mechanism. For details, see CORS for external actions.

- If the plugin has a backend and needs to verify the identity of the invoking user, see User verification for external actions.

## Supported events

The sidebar plugin can send instructions back to OpenText Software Delivery Management using a set of supported events.

In practice, this means:

- The sidebar plugin loads alongside a grid or details view.

- The plugin performs an action, such as reading or updating entity data via REST API.

- The plugin posts an event message so that OpenText Software Delivery Management refreshes the UI or navigates to an entity.

### Preconditions and transport

- Since sidebar plugins always run inside an iframe, post messages using `window.parent`.

- Include the expected context values in each message (`shared_space`, `workspace`, and `panel_id` where relevant), so the host can accept and route the message.

### Supported events for sidebar plugins

Event | Purpose
--- | ---
`octane_refresh_entity` | Instruct OpenText Software Delivery Management to refresh specified entities after they were updated in the plugin.
`octane_display_entity` | Instruct OpenText Software Delivery Management to open/display the details of a specified entity.
`octane_entity_was_added` | Notify OpenText Software Delivery Management that a new entity was created so it is displayed where relevant (as if it were created in OpenText Software Delivery Management).
`octane_refresh_list` | Instruct OpenText Software Delivery Management to refresh the full grid/list after updates made in the plugin.
`octane_select_entity` | Instruct OpenText Software Delivery Management to select specified entities in the grid/list.
`octane_read_settings` | Query the current user's settings for the application or a specified module. Results are returned in JSON.
`octane_update_settings` | Add/update a value in settings (stored in the `text` key).
`octane_report_error` | Instruct OpenText Software Delivery Management to add an entry to its errors log.

Note: If an entity is currently being edited with unsaved changes, some refresh operations may be intentionally suppressed to prevent data loss.

### Code examples

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

#### Refresh specific entities

The plugin updates specific entities and reflects those changes in the grid or details view.

Copy code

    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.parent.postMessage(message, '*');

#### Refresh the full list

The plugin makes bulk changes and reloads the entire grid.

Copy code

    var message = {
      event_name: 'octane_refresh_list',
      shared_space: params.shared_space,
      workspace: params.workspace,
      data: {
        entity_type: 'work_item',
      },
    };

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

#### Select entities in the grid

The plugin identifies entities that should be highlighted in the host grid.

Copy code

    var message = {
      event_name: 'octane_select_entity',
      shared_space: params.shared_space,
      workspace: params.workspace,
      data: {
        entity_type: 'work_item',
        entity_id: '1050',
      },
    };

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

#### Display an entity's details

The plugin triggers navigation to an entity's details view.

Copy code

    var message = {
      event_name: 'octane_display_entity',
      shared_space: params.shared_space,
      workspace: params.workspace,
      data: {
        entity_type: 'work_item',
        entity_id: '1050',
      },
    };

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

## JSON object

The JSON object is the action definition that tells OpenText Software Delivery Management how a sidebar plugin should be exposed and loaded. It defines the modules where the sidebar appears, the plugin URL, and how runtime context is passed to the plugin.

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.

### Sidebar plugin JSON example

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}#entity_ids={entity_ids}&entity_type={entity_type}&query={query}",
      "mode": {
        "name": "side_panel",
        "modules": ["pipelines"]
      }
    }

### JSON property reference

Property | Purpose | Notes
--- | --- | ---
`name` | Required. Unique action name for identification/logging. | Keep stable once used.
`title` | Required. Label displayed for the sidebar tab. |
`entity_type` | Required. Entity types the sidebar applies to. | REST entity names; aggregated types like `work_item` supported.
`views` | Required. Where the sidebar appears. | Allowed: `list`, `details`.
`url` | Required. URL of the web page loaded in the sidebar iframe. Can include URL tokens for runtime context. The executable entry file should be referenced from `url`. See Runtime URL parameters. |
`mode.name` | Required. Must be set to `"side_panel"`. |
`mode.modules` | Required. Modules in which the sidebar is made available. | Available values: `defects`, `vulnerabilities`, `requirements`, `model_based_testing`, `backlog`, `team_backlog`, `quality`, `pipelines`, `releases`, `milestones`, `processes`, `my_work_entityType`.
`icon` | Icon shown for the sidebar tab. | Choose from supported icon set.
`single_entity` | Selection constraint. | `true` = one selected item only, `false` = one or many, `null` = even none selected.
`workspaces` | Allow-list of workspace IDs. | Cannot be used with `exclude_workspaces`.
`exclude_workspaces` | Deny-list of workspace IDs. | Cannot be used with `workspaces`.

## Runtime URL parameters

The parameterized URL is the handoff contract between the sidebar plugin definition and the loaded web page.

You write the parameterized `url` once in the plugin JSON. At runtime, OpenText Software Delivery Management replaces these placeholders with actual context values before loading the plugin. The sidebar page then receives a regular URL with concrete parameter values.

Example parameterized `url` value (with selection-related parameters passed as hash parameters to avoid reloads on selection change — see Advanced guidelines):

Copy code

    {bundle_url}/external-details/external-details.html?shared_space={shared_space}&workspace={workspace}&user_login={user_login}&email={user_email}&octane_url={octane_url}#entity_ids={entity_ids}&entity_type={entity_type}&query={query}

### Supported URL parameters

Parameter | Purpose
--- | ---
`{entity_ids}` | Comma-delimited list of selected entity IDs. Limited to first 500 items when all items are selected in a grid or board view or when no items are selected.
`{entity_type}` | Aggregated type of the selected entity (for example, defect becomes `work_item`).
`{query}` | REST filter representing the current grid/board view. Particularly useful when Select all is active or when >500 items are selected, as it retrieves all matching items rather than being capped at 500.
`{all_selected}` | Boolean value (`true` or `false`) indicating whether all items in the current view are selected. Helps determine if `entity_ids` is limited to the first 500 items.
`{shared_space}` | ID of the space in which the action was triggered.
`{workspace}` | ID of the workspace in which the action was triggered.
`{user_login}` | Login name with which the invoking user connected to OpenText Software Delivery Management.
`{user_email}` | Email address of the invoking user as recorded in OpenText Software Delivery Management.
`{octane_url}` | Base URL of the OpenText Software Delivery Management site from which the action is invoked.
`{xsrf_token}` | Security token for PUT, POST, and DELETE REST requests. For details, see CORS for external actions.
`{user_identity_token}` | JWT token that lets the plugin verify the identity of the invoking OpenText Software Delivery Management user. For details, see User verification for external actions.

## Advanced guidelines

### React to selection changes without reloading

There are two ways to pass parameters to the sidebar plugin: as query parameters or as hash parameters.

- Query parameters:: `...index.html?entity_ids={entity_ids}`

  Using query parameters each time `entity_ids` changes causes the plugin to reload. This can negatively affect the user experience if loading and rendering the plugin UI takes time.

- Hash parameters: `...index.html#entity_ids={entity_ids}`

  Using hash parameters does not reload when `entity_ids` changes. Instead, subscribe to the `onhashchange` event to react to parameter updates:

  Copy code

      window.onhashchange = function () {
        const hashParams = document.location.hash.substring(1).split('&');
        for (let pair of hashParams) {
          const [name, value] = pair.split('=').map(value => decodeURIComponent(value));
          console.log(`parameter name: ${name} parameter value: ${value}`);
        }
      }

Recommendation: Pass stable, session-scoped parameters (such as `shared_space`, `workspace`, `user_login`) as query parameters, and pass selection-specific parameters (such as `entity_ids`, `entity_type`, `query`) as hash parameters.

### Use Chrome local overrides for development

Chrome's local overrides feature lets you serve local files in place of live network requests. This allows you to edit your plugin files from your IDE and see changes applied instantly in the browser, without re-uploading the bundle to OpenText Software Delivery Management.

To use local overrides:

1. Open Chrome DevTools > Sources > Overrides.

2. Select a local folder to store overrides.

3. In the Network tab, right-click the plugin's HTML response and select Override content.

4. Edit the local file; Chrome applies changes immediately on reload.

## REST API integration

Sidebar plugins can use OpenText Software Delivery Management's REST API to read and update entity data directly from the plugin's JavaScript code. The interactive API client allows you to experiment with the API on your shared space data and make API calls from within the UI. For details, see Interactive API client. For full details on the REST API, see REST API.

### Read a field value

Copy code

    async function getFeature(entityId) {
      const response = await fetch(
        `/api/shared_spaces/${params.shared_space}/workspaces/${params.workspace}/work_items/${entityId}?fields=name,wsjf_cod,rroe,job_size`
      );
      const entity = await response.json();
      return entity;
    }

### Update a field value

Include the `XSRF-HEADER` in mutating requests. The XSRF token is passed to the plugin via the `{xsrf_token}` URL parameter.

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',
      }
    );

Note: `XSRF-HEADER` is required when the plugin is hosted in OpenText Software Delivery Management itself, or when it is hosted on a separate server and communicates using CORS. For details, see CORS for external actions.

## Templates and examples

The following examples are available for download. Each example includes a zip bundle and a JSON configuration file to copy into the external action editor.

Example | Description
--- | ---
feature_work_items.zip | Lists work items belonging to the selected feature. Use feature_work_items.json for the configuration in the external action editor.
external_details.zip | Showcases all plugin APIs. Recommended as a template for starting a new plugin project. Use external-details.json for the configuration in the external action editor.
external_panel_template.zip | Empty plugin with no content. Use as a starting point for a new plugin. Use external-details.json for the configuration in the external action editor.
external_panel_wsjf.zip | Plugin with an example of updating a field via REST API. Use external_panel_wsjf.json for the configuration in the external action editor.

The `index.html` files in the examples reference a stylesheet that aligns the plugin's look and feel with OpenText Software Delivery Management's own styles:

Copy code

    <link rel="stylesheet" type="text/css" href="/ui/external-actions/style/alm-octane-style.css" />

## See also

- External actions

- REST API

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: