Share this page

# Create sidebar plugins

You can develop plugins for ALM Octane and display them in custom sidebars alongside grids. These plugins can interact with the grid items.

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

In this topic:

## Sidebar plugin overview

You can create custom sidebar plugins and add them to all grid views in ALM Octane that already include right pane sidebars (such as Filter and Preview). For example, you can develop a plugin that contains a link to the Teams channel related to the selected feature, or a sketch board whose contents are added as attachments to the feature. All main entity types are supported, including requirements, features, and tests.

Implementation examples

Following are examples of sidebar plugins:

- List the work items belonging to the selected feature:

  You can download the code for this example in the Templates and examples section.

- Analyze estimated vs. actual work effort of the selected feature and its items:

- Summary of integer fields of selected features. Supports multi-selection:

Back to top

## Use REST API in sidebar implementations

You can use ALM Octane's REST API in the sidebar plugin code to access data and post new data in ALM Octane.

The interactive API client allows you to experiment with the API on your shared space data to make API calls from within the ALM Octane UI. For details, see Interactive API client.

For full details on the REST API, see The REST API.

Back to top

## Sidebar code samples

This section contains code samples for sidebar plugin actions.

Get 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;
    }

Post a field value

Copy code

        const entity = {
            fieldName: fieldValue,
        };

        const cookieValue = document.cookie
            .split('; ')
            .find(row => row.startsWith('XSRF_COOKIE='))
            .split('=')[1];

        fetch(
            '/api/shared_spaces/' +
            ssId +
            '/workspaces/' +
            wsId +
            '/work_items/' +
            entityId,
            {
                headers: {
                    'content-type': 'application/json',
                    'XSRF-HEADER': cookieValue,
                },
                body: JSON.stringify(entityData) ,
                method: 'PUT',
                credentials: 'include',
            }
        );

Note the use of `XSRF_COOKIE` and `XSRF-HEADER`. They are required if the plugins are hosted in ALM Octane itself or if they are hosted in a separate service and use CORS to communicate with ALM Octane. For details, see Use CORS for external actions.

Post events and trigger actions in ALM Octane

ALM Octane events can be triggered by external applications, as shown in the examples below. For more details, see Trigger ALM Octane events from external app.

The following example causes ALM Octane to refresh the current entity:

Copy code

    {
        event_name: 'octane_refresh_entity',
        shared_space: '1004',
        workspace: '1006',
        data: {
            entity_type: 'work_item',
            entity_ids: ['1003', '4005'],
        },
    }

The following example causes ALM Octane to refresh a selection:

Copy code

    var message = {
        event_name: 'octane_refresh_list',
        shared_space: '1004',
        workspace: '1006',
        data: {
            entity_type: 'work_item',
            entity_ids: ['1003', '4005'],
        },
    };
    window.opener.postMessage(message, '*');

The following example causes ALM Octane to select entities in the grid:

Copy code

    {
        event_name: 'octane_select_entity',
        shared_space: '1004',
        workspace: '1006',
        data: {
            entity_type: 'work_item',
            entity_id: '1050',
        },
    }

The following example causes ALM Octane to open Document View for the selected entity:

Copy code

    {
        event_name: 'octane_display_entity',
        shared_space: '1004',
        workspace: '1006',
        data: {
            entity_type: 'work_item',
            entity_id: '1050',
        },
    }

Back to top

## Templates and examples

This section includes templates for creating new plugins and examples that show possible uses for plugins.

Note: Additional examples are available in Github.

You can download the following examples. Examples are composed of the zip files and a json configuration to copy to the external action editor when uploading the zip.

Example | Description
--- | ---
feature_work_items.zip | An implementation of the feature work items example. Use feature_work_items.json for the configuration in the external action editor.
external_details.zip | This plugin showcases all APIs used in the plugin mechanism and is 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 this to start a new empty plugin project. Use external-details.json for the configuration in the external action editor.
external_panel_wsjf.zip | Plugin with example of changing back a field via REST API. Use external_panel_wsjf.json for the configuration in the external action editor.

The index.html files in the zips contain references to an ALM Octane style sheet. The css file contains basic styles aligned with ALM Octane's own styles, which you can use to align the plugin's look and feel with ALM Octane for a smoother UX.

Copy code

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

Back to top

## Advanced guidelines

Following are guidelines for advanced work with sidebar plugins.

React to changes in external action parameters

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

Following is an example of a URL configuration for passing parameters as query parameters:

`{octane_url}/api/shared_spaces/{shared_space}/external-entity-actions/bundle/index.html?entity_ids={entity_ids}`

In this case, each time `entity_ids` changes, it causes the plugin to reload. This can negatively affect the UX if it takes time to load and render the plugin UI.

Alternatively, the same parameters can be passed as hash parameters:

`...index.html#entity_ids={entity_ids}`

In this case, the plugin will not reload when `entity_ids` parameters are updated. Instead, you would need to subscribe to the `onhashchange` event, which would allow you to react to changes in parameters. For example:

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}`);
        }
    }

Chrome local overrides

An efficient way to develop the plugin is by using the Chrome local overrides feature. Local overrides are files that Chrome serves in place of a live request. This allows you to edit your files from the Chrome developer console to see instant changes in the plugin. It can also track the real file for changes and apply them, so you can change and save the file using an IDE, and Chrome will apply the changes instantly to your plugin.

Back to top

See also:

- Create external actions
- The REST API

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ValueEdge & ALM Octane Help Center ValueEdge ALM Octane Help 16.0.100-16.0.400 All View Local Help Center View Online Help Center back Go back in browser history forward Go forward in browser history Remove search highlights next topic Go to next topic previous topic Go to previous topic Print the current topic Version: