Creating Custom Objects with Broadhead

Custom objects now use a global window object called Broadhead and are only available in SaaS with the next generation experience active.

You can continue to use the classic custom object feature. See Archer Next Generation User Experiences for more information on Classic and Next Generation experiences.

On this page

What is Broadhead?

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

Version

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

Examples:

<meta name="Broadhead" content="v1" />

How do I use Broadhead to create a Custom Object?

  1. Formulate your Broadhead command using the information on this page.

  2. In Application Builder > Application, select the custom object.

  3. In the properties panel, enter the command into New Experience Custom Object.

What are the Broadhead commands?

Broadhead has three commands that call different actions.

  • Send Action - update or retrieve information on the record

  • 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.

    • Examples: 

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

On Action

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

Examples:

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

Response:

{
action: string,
from: number,
to: number,
messageId: string,
message: any,
responseId: string
}

Subscribe

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 commands?

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

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.

Unavailable

Unavailable

Unavailable

Available

Navigate

Open an URL on current tab or in a new tab.

Unavailable

Unavailable

Unavailable

Available

Storage

Use local and session storage for your Broadhead object. Does not affect the record.

Unavailable

Unavailable

Unavailable

Available

Communicate

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

Unavailable

Unavailable

Unavailable

Available

Layout Metadata

Get details about the record's layout. IE: Field ids, tab ids, section ids, etc.

Available

Available

Available

Unavailable

Record Metadata

Get key details about the record. IE: record id, version, layout id, etc.

Available

Available

Available

Help unavailable

Form Values

Get current values for every field in the form.

Unavailable

Unavailable

Available

Unavailable

Form Metadata

Get details about the form. IE: are the inputs valid, is the form dirty, are the Save and discard buttons available

Unavailable

Unavailable

Available

Unavailable

Form Errors

Get all field errors that currently exist in the form.

Unavailable

Unavailable

Available

Unavailable

AWF Configuration

Get configuration details about the existing advanced workflow (AWF) for this record.

 Available Available Help available Unavailable

AWF Job Data

Access the AWF job data.

Available

Available

Available

Unavailable

Save Changes

Saves the record.

Available

Unavailable

Unavailable

Unavailable

Discard Changes

Discard changes to record since last save.

Available

Unavailable

Unavailable

Unavailable

Set Error

Puts a field into an error state with specified error message.

Available

Unavailable

Unavailable

Unavailable

Clear Error

Clears the error state of a field.

Available

Unavailable

Unavailable

Unavailable

Set Value

Updates the value of a field.

Available

Unavailable

Unavailable

Unavailable

Set Metadata

Updates the metadata for a tab set, tab, section, or field.

Available

Unavailable

Unavailable

Unavailable

Clear Metadata

Resets the metadata of a field to its original values.

Available

Unavailable

Unavailable

Unavailable

Set Focus

Move the users focus to a specific field, opening all associated tabs and sections.

Available

Unavailable

Unavailable

Unavailable

Enable Loading Overlay

Show or hide the record loading overlay.

Available

Unavailable

Unavailable

Unavailable

Trigger AWF Enrollment

Save and enroll the record in the AWF.

Available

Unavailable

Unavailable

Unavailable

Trigger AWF Transition

Saves and moves the record into the next stage of AWF.

Available

Unavailable

Unavailable

Unavailable

What are General Actions?

These actions allow you to get information not on the record. 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 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 use local and session storage for your custom object without changing the record.

Templates:

  • broadhead.localStorage.clear();

  • broadhead.localStorage.getItem(key).awaitResponse().then((response_data) => {});

  • broadhead.localStorage.setItem(key, value);

  • broadhead.localStorage.removeItem(key);

  • broadhead.sessionStorage.clear|getItem|setItem|removeItem()

Parameters:

  • method - Chose what you want to do with storage. Options are:

    • clear - Clear the entire storage.

    • getItem - Get a single item.

    • setItem - Set a single item.

    • removeItem - Remove a single item.

  • 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);

Communicate

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

Parameters:

  • custom object ID - The unique numeric identifier of the custom object.

  • get-field-value - The name of the custom object.

  • Response - The response from the custom object being communicated with.

Examples:

This example uses a separate custom object to get the field value using a field name.

Custom Object 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 Object 2 (id: 5678):

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

How can I retrieve data?

Use these actions to get data from Archer.

Layout Metadata

Get a list of IDs for all the sections, tabs, tab sets, and fields available for the layout associated with this record.

Examples:

  • broadhead.sendAction('layout-metadata');

  • broadhead.onAction('layout-metadata', (response_data) => {});

  • broadhead.subscribe('layout-metadata', (response_data) => {});

Parameters:

This action does not require parameters.

Response:

The response format is:

{[id: number]: object}

This is an response example with false data:

{
1234: { id: 1234, name: 'Mork', type: 'alien' },
5678: { id: 5678, name: 'Mindy', type: 'human' }
}

Record Metadata

Get key details about the record, such as id, version, layout id, etc.

Examples:

  • broadhead.sendAction('record-metadata');

  • broadhead.onAction('record-metadata', (response_data) => {});

  • broadhead.subscribe('record-metadata', (response_data) => {});

Parameters:

There are no required parameters for this action.

Response:

The response format is:

{
isDdeValuesListFilterCumulative: boolean,
isDirectToEditEnabled: boolean,
isModuleLeveled: boolean,
layoutId: number,
levelName: string,
recordId: number,
version: number
}

Form Values

Get current values for every field on the record.

Examples:

broadhead.subscribe('form-values', (response_data) => {});

Parameters:

There are no parameters for this action.

Response:

The response format is:

{ [fieldId: number]: any }

This is an response example with false data:

{
1234: Mork,
5678: Mindy
}

Form Metadata

Get details about the record. The information returned answers the following questions:

  • isValid - Is the record properly filled out?

  • isDirty - Has the record been changed since saving?

  • isSaveDiscardVisible - Are the save and discard buttons available?

Examples:

broadhead.subscribe('form-metadata', (response_data) => {});

Parameters:

There are no parameters for this action.

Response:

The response format is:

{
isValid: boolean,
isDirty: boolean,
isSaveDiscardVisible: boolean
}

Form Errors

Get all field errors that currently exist in the record. If there are no errors, a response is not returned.

Examples:

broadhead.subscribe('form-errors', (response_data) => {});

Parameters:

There are no parameters for this action.

Response:

The response format is this:

{[fieldId:number]: string }

This is an example response with false data:

{
1234: string,
5678: string
}

AWF Configuration

Get configuration details about the existing advanced workflow for this record

Examples:

  • broadhead.subscribe('advanced-workflow-configuration', (response_data) => {});

  • broadhead.sendAction('advanced-workflow-configuration');

  • broadhead.onAction('advanced-workflow-configuration', (response_data) => {});

Parameters:

There are no parameters for this action.

Response:

The response format is:

{
guid: string,
id: number,
levelId: number,
workflowProcessId: string,
isActive: boolean,
isEnrollable: boolean,
allowReenrollment: boolean,
enrollOnContentCreate: boolean,
enrollOnContentUpdate: boolean,
enrollOnDemand: boolean,
enrollOnDemandButtonText: string,
workflowValidationRuleId: number,
workflowPermissionRuleId: number,
isAuditEnabled: boolean,
auditRetentionDays: number,
auditRetentionJobs: number,
workflowAuditPermissionRuleId: number,
auditPermission: boolean
}

AWF Job Data

Get AWF job details about where the record is currently in the workflow and what transitions are available.

Examples:

  • broadhead.subscribe('advanced-workflow-data', (response_data) => {});

  • broadhead.sendAction('advanced-workflow-data');

  • broadhead.onAction('advanced-workflow-data', (response_data) => {});

Parameters:

There are no parameters for this action.

Response:

The response varies based upon the AWF step currently in progress.

See the Record Page API documentation for examples of the response. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html.

How can I manipulate the record? 

Use these actions to update your record.

Save Changes

Save the record.

Examples:

broadhead.sendAction('save-changes').awaitResponse().then((response_data) => {});

Parameters:

There are no parameters for this action.

Response:

Responses are based upon success or failure. For more details, see the Post Contents entry on the Record Page API documentation. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html.

Discard Changes

Discard changes to record since the last save.

Examples:

broadhead.sendAction('discard-changes');

Parameters:

There are no parameters for this action.

Response:

There is no response for this action.

Set Error

Put a field into an error state with specified error message.

Template:

broadhead.sendAction('set-error', parameters);

Parameters:

{
fieldId: string | number,
error: string
}

Examples:

broadhead.sendAction('set-error', {fieldId:12345, error:"This field is in error"});

Response:

There is no response for this action.

Clear Error

Clear the error state of a specific field when passed a fieldId. If null, undefined or no value is passed, then all errors on the record are cleared.

Template:

broadhead.sendAction('clear-error', fieldId);

Parameters:

fieldId: string | number | undefined | null

Examples:

broadhead.sendAction('clear-error', 12345);

broadhead.sendAction('clear-error');

Response:

There is no response for this action.

Set Value

Update the value of a field within the record. This value is subject to format validation based upon the field type.

To understand the format validation on each field type see the Record Page API documentation for examples. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html. Value attributes are found by searching {Field Type}FieldContentSave in the documentation.

Only the following field types can have their value set: Text, Date, Numeric, ValuesList, CrossReference, UsersGroupsList (RecordPermissions use this type but with 'isRecordPermission: true' in the layout), Scheduler, SubForm, and RelatedRecords. Private fields do not allow their value to be set.

Template:

broadhead.sendAction('set-value', parameters);

Parameters:

{
fieldId: number | string,
value: any
}

Examples:

broadhead.sendAction('set-value', {fieldId:12345, value:"This is a value");

Response:

There is no response for this action.

Set Metadata

Update the metadata for a tab set, tab, section, or field. This action overrides any Data Driven Events (DDE) and does not trigger DDEs.

For example, if a DDE hides a section when all the fields are hidden, using this action to hide fields does not trigger the DDE and the section remains visible despite appearing empty.

Template:

broadhead.sendAction('set-metadata', parameters);

Parameters:

For Fields

{
fieldId: number,
hidden: boolean,
isRequired: boolean,
isContentReadOnly: boolean,
helpText: string,
showHelpTextInEdit: boolean,
showHelpTextInView: boolean
}

For Sections:

{
sectionId: number,
hidden: boolean,
isHideHeader: boolean,
panelText: string,
showPanelText: boolean,
helpText: string,
showHelpText: boolean
}

For Tab sets:

{
tabsetId: number,
hidden: boolean
}

For Tabs:

{
tabId: number,
hidden: boolean
}

For CrossReference, RelatedRecords, and SubForm types:

{
fieldId: number,
allowLookup: boolean,
allowAddNewInEdit: boolean,
allowAddNewInView: boolean
}

For TextBox type:

{
fieldId: number,
text: string,
}

Examples:

  • broadhead.sendAction('set-metadata', { tabsetId:123454, hidden:true });

  • broadhead.sendAction('set-metadata', { tabId:6784, hidden:true });

Response:

There is no response for this action.

Clear Metadata

Reset the metadata of a field to its original values.

Template:

broadhead.sendAction('clear-metadata',number);

Parameters:

number | string

To clear the metadata on a specific field, send a fieldId.

To clear all metadata set by custom objects, do not send a parameter.

Examples:

broadhead.sendAction('clear-metadata',123123);

Response:

There is no response for this action.

Set Focus

Move the user's focus to a specific field, opening all associated tabs and sections. This action maintains the current mode. For example, when the focus is moved and the user is in edit mode, the user stays in edit mode.

Template:

broadhead.sendAction('set-focus', parameters);

Parameters:

{id: number | string}

Examples:

broadhead.sendAction('set-focus', {id: 1234});

Response:

There is no response for this action.

Enable Loading Overlay

Show or hide the display by muting it and overlaying a loading icon when the record is loading. Navigation is still available with the overlay enabled.

Templates:

broadhead.sendAction('show-loading-overlay', false)

broadhead.sendAction('show-loading-overlay')

Parameters:

{empty | undefined | boolean}

Response:

There is no response for this action.

Trigger AWF Enrollment

Save and enroll the record in the AWF.

If there are errors on the record, the enrollment fails and a message displays.

Examples:

broadhead.sendAction('trigger-advanced-workflow-enrollment');

Parameters:

There are no parameters for this action.

Response:

For more details on potential responses, see the /record/v1/contents/{contentId}/advanced-workflow entry on the Record Page API documentation. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html.

Trigger AWF Transition

Save and move the record into the next stage of AWF.

If there are errors on the record, the transition fails and a message displays.

Template:

broadhead.sendAction('trigger-advanced-workflow-transition', parameters );

Parameters:

{
transitionId: number | string,
skipConfirmation (Optional): boolean
}

By default, a confirmation dialog appears that the user must interact with to continue. You can choose to bypass this with the skipConfirmation parameter.

Examples:

broadhead.sendAction('trigger-advanced-workflow-transition', { transitionId: 12323, skipConfirmation: true} );

Response:

For more details on potential responses, see the /record/v1/transition-node entry on the Record Page API documentation. Access the API documentation available by logging into Archer and replacing everything after your Archer link with ngrx/record/swagger/index.html..