---
sourceDocument: Xanadu API Reference
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# PDAutomationProvider - Scoped, Global

# PDAutomationProvider - Scoped, Global {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 minutes to read

The PDAutomationProvider API enables inserting an optional activity
into a process while it's executing.

This API is part of the Playbooks plugin (com.glide.pad.core) and runs in the `sn_pad` namespace.  
Calling scripts with this API requires at least one of the following:

* The caller must be in the same scope in which the optional activity trigger was created.
* Admin privileges.
{#PDAutomationProviderBothAPI__ul_glp_zx2_5rb}

A process is a series of activities ordered by lanes. An optional activity is predefined
during process design. The activities aren't scheduled to run at a precise time. An activity
can be assigned to a lane and made available to run during lane execution. An activity can be
assigned to a process and made available to run during lane execution.

To create an optional activity, it must have the Start rule set to Manual in the Activities \[sys_pd_activity\] table.
Playbooks doesn't currently support creating manual activities.

An agent adds the optional activity to a lane or activity relative to another activity. The
process must be running to insert an optional activity.  
See also:

* [Design an automated
  process](https://www.servicenow.com/docs/access?context=design-automated-process&version=xanadu&pubname=xanadu-build-workflows&ft:locale=en-US)
* [Process Automation Designer lanes
  and activities](https://www.servicenow.com/docs/access?context=process-automation-designer-lanes-activities&version=xanadu&pubname=xanadu-build-workflows&ft:locale=en-US)
{#PDAutomationProviderBothAPI__ul_a1m_lxj_5rb}

## PDAutomationProvider -- activateProcess(String processDefinitionSysId) {#ariaid-title2}

Activates a playbook.
{#PDAuto-activateProcess_S__table_zkb_lbs_1cc__entry__3}

| Name | Type | Description |
|-|-|-|
| processDefinitionSysId | String | The sys_id of a playbook located in the Process Definitions \[sys_pd_process_definition\] table. |
[Table 1. Parameters]

{#PDAuto-activateProcess_S__table_zkb_lbs_1cc} {#PDAuto-activateProcess_S__table_alb_lbs_1cc__entry__2}

| Property | Description |
|-|-|
| Object | Object containing process definition activation details. { "errors": [Array] "process_definition": {Object}, "state": "String" } |
| errors | List of errors. Empty if successful. Data type: Array of String(s) |
| process_definition | The activated playbook and its properties. Data type: Object "process_definition": { "active": Boolean, "snapshot": {Object}, "status": "String" } |
| process_definition.active | Flag that indicates whether the process definition for the deactivated playbook is active. Find process definitions in the Process Definitions \[sys_pd_process_definition\] list. Valid values: * true: The process definition for the deactivated playbook is active. * false: The process definition for the deactivated playbook is inactive. {#PDAuto-activateProcess_S__ul_vl4_xtp_ccc} Data type: Boolean |
| process_definition.snapshot | Contains details about the process definition at the time of activation. Data type: Object { "snapshot": { "created": "String", "processDefinitionSysId": "String" } } |
| process_definition. snapshot. created | The date that the playbook was created. Data type: String |
| process_definition. snapshot. processDefinitionSysId | The sys_id of the activated playbook. Data type: String |
| process_definition.status | Indicates the publishing status of the playbook. Possible values: * draft: The playbook is in draft state. * published: The playbook is in published state. {#PDAuto-activateProcess_S__ul_exj_hj3_2cc} Data type: String |
| state | Indicates whether your request to activate was successful or not. Possible values: * SUCCESS -- The playbook was successfully activated. * FAILURE -- The ID for the playbook was not found. Data type: Object |
[Table 2. Returns]

{#PDAuto-activateProcess_S__table_alb_lbs_1cc}  
The following example shows how to activate a playbook.

    var myPlaybook = sn_pad.PDAutomationProvider.activateProcess('cdd1b85e43000210d96e29c28ab8f275');
    gs.info(JSON.stringify(myPlaybook));

Output:

    {
      "process_definition": {
        "active": true,
        "snapshot": {
          "processDefinitionId": "cdd1b85e43000210d96e29c28ab8f275",
          "created": "2024-02-19 22:58:12"
        },
        "status": "published"
      },
      "state": "SUCCESS",
      "errors": []
    }

## PDAutomationProvider -- addOptionalActivityRelativeToActivityContext(String contextID,
String activityId, String where, String relativeToId) {#ariaid-title3}

Adds a specified optional activity to a process to be run relative to another activity
during process execution.
An activity context is created for each activity when a process executes. The context also
handles how the activity handles execution. For information, see [Process Automation Designer lanes and
activities](https://www.servicenow.com/docs/access?context=process-automation-designer-lanes-activities&version=xanadu&pubname=xanadu-build-workflows&ft:locale=en-US).
{#PDAuto-addRelToActvtyCntxt_S_S_S_S__PDAutoParms__entry__3}

| Name | Type | Description |
|-|-|-|
| contextID | String | Sys_id of the activity execution in which to add the optional activity. To access, click the process listed in the Process Executions \[sys_pd_context\] table. The execution selected must be in a state of In Progress. |
| activityId | String | Sys_id of the optional activity listed in the Activities \[sys_pd_activity\] table. Note: To create an optional activity, it must have the Start rule set to Manual in the Activities \[sys_pd_activity\] table. |
| where | String | Indicates where to place the activity in the process. Valid values: * AFTER -- Execute this activity after the relative activity context. * WITH -- Execute the activity at the same time as another relative activity context. {#PDAuto-addRelToActvtyCntxt_S_S_S_S__ul_tlq_mdl_lrb} |
| relativeToId | String | ID of the relative activity context that the optional activity will run after or with. Listed in the Activity Context \[sys_pd_activity_context\] table. |
[Table 3. Parameters]

{#PDAuto-addRelToActvtyCntxt_S_S_S_S__PDAutoParms} {#PDAuto-addRelToActvtyCntxt_S_S_S_S__PDAutoReturns__entry__2}

| Type | Description |
|-|-|
| Boolean | Flag that indicates whether the activity was successfully scheduled to run. Valid values: * true: Activity is successfully scheduled to run. The output is a string stating success. * false: Activity isn't successfully scheduled to run. The output is an array of one or more error messages. {#PDAuto-addRelToActvtyCntxt_S_S_S_S__ul_a4j_yvl_nrb} If errors, list of one or more error messages. Message stating Array of 0 or more elements otherwise. |
| Array | If errors, list of one or more error messages. Message stating Array of 0 or more elements otherwise. Possible error messages: * Invalid Optional activity Id -- The sys_id provided for the activityId parameter is invalid. * Invalid PD context Id -- The Process Designer (PD) sys_id provided in the contextID parameter is invalid. * Invalid position type -- The position type provided is invalid. See the description of the where parameter for valid types. * Invalid Relative-to Id -- The sys_id provided for the relativeToId parameter is invalid. * Optional activity not found -- The sys_id provided for the activityId parameter wasn't found. * Process must still be active -- The process containing this activity must be active to run the optional activity. * Relative activity context not found -- The sys_id provided for the relativeToId parameter was not found. {#PDAuto-addRelToActvtyCntxt_S_S_S_S__ul_o5f_p12_5rb} |
[Table 4. Returns]

{#PDAuto-addRelToActvtyCntxt_S_S_S_S__PDAutoReturns}  
The following example shows how to run an optional activity simultaneously with the
relative activity context.

    var contextId = '<context_id>';
    var optionalActivityId = '<optional_activity_id>';
    var where = 'WITH'; // options AFTER, WITH
    var relativeToId = '<relative_activity_context_id>'; // relative activity context ID

    var response = sn_pad.PDAutomationProvider.addOptionalActivityRelativeToActivityContext(contextId, optionalActivityId, where, relativeToId);

    gs.info(JSUtil.describeObject(response));

Output (success):

    success: boolean = true
    errors: Array of 0 elements

## PDAutomationProvider -- addOptionalActivityRelativeToLaneContext(String contextID, String
activityId, String where, String relativeToId) {#ariaid-title4}

Assigns an optional activity to a lane to run during that lane's execution
context.
A lane context is created for each lane when a process executes. The context also handles
how the lane handles execution. For information, see [Process Automation Designer lanes and
activities](https://www.servicenow.com/docs/access?context=process-automation-designer-lanes-activities&version=xanadu&pubname=xanadu-build-workflows&ft:locale=en-US).
{#PDAuto-addRelToLaneContext_S_S_S_S__PDAutoParms__entry__3}

| Name | Type | Description |
|-|-|-|
| contextID | String | Sys_id of the activity execution in which to add the optional activity. To access, click the process listed in the Process Executions \[sys_pd_context\] table. The execution selected must be in a state of In Progress. |
| activityId | String | Sys_id of the optional activity listed in the Activities \[sys_pd_activity\] table. Note: To create an optional activity, it must have the Start rule set to Manual in the Activities \[sys_pd_activity\] table. |
| where | String | Indicates where to place the activity in the process. Valid values: * LAST -- Execute as the final activity in a lane context. * NEXT -- Execute in the next activity in a lane context. {#PDAuto-addRelToLaneContext_S_S_S_S__ul_tlq_mdl_lrb} |
| relativeToId | String | ID of the relative lane context in which the optional activity is to run. Listed in the Lane Context \[sys_pd_lane_context\] table. |
[Table 5. Parameters]

{#PDAuto-addRelToLaneContext_S_S_S_S__PDAutoParms} {#PDAuto-addRelToLaneContext_S_S_S_S__PDAutoReturns__entry__2}

| Type | Description |
|-|-|
| Boolean | Flag that indicates whether the activity was successfully scheduled to run. Valid values: * true: Activity is successfully scheduled to run. The output is a string stating success. * false: Activity isn't successfully scheduled to run. The output is an array of one or more error messages. {#PDAuto-addRelToLaneContext_S_S_S_S__ul_a4j_yvl_nrb} |
| Array | If errors, list of one or more error messages. Message stating Array of 0 or more elements otherwise. Possible error messages: * Invalid Optional activity Id -- The sys_id provided for the activityId parameter is invalid. * Invalid PD context Id -- The Process Designer (PD) sys_id provided in the contextID parameter is invalid. * Invalid position type -- The position type provided is invalid. See the description of the where parameter for valid types. * Invalid Relative-to Id -- The sys_id provided for the relativeToId parameter is invalid. * Optional activity cannot be added to lane -- The optional activity provided in the activityId parameter can't be added relative to the lane provided in the relativeToId parameter. Make sure that the Activity Execution selected is in the In Progress state. * Optional activity not found -- The sys_id provided for the activityId parameter wasn't found. * Process must still be active -- The process containing this activity must be active to run the optional activity. * Relative lane context not found -- The sys_id provided for the relativeToId parameter was not found. {#PDAuto-addRelToLaneContext_S_S_S_S__ul_xw3_422_5rb} |
[Table 6. Returns]

{#PDAuto-addRelToLaneContext_S_S_S_S__PDAutoReturns}  
The following example shows how to run an optional activity as the final activity in a lane
context.

    var contextId = '<context_id>';
    var optionalActivityId = '<optional_activity_id>';
    var where = 'LAST'; // options LAST, NEXT
    var relativeToId = '<relative_lane_context_id>'; // relative lane context ID

    var response = sn_pad.PDAutomationProvider.addOptionalActivityRelativeToLaneContext(contextId, optionalActivityId, where, relativeToId);

    gs.info(JSUtil.describeObject(response));

Output (success):

    success: boolean = true
    errors: Array of 0 elements

## PDAutomationProvider -- deactivateProcess(String processDefinitionSysId) {#ariaid-title5}

Deactivates a playbook.
{#PDAuto-deactivateProcess_S__table_zkb_lbs_1cc__entry__3}

| Name | Type | Description |
|-|-|-|
| processDefinitionSysId | String | The sys_id of a playbook located in the Process Definitions \[sys_pd_process_definition\] table. |
[Table 7. Parameters]

{#PDAuto-deactivateProcess_S__table_zkb_lbs_1cc} {#PDAuto-deactivateProcess_S__table_alb_lbs_1cc__entry__2}

| Property | Description |
|-|-|
| Object | Object containing process definition deactivation details. { "errors": [Array] "process_definition": {Object}, "state": "String" } |
| errors | List of errors. Empty if successful. Data type: Array of String(s) |
| process_definition | The deactivated playbook and its properties. Data type: Object "process_definition": { "active": Boolean, "snapshot": {Object}, "status": "String" } |
| process_definition.active | Indicates whether the process definition for the deactivated playbook is active. Find process definitions in the Process Definitions \[sys_pd_process_definition\] list. Possible values: * true: The process definition for the deactivated playbook is active. * false: The process definition for the deactivated playbook is inactive. {#PDAuto-deactivateProcess_S__ul_idr_br3_2cc} Data type: Boolean |
| process_definition.description | Details about your deactivated playbook. Data type: String |
| process_definition.label | The name of the deactivated playbook that users see in the interface. Data type: String |
| process_definition.name | The name for the deactivated playbook in the code. Only used as a request parameter in scripting. Data type: String |
| process_definition.scope | The sys_id of the application scope that your playbook is deactivated for. Data type: String |
| process_definition.status | If the playbook is published, it changes back to a draft. Data type: String |
| state | Indicates whether deactivation was successful. Possible values: * SUCCESS -- The playbook was successfully deactivated. * FAILURE -- The ID for the playbook was not found. {#PDAuto-deactivateProcess_S__ul_zfl_k34_2cc} Data type: String |
[Table 8. Returns]

{#PDAuto-deactivateProcess_S__table_alb_lbs_1cc}  
Deactivate the playbook.

    sn_pad.PDAutomationProvider.deactivateProcess('cdd1b85e43000210d96e29c28ab8f275')

Outputs:

    {"process_definition":{"scope":"global","name":"test","active":true,"description":"","label":"test","status":"draft"},"state":"SUCCESS"}

## PDAutomationProvider -- duplicateProcess(String processDefinitionSysId, String label, String description, String scopeId, String triggerTypeId) {#ariaid-title6}

Duplicates a playbook.
{#PDAuto-duplicateProcess_S_S_S_S_S__table_zkb_lbs_1cc__entry__3}

| Name | Type | Description |
|-|-|-|
| processDefinitionSysId | String | The sys_id of a playbook located in the Process Definitions \[sys_pd_process_definition\] table. |
| label | String | The name of the duplicated playbook. |
| description | String | Optional. Add details about your playbook. |
| scopeId | String | The sys_id of the application scope that you want your playbook to run in. The scoped name is from the Process Definition \[sys_pd_process_definition\] table in the format `scope.name`. Entering the sys_id for the global scope lets your playbook run in any application scope. |
| triggerTypeId | String | The sys_id of the trigger from which to initiate playbook runs. Find the trigger type in the Trigger Type \[sys_pd_trigger_type\] table and copy its sys_id. |
[Table 9. Parameters]

{#PDAuto-duplicateProcess_S_S_S_S_S__table_zkb_lbs_1cc} {#PDAuto-duplicateProcess_S_S_S_S_S__table_alb_lbs_1cc__entry__2}

| Property | Description |
|-|-|
| Object | Object containing process definition duplication details. { "errors": [Array] "processDefinitionSysId": "String", "state": "String" } |
| errors | List of errors. Empty if successful. Data type: Array of String(s) Possible error messages: * Scope not found for scopeId: xyz * Process definition not found for id: xyz * Trigger type not found for triggerTypeId: xyz {#PDAuto-duplicateProcess_S_S_S_S_S__ul_df4_hkt_bcc} |
| processDefinitionSysId | The sys_id of the new playbook in the Process Definitions \[sys_pd_process_definition\] table. Data type: String |
| state | Indicates whether playbook duplication was successful. Possible values: * SUCCESS -- The playbook was successfully duplicated. * FAILURE -- The ID for the playbook, application scope, or trigger was not found. {#PDAuto-duplicateProcess_S_S_S_S_S__ul_zq2_434_2cc} Data type: Object |
[Table 10. Returns]

{#PDAuto-duplicateProcess_S_S_S_S_S__table_alb_lbs_1cc}  
This example shows how to duplicate a playbook with the sys_id `f8ca6192ec210210f8772cbd595eab20`. The new playbook is named Playbook 2.0, has an application scope of
Global, and is triggered when a record is created. The Record Create trigger type has a sys_id of `ab6951170f1200108c87f4f0ff767e4f`.

    sn_pad.PDAutomationProvider.duplicateProcess('f8ca6192ec210210f8772cbd595eab20', 'Playbook 2.0', '', 'global', 'ab6951170f1200108c87f4f0ff767e4f');

Output:

    {"processDefinitionSysId":"6e4f0b8fece9c210f8772cbd595eabda","state":"SUCCESS"}