PDAutomationProvider - Scoped, Global

  • Release version: Yokohama
  • Updated January 30, 2025
  • 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.

    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:

    PDAutomationProvider – activateProcess(String processDefinitionSysId)

    Activates a playbook.

    Table 1. Parameters
    Name Type Description
    processDefinitionSysId String Sys_id of a playbook.

    Table: Process Definitions [sys_pd_process_definition]
    Table 2. Returns
    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.

    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.

    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

    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)

    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.

    Table 3. Parameters
    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.
    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 4. Returns
    Type Description
    Boolean Flag that indicates whether the activity was successfully scheduled to run.
    Possible 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.

    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.

    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)

    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.

    Table 5. Parameters
    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.
    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 6. Returns
    Type Description
    Boolean Flag that indicates whether the activity was successfully scheduled to run.
    Possible 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.
    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.

    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)

    Deactivates a playbook.

    Table 7. Parameters
    Name Type Description
    processDefinitionSysId String Sys_id of a playbook.

    Table: Process Definitions [sys_pd_process_definition]
    Table 8. Returns
    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.

    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.

    Data type: String

    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)

    Duplicates a playbook.

    Table 9. Parameters
    Name Type Description
    processDefinitionSysId String Sys_id of a playbook.

    Table: Process Definitions [sys_pd_process_definition]
    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 10. Returns
    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
    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.

    Data type: Object

    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"}