Share this page

# Scripted widgets

You can create custom JavaScript-based widgets that integrate seamlessly into the dashboard widget gallery. Scripted widgets allow you to build specialized visualizations and reporting functionality beyond what built-in widgets provide.

Note: Scripted widgets are available as a technical preview.

In this topic:

## Overview

Scripted widgets are external actions configured with `mode.name: "widget"`. They function as custom dashboard widgets that:

- Are developed outside of OpenText Software Delivery Management and hosted independently or uploaded as bundles
- Appear in the dashboard widget gallery under a specified category or "All"
- Communicate with OpenText Software Delivery Management through an event-based system
- Support custom configuration pages for users to set up widget behavior
- Run in a sandboxed execution environment for security

Back to top

## Key features

Scripted widgets support the following capabilities:

Feature | Description
--- | ---
Custom configuration | Define custom configuration pages that users interact with when setting up the widget. Configuration is persisted in user settings.
Advanced filtering | Widgets can integrate with OpenText Software Delivery Management advanced filters and dynamic filters to scope data for visualization.
Cross-workspace support | Widgets can be configured to display data from multiple workspaces if enabled by the author.
Entity color retrieval | Widgets can request the colors assigned to items in OpenText Software Delivery Management for consistent visualization.
Drill-down functionality | Widgets can trigger drill-down lists of entities with specified filters and columns.
Gallery integration | Widgets appear in the dashboard widget gallery with configurable categories and icons. Users add widgets to dashboards just like built-in widgets.

Back to top

## Creating a scripted widget

To create a scripted widget, follow these steps:

1. Develop the widget's HTML, CSS, and JavaScript files outside of OpenText Software Delivery Management.
2. Create a JSON configuration file that defines the widget's metadata and behavior. The configuration must include a `mode` object with `name: "widget"`.
3. Optionally create configuration page files (HTML) that users interact with to customize widget behavior.
4. Upload the widget bundle to OpenText Software Delivery Management using the External action editor.
5. The widget appears in the dashboard widget gallery and is available for users to add to dashboards.

For detailed information on JSON configuration properties, see JSON properties.

Back to top

## JSON configuration

A scripted widget's JSON configuration must include the following properties:

Property | Details
--- | ---
name | Unique identifier for the widget, used in logs and errors.
title | The widget's display title in the gallery and on the dashboard.
url | The URL of the widget's main HTML file to be rendered in the dashboard. Use `{bundle_url}` if uploading as a bundle.
mode.name | Must be set to `"widget"`.
mode.description | Description displayed in the widget gallery to help users understand what the widget does.
mode.configuration_pages | Array of objects defining custom configuration pages. Each object includes a `title` (tab name) and `url` (path to the configuration page).
workspaces / exclude_workspaces | (Optional) Specify which workspaces the widget applies to, or exclude specific workspaces.

Example JSON configuration

Copy code

    {
      "name": "custom-defect-trend-widget",
      "title": "Defect Trend Analysis Widget",
      "url": "{bundle_url}/my_external_widget/index.html",
      "mode": {
        "name": "widget",
        "description": "Displays a trend graph of defect creation over a configurable period and by severity. This widget can be added to dashboards.",
        "configuration_pages": [
          {
            "title": "Data",
            "url": "{bundle_url}/my_external_widget/data_config.html"
          },
          {
            "title": "Display",
            "url": "{bundle_url}/my_external_widget/display_config.html"
          }
        ]
      }
    }

Back to top

## Widget events

Scripted widgets communicate with OpenText Software Delivery Management through events. Configuration pages and the widget display use these events to read and update configuration, retrieve data, and interact with OpenText Software Delivery Management features.

### Configuration events

Use the following events to manage widget configuration:

Event | Purpose and Usage
--- | ---
`octane_read_widget_configuration` | Request the current configuration for the widget. Trigger: Send this event from your configuration page when it loads. Message structure: `data: { panel_id: <panel_id from url> }` Response: OpenText Software Delivery Management responds with `octane_widget_configuration` event containing the configuration object.
`octane_widget_configuration` | Receive the widget's configuration from OpenText Software Delivery Management. Trigger: OpenText Software Delivery Management sends this event in response to `octane_read_widget_configuration`. Data structure: Listen for this event and retrieve configuration via `data.config`. On first use, the configuration object is empty.
`octane_update_widget_configuration` | Update the widget's configuration in user settings. Trigger: Send this event whenever the user makes changes in the configuration page. Message structure: `data: { panel_id: <panel_id from url>, config: <configuration object> }` Behavior: OpenText Software Delivery Management persists the configuration to user settings.

Implementation notes

- Configuration pages are loaded in an iFrame. Use `window.parent.postMessage()` to send events to OpenText Software Delivery Management.
- The widget display itself is also loaded in an iFrame. Use the same postMessage approach for widget-to-Octane communication.
- Always include the `panel_id` parameter (obtained from the URL) when sending events.
- Configuration is stored per user and persists across dashboard sessions.

Back to top

## Advanced filtering and dynamic filters

Note: Context filters are not supported for scripted widgets. Use the Advanced filter UI and dynamic filters instead.

From a configuration page, you can ask OpenText Software Delivery Management to open the Advanced filter dialog for the user, and then persist the result into your widget configuration.

Request the Advanced filter dialog

Send an event to display the Advanced filter with the appropriate scope and field restrictions.

Proposed message structure:

Copy code

    const message = {
      event_name: 'octane_open_advanced_filter', // TBD EVENT NAME
      data: {
        panel_id, // from URL params
        entity_type: 'work_item',
        subtypes: ['feature', 'defect'], // optional
        restrict_fields: ['team', 'program'], // optional
        allow_cross_filters: true, // optional
        cross_filter_fields: ['program'], // optional
        bind_to_config_property: 'data.filter' // where Octane should persist the Advanced filter JSON
      }
    };
    window.parent.postMessage(message, '*');

Receive updated filter

When the user applies the filter, OpenText Software Delivery Management updates the bound configuration property and notifies the page.

Listen for `octane_widget_configuration` and re-render your preview/UI accordingly.

Back to top

## Entity color retrieval

To keep your visualization consistent with OpenText Software Delivery Management UI colors, request item colors for entities in scope.

Request colors

Copy code

    const request = {
      event_name: 'octane_get_item_colors', // TBD EVENT NAME
      data: {
        panel_id,
        entity_type: 'work_item',
        ids: ['1001','1002','1003'] // optional; omit to request palette by subtype/value
      }
    };
    window.parent.postMessage(request, '*');

    window.addEventListener('message', (e) => {
      if (e.data && e.data.event_name === 'octane_item_colors') { // TBD RESPONSE EVENT NAME
        const colorsById = e.data.data.colors; // { '1001': '#4C8BF5', '1002': '#F44336', ... }
        // apply to chart
      }
    });

If your widget groups by a categorical field (for example, Team or Severity), request colors by field value to maintain consistent mapping across widgets.

Back to top

## Drill-down entity list

Open a drill-down list dialog for a given entity filter and optional columns. Use the `entity_list` event.

Field | Details
--- | ---
`entity_type` / `subtypes` | Specify a base entity type (for example, work_item) or a list of specific subtypes.
`label` | Optional dialog title.
`description` | Optional text displayed in an inline notification area.
`query` | REST query string to filter the displayed entities.
`columns` | Optional list of column field names to display.

Copy code

    const message = {
      event_name: 'entity_list',
      data: {
        panel_id,
        entity_type: 'defect',
        label: 'Open critical defects',
        description: 'Filtered by Severity = Critical',
        query: "?query=" + encodeURIComponent("severity EQ {list_node}^list_node.severity.critical; phase EQ {list_node}^list_node.defect_phase.new"),
        columns: ['id','name','severity','owner']
      }
    };
    window.parent.postMessage(message, '*');

Note: Use `{query}` and related URL tokens to construct robust queries when selection may exceed 500 items. For details, see External actions.

Back to top

Back to top

## Configuration pages

Configuration pages are custom HTML pages that users interact with to customize widget behavior. They appear as tabs in the widget configuration dialog.

Configuration pages should:

- Load and display the current widget configuration when the page opens by sending `octane_read_widget_configuration` event.
- Allow users to modify settings (data sources, display options, filters, etc.).
- Send `octane_update_widget_configuration` event whenever the configuration changes to persist updates.
- Use HTML forms and standard web controls for user interaction.

The configuration object structure is defined by the widget author.

Back to top

## Widget display

The widget display file (referenced in the main `url` property) is the HTML page rendered in the dashboard.

The widget display should:

- Read its configuration using the `octane_read_widget_configuration` event when it loads.
- Use the configuration to determine what data to fetch and how to visualize it.
- Make REST API calls to OpenText Software Delivery Management to fetch the data needed for visualization.
- Handle loading states, empty states, and error conditions gracefully.
- Respond to configuration updates if the widget is reconfigured while displayed on the dashboard.

Back to top

## Uploading scripted widgets

You can upload scripted widgets in the same way as other external actions:

1. Create a zip bundle containing the JSON configuration file and all widget code files (HTML, CSS, JavaScript).
2. Place the JSON configuration file at the root level of the zip.
3. As a Shared Space admin, open Settings > Management > External action editor.
4. Click Upload Bundle.
5. Select Upload New Action and locate your zip file.
6. The widget is added to the external actions and appears in the dashboard widget gallery.

For detailed upload instructions, see External actions.

Back to top

## Gallery integration

After uploading a scripted widget, it appears in the dashboard widget gallery. The widget's `title` and `mode.description` are displayed to help users understand what the widget does.

Back to top

## Sample widget bundle

A sample scripted widget bundle is available to help you get started with widget development. The sample demonstrates:

- JSON configuration structure
- Configuration page implementation
- Widget display and data visualization
- Event-based communication with OpenText Software Delivery Management
- REST API integration for fetching data

Back to top

## Best practices

- Security: Validate all user input in configuration pages. Use HTTPS for external resources. Be aware that widgets run in a sandboxed environment.
- Performance: Optimize API calls. Consider caching data where appropriate. Use pagination for large datasets.
- User experience: Show loading states while data is being fetched. Display clear error messages if something goes wrong. Provide helpful descriptions in the gallery.
- Configuration: Keep configuration simple and intuitive. Use clear labels and helpful hints for configuration fields.
- Testing: Test widgets with different data volumes and configurations. Test error scenarios such as API failures or network issues.

Back to top

See also:

- External actions

- JSON structure

- Sidebar plugins

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.1 All View Local Help Center View Online Help Center Version: