Creating a Workflow Playbook

Updated on 30 Aug 2022
11 Minutes to read

Print
Dark

Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Follow these steps to create a Workflow Playbook and configure the Workflow Trigger used in the Playbook.

On the top navigation bar, click Playbooks to display the Playbooks screen.
Hover over the NEW button at the upper-left corner of the Playbooks screen and select Create Playbook. The Create Playbook window will be displayed (Figure 1).
- Name: Enter a name for the Workflow Playbook.
- Description: Enter an optional description of the Playbook.
- Type: Select Workflow.
- Click the SAVE button.
The Playbook Designer will open (Figure 2). By default, a Workflow Trigger is added to the Workflow Playbook when it is created. This Trigger is the element that causes the Workflow Playbook to execute and defines the behavior of the Playbook (i.e., the inputs and outputs) when it is used in a Workflow Task. No other Triggers may be added to a Workflow Playbook.
Click Summary on the side navigation bar of the Playbook Designer to display the Summary pane (Figure 3). In the METADATA section of the Summary pane, you can click Edit to edit the Playbook’s Name or Description and add or remove Labels, which are keywords used to classify Playbooks. For example, labels such as “In Design” and “QA” can be used to track the development or status of Playbooks, and labels such as “Enrichment” and “Reporting” can be used to make filtering by Playbook type more manageable.

Note
Labels can be used to mark Workflow Playbooks as such. In addition, filtering for Workflow Playbooks from the Playbooks screen can be accomplished by selecting Workflow under the Type menu, which will cause only Playbooks with Workflow Triggers to be displayed.
Double-click the Workflow Trigger. The Inputs section of the Edit Trigger pane will be displayed (Figure 4).
- Trigger Name: Enter a name for the Workflow Trigger.
- Run as current user: When this checkbox is selected, the Workflow Playbook will be run by the user who created the Case containing the automated Task using the Workflow Playbook, or, if the automated Task was executed ad hoc, by the user who executed the Task. If this checkbox is not selected, the Workflow Playbook will be run by the user selected in the Run As dropdown menu under the Settings menu of the Playbook.
Click the plus icon to display the Create Parameter: configuration options (Figure 5). This section is where specifications for the variable(s) that pass information from a Case or Task into a Workflow Playbook are entered.
- Label: Enter a name for the parameter that will pass information into the Workflow Playbook. This information will be displayed in the Run Playbook drawer within the Workflow Case that calls the Playbook.
- Variable Name: This field will autofill the name of the corresponding input variable for the parameter, based on the provided label. For example, if the label is Sample Input Parameter, then the Variable Name will fill as sample_input_parameter. This field cannot be edited.
- UI Element: Select the type of element (TextField, Editable Choice, Dropdown, Checkbox, Multiselect Dropdown, or Key/Value List) that will render for this parameter in the Run Playbook drawer within the Workflow Case that calls the Playbook.
  Important
  The choice of UI Element will determine the rest of the fields in the Create Parameter: section that can be configured. For example, if the TextField element is selected, users can configure the Default Value, Enable Multi-line, Data Type, Required, Allow Text Variables, and Encrypted & Allow Keychain Variables options, whereas if the Checkbox element is selected, users can configure only the Default Value option, and all remaining options will be grayed out.
  Note
  Internal variables such as ${OWNERS} (i.e., the list of all available owners in the user’s Organization) may be entered as a dropdown option so that the user does not have to enter every element contained within the variable manually. In this example, users configuring the Playbook in the Run Playbook drawer within a Case would see a list of all available owners in their Organization for the parameter.
  - TextField (Figure 5)
    - Default Value: Enter a default value that will be displayed for the parameter in the Run Playbook drawer within the Workflow Case that calls the Playbook, if desired.
    - Enable Multi-line: Select the checkbox to display a TextField input field with multiple lines in the Run Playbook drawer within the Workflow Case that calls the Playbook.
    - Data Type: Select one or more types of data that the parameter will take. The letter to the left of each selection provides a quick reference to the type of data, with the array versions of a data type having the same letter as the non-array versions (e.g., both String and StringArray are represented by “S”), but appearing in a square instead of a circle.
    - Required: Select the checkbox to require the user to enter a value for this parameter.
    - Allow Text Variables: Select the checkbox to allow text variables to be entered as values for this parameter.
    - Encrypted & Allow Keychain Variables: Select the checkbox to enable encryption and allow keychain variables to be entered as values for this parameter.
  - Editable Choice (Figure 6)
    - Default Value: Enter a default value that will be displayed for the parameter in the Run Playbook drawer within the Workflow Case that calls the Playbook, if desired.
    - Dropdown Options: Enter pipe-delimited (|) dropdown options that users will choose from in the Run Playbook drawer within the Workflow Case that calls the Playbook.
    - Required: Select the checkbox to require the user to select a value for this parameter.
    - Allow Text Variables: Select the checkbox to allow text variables to be entered as values for this parameter.
  - Dropdown (Figure 7)
    - Default Value: Enter a default value that will be displayed for the parameter in the Run Playbook drawer within the Workflow Case that calls the Playbook, if desired.
    - Dropdown Options: Enter pipe-delimited (|) dropdown options that users will choose from in the Run Playbook drawer within the Workflow Case that calls the Playbook.
    - Required: Select the checkbox to require the user to select a value for this parameter.
  - Checkbox (Figure 8)
    - Default Value: Specify whether the Checkbox parameter will be selected (True) or cleared (False) by default.
  - Multiselect Dropdown (Figure 9)
    - Default Value: Enter a default value that will be displayed for the parameter in the Run Playbook drawer within the Workflow Case that calls the Playbook, if desired. Multiple values separated by the pipe (|) character may be entered as default values.
    - Dropdown Options: Enter pipe-delimited (|) dropdown options that users will choose from in the Run Playbook drawer within the Workflow Case that calls the Playbook.
    - Required: Select the checkbox to require the user to select a value for this parameter.
  - Key/Value List (Figure 10)
    - Data Type: Select one or more types of data that the parameter will take. The letter to the left of each selection provides a quick reference to the type of data, with the array versions of a data type having the same letter as the non-array versions (e.g., both String and StringArray are represented by “S”), but appearing in a square instead of a circle.
    - Required: Select the checkbox to require the user to select a value for this parameter.
    - Allow Text Variables: Select the checkbox to allow text variables to be entered as values for this parameter.
    - Encrypted & Allow Keychain Variables: Select the checkbox to enable encryption and allow keychain variables to be entered as values for this parameter.
- Click the CREATE button.
  Note
  Workflow Triggers are configured similarly to Component Triggers, but within the context of passing information to and from a Workflow instead of a Playbook from which the Component is called.
The new input parameter will be displayed in the table on the Inputs section of the Edit Trigger pane (Figure 11).
- Vertical ellipsis : Hover over this icon to the right of the value in the Data Type column to display a summary of the parameter’s settings (Figure 12).
- Edit : Click this icon to edit the parameter.
- Delete : Click this icon to delete the parameter.
  Important
  Clicking Delete deletes the parameter immediately. No window or message will be displayed to ask for confirmation first.
- Move =: To reorder the parameters listed in the table, click this icon and drag the parameter to the desired location in the table.
Repeat Steps 6 and 7 to add information for all remaining parameters. Once you have created all input parameters, click the NEXT button. The Outputs section of the Edit Trigger pane will be displayed (Figure 13).
Click the SAVE button without adding output variables. Output variables are used to pass information back to the Case or Task that called the Workflow Playbook, but the list of potential values will first need to be populated by the Apps that connect to the Workflow Trigger. As such, the output variables must be added after all Apps are added to the Playbook.
Hover the cursor over the hashtag (#) at the upper-left corner of the Workflow Trigger in the design pane to display a list of output variables (Figure 14). These values are the variables available for use by downstream Apps in the Workflow Playbook and are distinct from the output variables referred to in the previous step, which are the variables returned by the Workflow Playbook to the Workflow Case or Task that called it.
- Workflow-specific variables:
  - #tc.case_id and #tc.case: A String and a TCEntity, respectively, that provide the identification number of the Workflow Case calling the Playbook. These variables can be used to identify the Case when using a Playbook App to pull data from the Case (e.g., Artifact, Note).
  - #tc.wf.username, #tc.wf.firstname, and #tc.wf.lastname: A string that provides the username, first name, and last name, respectively, of the user that executed the Workflow Playbook within a Case or Task. These variables can be used to track which users executed the Playbook and assign Cases and Tasks to the appropriate user.
    Note
    The #tc.wf.username, #tc.wf.firstname, and #tc.wf.lastname variables provide the username, first name, and last name, respectively, of the user that executed the Playbook, regardless of whether you selected the Run as current user checkbox when configuring the Workflow Trigger.
- Input parameters from the Workflow Trigger: The input parameters defined in the Workflow Trigger are the information that the Workflow Playbook requires when it is called by a Case or Task. Those parameters are then passed to the Workflow Trigger as output variables to the rest of the Playbook and are displayed under the Workflow-specific variables (e.g., #email_subject and #email_body in this example). A second version of each input parameter from the Workflow Trigger is provided as an Artifact ID (e.g., #email_subject.tc.artifact_id and #email_body.tc.artifact_id in this example). If the original input parameter is indeed an Artifact, the corresponding Artifact ID parameter will be populated with the identification number of the Artifact, allowing Apps in the Playbook to access the Artifact.
  Note
  Depending on the number of input parameters added to the Workflow Trigger, you may need to scroll down the list to view all output variables. In this example, the #email_body, #email_subject.tc.artifact_id, and #email_body.tc.artifact_id variables are not displayed in Figure 15 until you scroll down the list.
Add Apps and Operators to the Workflow Playbook in the same way that they would be added to a regular Playbook. It is good practice to connect the end of all possible pathways back to the Workflow Trigger so that it receives the final output from the pathway(s) the Workflow takes and can pass that information back to the calling Case or Task in Workflow.
Double-click the Workflow Trigger to edit it again. In the Edit Trigger pane, click the NEXT button (Figure 11) to go to the Outputs section (Figure 13).
For each output variable, enter a name in the Name field, and then, if desired, type a hashtag (#) in the Value field to display a dropdown list of possible values (Figure 15). Select a value from the list, or enter a value manually.

Note
The actual values provided will depend on the Apps used in the Playbook.
Note
The Workflow Trigger supports the String, Binary, StringArray, and BinaryArray data types for its outputs.
Note
You can also build Workflow Playbooks by adding Apps before configuring any part of the Workflow Trigger (i.e., before adding input variables). Once you have configured all Apps and built all pathways, configure the Workflow Trigger in full (i.e., input variables and then output variables).
Click the plus icon to add the variable to the Trigger (Figure 16).
- Edit : Click this icon to edit the variable. When editing a variable, the Variables fields will populate with its name and value. Make the changes in those fields, and then click the checkmark or X icon to accept or reject the changes, respectively.
  Important
  While editing a variable, the Edit, Copy, Delete, and Move icons will be disabled for all variables listed in the table.
- Copy : Click this icon to duplicate the variable. A copy of the variable will be added to the table with the text “_copy” appended to its name (e.g., myEmail_copy). This functionality is useful when you want to create a new variable based on an existing one.
  Important
  If you duplicate the same variable more than once without changing the first copy’s name, duplicate entries will be displayed in the table, an error notification will be displayed at the bottom left of the screen, and you will be prevented from saving the Workflow Trigger’s configuration until you change the name of all copies with the same name.
  Note
  To copy only the contents of a name or value field in the table, highlight the corresponding text and use your browser’s copy functionality (e.g., Command-C).
- Delete : Click this icon to delete the variable.
  Important
  Clicking Delete deletes the parameter immediately. No window or message will be displayed to ask for confirmation first.
- Move =: To reorder the variables listed in the table, click this icon and drag the variable to the desired location in the table.
Once you have entered all variables, click the SAVE button.
Once you have fully configured the Workflow Playbook, hover over the Mode dropdown menu at the upper-right corner of the Playbook Designer and select Active. The Playbook will switch from Design Mode to Active (Figure 17).

Note
A Workflow Playbook must be active in order to be called by a Case or Task.
Note
Topics not specifically covered in this article, such as Workflow Playbook administrative functionalities (e.g., cloning, deleting, importing, exporting, versions, return on investment) and execution and logging, can be found in the Playbooks articles.