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 Core Software Delivery Platform through URL parameters, such as selected entity IDs, workspace, and user info.

The plugin can use OpenText Core Software Delivery Platform's REST API to read and update data, and trigger UI behavior in OpenText Core Software Delivery Platform 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 Core Software Delivery Platform data, include REST API calls in the plugin code. See REST API integration.

3. Handle supported events

   If posting events back to OpenText Core Software Delivery Platform, 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 Core Software Delivery Platform, the plugin code can include REST API requests.

• If the plugin is hosted on an external server, trust must be established between OpenText Core Software Delivery Platform 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 Core Software Delivery Platform 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 Core Software Delivery Platform 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

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.

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.

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.

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.

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 Core Software Delivery Platform 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

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

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 Core Software Delivery Platform 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):

{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

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 Core Software Delivery Platform.

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 Core Software Delivery Platform'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

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.

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

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.

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

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

See also

• External actions

• REST API