Creating Custom Widgets with Broadhead

Important: To view the content for the Classic Dashboard experience see Workspaces & Dashboards (Classic).
For information on Classic experiences, see Archer Classic Experiences.

Dashboards supports a global window object called Broadhead to create customized widgets.

On this page

What is Broadhead?

Broadhead is a series of predefined commands and actions that you can use within the custom widget to provide functionality to your users that may not yet exist within Archer.

Version - Required

To specify which version of Broadhead you are using, you must include a meta tag in your custom code. As Broadhead grows, new versions of the code may be added.

Examples:

How do I use Broadhead to create a custom widget?

Formulate your Broadhead command using the information on this page.
On Edit Dashboard, drag and drop the non-report widget Custom to the Center pane.
In properties, name your dashboard, and enter the command into Widgets section.

What are the Broadhead commands?

Broadhead has three commands that call different actions:

Send Action - update or retrieve information
On Action - receive the data from the Send Action command
Subscribe - automate the Send Action and On Action cycle

Send Action

Send Action deals with anything that changes a value, triggers an event, stores or retrieves information. This command requires the action name being called and any associated parameters. Before being performed, Archer validates the syntax to minimize the impact of incorrect code.

Examples:

broadhead.sendAction('action-name', parameters);

Response:

In the cases where Send Action results in a response, you can handle in one of the following methods:

Create an On Action which asynchronously manages the response data.
Include an await response component to the send action command to handle the response.
- By default, this times out after 10 seconds. You can extend that time by providing a parameter in milliseconds.

Examples:

broadhead.sendAction('action-name', parameters).awaitResponse(15000).then((response_data) => {});

On Action

Use On Action receive content from a Send Action command, only.

Examples:

broadhead.onAction('action-name', (response_data, respond) => {});

Response:

{
action: string,
from: string,
to: string,
messageId: string,
message: any,
responseId: string (optional)
}

Use Subscribe to automate the Send Action and On Action command cycle.

Examples:

broadhead.subscribe('action-name', (response_data) => {});

You may find you want to cancel an existing Subscribe command. In those cases, use Unsubscribe to stop that command.

Examples:

broadhead.unsubscribe('action-name');

What actions can be used with each command?

Use these actions with the Broadhead commands to create your own custom widgets.

The following table describes each action, which actions are available with each command, and links to more specific instructions:
Action	Description	SendAction	OnAction	Subscribe	General
Fetch	Call an API.
Navigate	Open a URL on current tab or in a new tab.
Storage	Use local and session storage for your Broadhead object.
Dashboard Storage	Use to enable navigation across dashboards
Communicate	Send and receive messages between custom widgets using custom defined actions.

What are General Actions?

These actions allow you to get information that is not on the custom widget. General actions work on their own and do not require a command.

Fetch

Fetch allows you to call any Archer API from within your record.

Important: You must understand the API you want to use in order to properly leverage this action. Each API may require a url, header, body, and method. Access the API documentation to learn more about the commands available. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html.

Template:

broadhead.fetch({ Parameters }).awaitResponse().then((response_data) => {});

Parameters:

These are potential Parameters depend upon the API being called. Those parameters marked optional may be required depending upon the API being called.

url - Identifies the API to call.
headers - (optional) Attributes that are added to the request header.
body - (optional) Parameters passed to the API in the body of the request.
method - (optional) Identifies the method of the request. IE: get (Default), post, put, patch

Examples:

broadhead.fetch({url: '/record/v1/repository-files/8675309/file'}).awaitResponse().then((response_data) => {});
broadhead.fetch (
{ url: 'ngrx/record/v1/contents',
method: 'POST',
headers: { correlationId: '888-789' },
body: {id: 1234, contentFields: [...], ... }
}).awaitResponse().then((response_data) => {});

Response Format:

{ data: any; ok: boolean; status: number; statusText: string; contentType: string; redirected: boolean; url: string; }

Navigate

Navigate allows you to open a URL in the current tab or a new tab.

Template:

broadhead.navigate(url,newTab);

Parameters:

url - Identify the string to open.
newTab - (optional) set to true to open a new tab.

Examples:

broadhead.navigate('https://go.archerirm.com/',true);

Storage

Storage allows you to do the following within local and session storage.

clear - Clear the entire storage.
getItem - Get a single item.
setItem - Set a single item.
removeItem - Remove a single item.

Templates:

broadhead.localStorage.clear();
broadhead.localStorage.getItem(key).awaitResponse().then((response_data) => {});
broadhead.localStorage.setItem(key, value);
broadhead.localStorage.removeItem(key);
broadhead.sessionStorage.clear();
broadhead.sessionStorage.getItem(key).awaitResponse().then((response_data) => {});
broadhead.sessionStorage.setItem(key, value);
broadhead.sessionStorage.removeItem(key);

Parameters:

key - Identify the item to work with.
value - Set the value of the item.

Examples:

broadhead.localStorage.setItem('Number_of_Players', 1);
broadhead.localStorage.removeItem('Number_of_Players');

Dashboard Storage

Use session storage to enable navigation across dashboards.

Parameters:

dashboardDetails - key used to store dashboard identifiers: dashboardId and WorkspaceId

Examples:

broadhead.sendAction('save-dashboard-details-to-session');
broadhead.sessionStorage.getItem('dashboardDetails');
broadhead.sendAction('remove-dashboard-details-from-session');

Communicate

Send and receive messages between custom content using custom defined actions.

Note: Communication between custom content uses `sendActionToIFrame` for sending messages and the standard `onAction` method for receiving them. This allows custom content to create their own broadhead actions for other iframes to catch. The `sendActionToIFrame` method is different from the standard `sendAction` command, while `onAction` works the same way for both built-in and custom actions.

Template:

broadhead.sendActionToIFrame(iFrameId, action, message);

Parameters:

iFrameId - The unique numeric identifier of the target custom content (as a string).
action - The name of the custom action to send.
message - The message payload to send with the action.

Examples:

This example uses a separate custom content to get the field value using a field name. In this example, a utility content, called Custom 1, is referenced by several other custom content within a record, such as Custom 2, to do different tasks at different locations.

Custom 1 (id: 1234):

broadhead.onAction('get-field-value', (fullMessage, respond) => {
const { message } = fullMessage;
const { fieldName } = message;
// logic to get the field value
respond({ fieldId, fieldValue });
});

Custom 2 (id: 5678):

broadhead.sendActionToIFrame('1234', 'get-field-value', { fieldName: 'Field Name' })
.awaitResponse()
.then((message) => {
const { fieldId, fieldValue } = message;
// Do something with the response
});