The PlaybookExperience API provides methods for handling playbook executions.

This API requires the Playbook Experience Core plugin (com.glide.playbook_experience.config) and is provided within the sn_playbook namespace.

This API requires at least one playbook in the Process Definition [sys_pd_process_definition] table. To use this API, you must have the roles required to view and cancel a running process in Process Automation Designer. For more information, see Process Automation Designer.

PlaybookExperience - cancelPlaybooksByParentRecord(GlideRecord parentRecord, String cancellationReason, String scopedName, String playbookExperienceId)

Cancels playbook executions for a given parent record.

Table 1. Parameters
NameTypeDescription
parentRecord GlideRecord The parent record to cancel playbook executions for. The parent record can be any record that has playbook executions, such as an interaction record or an onboarding case record.
cancellationReason String The reason for cancelling the playbook executions.
scopedName String Optional. The scoped name of the playbook to cancel. The scoped name is from the Process Definition [sys_pd_process_definition] table in the format scope.name. If provided, only executions of this playbook are cancelled for the given parent record. If not provided, all executions of all playbooks are cancelled for the given parent record.
playbookExperienceId String Optional. Sys_id of the playbook experience record in the Playbook Experience [sys_playbook_experience] table to use for the cancellation. Use this parameter if you've defined custom activity state mappings. See Playbook activity state mapping.

Default: Sys_id of the Global Playbook Experience record.
Table 2. Returns
TypeDescription
Object Object containing the cancelled playbook executions and any skipped playbook executions that were unable to be cancelled. 
{
  "canceledPlaybookContext": [Array],
  "skippedPlaybookContext": [Array]
}
<Object>.canceledPlaybookContext List of the cancelled playbook executions. Each playbook execution is an object in the array.

Data type: Array

"canceledPlaybookContext": [
    {
      "can_read": Boolean,
      "canceled_by": "String",
      "cancellation_reason": "String",
      "errors": [Array],
      "parent_record": "String",
      "parent_table": "String",
      "playbook_id": "String",
      "playbook_table": "String",
      "scoped_name": "String",
      "state": {Object},
      "sys_id": "String",
      "title": "String"   
    }
]
<Object>.canceledPlaybookContext.can_read

Flag that indicates whether the current user can read the playbook execution record. The current user must have read access to the parent record to be able to read the playbook execution record.

Valid values:
  • true: Current user has read access to the playbook execution record.
  • false: Current user doesn't have read access to the playbook execution record.

Data type: Boolean
<Object>.canceledPlaybookContext.canceled_by The User ID of the user who cancelled the playbook execution.

Data type: String
<Object>.canceledPlaybookContext.cancellation_reason The cancellation reason input by the user who cancelled the playbook execution.

Data type: String
<Object>.canceledPlaybookContext.errors List of cancellation errors. Each error is an object in the array.

Data type: Array

"errors": [
    {      
      "message": "String",
      "type": "String"  
    }
]
<Object>.canceledPlaybookContext.errors.message The error message.

Data type: String
<Object>.canceledPlaybookContext.errors.type The type of error.

Data type: String
<Object>.canceledPlaybookContext.parent_record Sys_id of the parent record that playbook executions were cancelled for.

Data type: String
<Object>.canceledPlaybookContext.parent_table The name of the table that the parent record is from.

Data type: String
<Object>.canceledPlaybookContext.playbook_id Sys_id of the playbook from the Process Definitions [sys_pd_process_definition] table.

Data type: String
<Object>.canceledPlaybookContext.playbook_table The name of the table that the playbook is from, generally the Process Definitions [sys_pd_process_definition] table.

Data type: String
<Object>.canceledPlaybookContext.scoped_name The scoped name of the playbook from the Process Definitions [sys_pd_process_definition] table in the format scope.name.

Data type: String
<Object>.canceledPlaybookContext.state The state of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: Object

"state": {    
   "displayValue": "String",    
   "value": "String"
}
<Object>.canceledPlaybookContext.state.displayValue The display value of the playbook execution state.

Data type: String
<Object>.canceledPlaybookContext.state.value The value of the playbook execution state.

Data type: String
<Object>.canceledPlaybookContext.sys_id Sys_id of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: String
<Object>.canceledPlaybookContext.title The label of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: String
<Object>.skippedPlaybookContext List of the skipped playbook executions. Each playbook execution is an object in the array. For descriptions of the object properties, see the canceledPlaybookContext array.

Data type: Array

"skippedPlaybookContext": [
    {
      "can_read": Boolean,
      "canceled_by": "String",
      "cancellation_reason": "String",
      "errors": [Array],
      "parent_record": "String",
      "parent_table": "String",
      "playbook_id": "String",
      "playbook_table": "String",
      "scoped_name": "String",
      "state": {Object},
      "sys_id": "String",
      "title": "String"   
    }
]

Example

This example shows how to cancel all executions of a specific playbook (in this case, the Playbook Experience Demo) for a given interaction record. To use this method in a UI action or business rule, pass the current object as the parentRecord instead.

var parentRecord = new GlideRecordUtil().getGR("interaction", "d91742531b343010a26c98a1b24bcbe0");

var cancellationReason = "Cancelling this playbook";

// demo playbook from Process Automation Experience Demo store app
var scopedName = "sn_pad_demo.playbook_experience_demo"; 

// demo playbook experience from Process Automation Experience Demo store app
var playbookExperienceId = "a56d8d93ff311010cc0853ea793bf1a6"; 
	
var cancelPlaybookReturn = sn_playbook.PlaybookExperience.cancelPlaybooksByParentRecord(parentRecord, cancellationReason, scopedName, playbookExperienceId);
	

gs.info(JSON.stringify(cancelPlaybookReturn, null, 2));

Output:

{
  "canceledPlaybookContext": [
    {
      "can_read": true,
      "sys_id": "d02782533d343010ac50ee17e75d3466",
      "scoped_name": "sn_pad_demo.playbook_experience_demo",
      "canceled_by": "admin",
      "playbook_table": "sys_pd_process_definition",
      "state": {
        "displayValue": "Pending Cancel",
        "value": "PENDING_CANCEL"
      },
      "title": "Playbook Experience Demo",
      "parent_record": "d91742531b343010a26c98a1b24bcbe0",
      "playbook_id": "0d35ee1807301010cc08d9630ad3002a",
      "cancellation_reason": "Cancelling this playbook",
      "parent_table": "interaction",
      "errors": []
    }
  ],
  "skippedPlaybookContext": []
}

PlaybookExperience - getPlaybooksForParentRecord(GlideRecord parentRecord)

Gets a list of playbook executions for a given parent record.

Table 3. Parameters
Name Type Description
parentRecord GlideRecord The parent record to get playbook executions for. The parent record can be any record that can have playbook executions, such as an interaction record or an onboarding case record.
Table 4. Returns
TypeDescription
Array List of playbook executions for the parent record. Each playbook execution is an object in the array.
[
    {
      "can_read": Boolean,
      "canceled_by": "String",
      "cancellation_reason": "String",
      "errors": [Array],
      "parent_record": "String",
      "parent_table": "String",
      "playbook_id": "String",
      "playbook_table": "String",
      "scoped_name": "String",
      "state": {Object},
      "sys_id": "String",
      "title": "String"   
    }
]
<Array>.can_read

Flag that indicates whether the current user can read the playbook execution record. The current user must have read access to the parent record to be able to read the playbook execution record.

Valid values:
  • true: Current user has read access to the playbook execution record.
  • false: Current user doesn't have read access to the playbook execution record.

Data type: Boolean
<Array>.canceled_by The User ID of the user who cancelled the playbook execution. Empty if the playbook is not cancelled.

Data type: String
<Array>.cancellation_reason The cancellation reason input by the user who cancelled the playbook execution. Empty if the playbook is not cancelled.

Data type: String
<Array>.errors List of errors. Each error is an object in the array.

Data type: Array

"errors": [
    {      
      "message": "String",
      "type": "String"  
    }
]
<Array>.errors.message The error message.

Data type: String
<Array>.errors.type The type of error.

Data type: String
<Array>.parent_record Sys_id of the parent record.

Data type: String
<Array>.parent_table The name of the table that the parent record is from.

Data type: String
<Array>.playbook_id Sys_id of the playbook from the Process Definitions [sys_pd_process_definition] table.

Data type: String
<Array>.playbook_table The name of the table that the playbook is from, generally the Process Definitions [sys_pd_process_definition] table.

Data type: String
<Array>.scoped_name The scoped name of the playbook from the Process Definitions [sys_pd_process_definition] table in the format scope.name.

Data type: String
<Array>.state The state of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: Object

"state": {    
   "displayValue": "String",    
   "value": "String"
}
<Array>.state.displayValue The display value of the playbook execution state.

Data type: String
<Array>.state.value The value of the playbook execution state.

Data type: String
<Array>.sys_id Sys_id of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: String
<Array>.title The label of the playbook execution from the Process Executions [sys_pd_context] table.

Data type: String

Example

This example shows how to get playbook executions for a given interaction record. To use this method in a UI action or business rule, pass the current object as the parentRecord instead.

var parentRecord = new GlideRecordUtil().getGR("interaction", "148776e5818d7410f87701eb89fdc824");
var playbook = sn_playbook.PlaybookExperience.getPlaybooksForParentRecord(parentRecord);
gs.info(JSON.stringify(playbook, null, 2));

Output:

[
  {
    "can_read": true,
    "sys_id": "bd87bae50b8d7410807a8ffed6d0909e",
    "scoped_name": "sn_pad_demo.playbook_experience_demo",
    "canceled_by": "",
    "playbook_table": "sys_pd_process_definition",
    "state": {
      "displayValue": "In Progress",
      "value": "IN_PROGRESS"
    },
    "title": "Playbook Experience Demo",
    "parent_record": "148776e5818d7410f87701eb89fdc824",
    "playbook_id": "0d35ee1807301010cc08d9630ad3002a",
    "cancellation_reason": "",
    "parent_table": "interaction",
    "errors": []
  }
]

PlaybookExperience - parentRecordContainsPlaybook(GlideRecord parentRecord, String scopedName)

Checks whether a parent record has playbook executions.

Table 5. Parameters
Name Type Description
parentRecord GlideRecord The parent record to check for playbook executions. The parent record can be any record that can have playbook executions, such as an interaction record or an onboarding case record.
scopedName String Optional. The scoped name of the playbook to check for. The scoped name is from the Process Definition [sys_pd_process_definition] table in the format scope.name. If provided, only executions of this playbook are checked for. If not provided, executions of all playbooks are checked for.
Table 6. Returns
Type Description
Boolean

Flag that indicates whether the parent record has playbook executions.

Valid values:
  • true: Parent record has playbook executions.
  • false: Parent record doesn't have playbook executions.

Example

This example shows how to check if a given interaction record has executions of a specific playbook (in this case, the Playbook Experience Demo). To use this method in a UI action or business rule, pass the current object as the parentRecord instead.

var parentRecord = new GlideRecordUtil().getGR("interaction", "148776e5818d7410f87701eb89fdc824");

// demo playbook from Process Automation Experience Demo store app
var scopedName = "sn_pad_demo.playbook_experience_demo"; 

var hasPlaybooks = sn_playbook.PlaybookExperience.parentRecordContainsPlaybook(parentRecord, scopedName);
gs.info(hasPlaybooks);

Output:

true

PlaybookExperience - restartPlaybook(String playbookContextId, String laneContextId, String activityContextId, String playbookExperienceId)

Restarts an execution from the beginning (the entire playbook) or from a specific stage or activity of a playbook.

Note: Only playbooks that are In Progress, Queued, or Pending Cancel state can be restarted.
Table 7. Parameters
NameTypeDescription
playbookContextId String Sys_id of the playbook context record for the playbook run or execution that you want to restart.

Table: Process Execution [sys_pd_context]
laneContextId String Optional. The sys_id of the stage context record for the stage run or execution that you want to restart from.
Note: Only complete stages can be restarted.

Table: Lane Executions [sys_pd_lane_context]
activityContextId String Optional. The sys_id of the activity context record for the activity run or execution that you want to restart from.
Note: Only complete activities can be restarted.

Table: Activity Executions [sys_pd_activity_context]
playbookExperienceId String Optional. The sys_id of the playbook experience that you want to use for the restarted run. Use this parameter if you have defined custom activity state mappings. See Playbook activity state mapping.

Default: Global Playbook Experience

Table: Playbook Experience [sys_playbook_experience]
Table 8. Returns
PropertyDescription
Object Object containing the restarted playbook execution details.
{
 "can_add_activity": Boolean,
 "can_cancel": Boolean,
 "can_read": Boolean
 "can_restart": Boolean,
 "canceled_by": "String",
 "cancellation_reason": "String",
 "errors": [Array]
 "is_archived": Boolean
 "parent_record": "String",
 "parent_table": "String",
 "playbook_id": "String",
 "playbook_table": "String",
 "scoped_name": "String",
 "state": {Object},
 "sys_id": "String",
 "title": "String",
}
can_add_activity Flag that indicates whether a user can add an optional activity to the playbook.
Valid values:
  • true: Current user can add an optional activity to the playbook.
  • false: Current user can’t add an optional activity to the playbook.

Data type: Boolean
can_cancel Flag that indicates whether a user can cancel a playbook.
  • true: The process definition for the deactivated playbook is active.
  • false: The process definition for the deactivated playbook is inactive.

Data type: Boolean
can_read Flag that indicates whether the current user can read the playbook execution record. The current user must have read access to the parent record to be able to read the playbook execution record.
  • true: Current user has read access to the playbook execution record.
  • false: Current user doesn't have read access to the playbook execution record.

Data type: Boolean
can_restart Flag that indicates whether a user can restart a playbook, stage, or activity.
  • true: Current user can restart the playbook, stage, or activity.
  • false: Current user can’t restart the playbook, stage, or activity.

Data type: Boolean
canceled_by User ID of the user who canceled the playbook execution.

Data type: String
cancellation_reason Cancellation reason entered by the user who canceled the playbook execution.

Data type: String
errors List of restart errors. Each error is an object in the array.

Data type: Array

"errors": [
 {      
  "message": "String",
  "type": "String"  
 }
]
is_archived Flag that indicates whether playbook context records are archived.
Possible values:
  • true: Playbook context records are archived.
  • false: Playbook context records aren’t archived.

Data type: Boolean
parent_record Sys_id of the parent record that playbook executions were restarted for.

Data type: String
parent_table Name of the table that the parent record is from.

Data type: String
playbook_id Sys_id of the playbook.

Data type: String

Table: Process Definitions [sys_pd_process_definition]
playbook_table Name of the table that the playbook is from, generally the Process Definitions [sys_pd_process_definition] table.

Data type: String
scoped_name Optional. The scoped name of the playbook to restart. The scoped name is from the Process Definition [sys_pd_process_definition] table in the format scope.name. If provided, only executions of this playbook are restarted for the given parent record. If not provided, all executions of all playbooks are restarted for the given parent record.

Data type: String
state Indicates whether your request to activate was successful.

Data type: Object

Possible values:
  • SUCCESS: The playbook was successfully activated.
  • FAILURE: The ID for the playbook wasn’t found.
"state": [
    {      
      "displayValue": "String",
      "value": "String"  
    }
]
state.displayValue Display value of the playbook execution state.

Data type: String
state.value Value of the playbook execution state.

Data type: String
sys_id Sys_id of the playbook execution.

Data type: String

Table: Process Executions [sys_pd_context]
title Label of the playbook execution.

Data type: String

Table: Process Executions [sys_pd_context]

Example

This example shows how to restart an entire playbook run with the Process Executions [sys_pd_context] record ID 98e4fe04591b4caca59583f7b8e30b0a.

var gr = new GlideRecord('sys_pd_context');
var found = gr.get('98e4fe04591b4caca59583f7b8e30b0a'); 
if (found) {
    var result = sn_playbook.PlaybookExperience.restartPlaybook(gr);
    gs.info(JSON.stringify(result));
}
else
    gs.info('invalid pd context');

Output:

{
 "scoped_name": "global.restart_scriptable_demo",
 "canceled_by": "",
 "can_add_activity": true,
 "playbook_table": "sys_pd_process_definition",
 "can_restart": true,
 "can_cancel": true,
 "title": "Restart scriptable demo",
 "cancellation_reason": "",
 "parent_table": "interaction",
 "can_read": true,
 "sys_id": "98e4fe04591b4caca59583f7b8e30b0a",
 "is_archived": false,
 "state": {
   "displayValue": "In Progress",
   "value": "IN_PROGRESS"
 },
 "parent_record": "b88623beb5e10210f877d783f6f83a46",
 "playbook_id": "12d5a7fab5e10210f877d783f6f83aff",
 "errors": []
}

PlaybookExperience - triggerPlaybook(String scopedName, GlideRecord parentRecord)

Initiates a playbook for a parent record.

Table 9. Parameters
Name Type Description
scopedName String The scoped name of the playbook to initiate. The scoped name is from the Process Definition [sys_pd_process_definition] table in the format scope.name.
parentRecord GlideRecord The parent record to initiate a playbook for. The parent record can be any record that can have playbook executions, such as an interaction record or an onboarding case record.
Table 10. Returns
Type Description
String Sys_id of the playbook execution from the Process Executions [sys_pd_context] table that was created for the parent record. Null if a playbook execution wasn't successfully created.

Example

This example shows how to initiate a playbook for a given interaction record. To use this method in a UI action or business rule, pass the current object as the parentRecord instead.

var parentRecord = new GlideRecordUtil().getGR("interaction", "148776e5818d7410f87701eb89fdc824");

// demo playbook from Process Automation Experience Demo store app
var scopedName = "sn_pad_demo.playbook_experience_demo"; 

var playbookExecution = sn_playbook.PlaybookExperience.triggerPlaybook(scopedName, parentRecord);
gs.info(playbookExecution);

Output:

f059958267cdb410952864f0fed358cc