When developing a playbook for the Employee Center you may have the need to be able to utilize some of the functions that are only available in the portal. This can be done by creating a custom playbook activity and then use the events which the widget listens on.
Use cases
- Show a info message on the top of the page
- Route the user to a different page when the playbook finishes
- Open a record or list view modal
Portal widget
The playbook widget in the portal listens on 6 different storage events, that can be called from a custom playbook activity in UI Builder.
PLAYBOOK#OPEN_RECORD
Open a modal containing the record.
Parameters
| Parameter | Type | Required | Default value | Description |
| table | String | Yes | - | The table. |
| sys_id | String | Yes | - | SYS ID of the record. |
Example usage in UI Builder
api.emit('PLAYBOOK_INTERNAL#OPEN_RECORD', {
table: 'incident',
sys_id: '123...'
});PLAYBOOK#OPEN_LIST
Open a modal containing the list.
Parameters
| Parameter | Type | Required | Default value | Description |
| table | String | Yes | - | The table. |
| query | String | Yes | - | Encoded query. |
| view | String | No | null | Optional list view. |
Example usage in UI Builder
api.emit('PLAYBOOK_INTERNAL#OPEN_LIST', {
table: 'incident',
query: 'active=true',
view: 'default'
});PLAYBOOK#RECORD_GENERATED
Judging by the name, this is probably intended for the Playbook Experience Record Generator. When using the event, it reloads the current page with the table and sysId added to the URL parameters.
NOTE! This can cause an infinite loop, check your conditions before using this event.
Parameters
The notifications array consists of an object with these parameters
| Parameter | Type | Required | Default value | Description |
| table | String | Yes | - | The table. |
| sysId | String | Yes | - | SYS ID of the record. |
Example usage in UI Builder
api.emit('PLAYBOOK_INTERNAL#RECORD_GENERATED', {
table: 'incident',
sysId: '123..'
});
PLAYBOOK#ADD_NOTIFICATIONS
Shows one or multiple messages on the top of the portal page.
Parameters
The notifications array consists of an object with these parameters
| Parameter | Type | Required | Default value | Description |
| type | String | No | - | info, error, critical |
| message | String | Yes | - | message to show |
Example usage in UI Builder
api.emit('ADD_NOTIFICATIONS_INTERNAL', {
notifications: [
{
"type": "info",
"message": "A message"
}
]
});
PLAYBOOK#LINK_TO_DESTINATION
Opens a URL, either in a new browser tab or replace the current one.
Parameters
| Parameter | Type | Required | Default value | Description |
| external | String | Yes | - | The URL to open |
| targetRoute | String | No | _blank | _self, _blank |
_self - Replace the current browser page.
_blank - A new browser tab will open up.
Example usage in UI Builder
api.emit('PLAYBOOK_INTERNAL#LINK_TO_DESTINATION', {
external: 'https://www.servicenow.com/',
targetRoute: '_self'
});
PLAYBOOK#RESIZE_IFRAME
Set the height of the iframe.
Parameters
| Parameter | Type | Required | Default value | Description |
| currentHeight | String | Yes | - | Height of the iframe. |
Example usage in UI Builder
api.emit('PLAYBOOK_INTERNAL#RESIZE_IFRAME', {
currentHeight: '600'
});
Dispatched events
Some widget events are not added to the UI Builder by default, so you must add these events to be able to use them.
Example
Custom events
If you have the need for a custom event, to be able to send a custom payload to the portal you're required to use a cloned version of the playbook-widget to intercept the custom events since it's in read-only.
Client script - Portal widget
This is just a example. You could expand on the already existing event listener instead.
window.addEventListener("storage", function(event) {
if(!event || !event.key) return;
var newValue = event.newValue;
var value = JSON.parse(newValue);
if ( value.customParam ) {
console.log(value.customParam);
}
});
Client script - UI Builder
In this example we're just using the notifications event with a different payload.
api.emit('ADD_NOTIFICATIONS_INTERNAL', {
customParam: 'test'
});
