Workflow Automation CoE > Playbooks > Custom Playbook Activities
Goal
In this Workflow Automation Center of Excellence article, you will learn how to create a Custom Playbook Activity Definition including defining a Custom Activity UI in UI Builder.
If you prefer to watch a video over a written guide, check out this Workflow Academy session on Custom Playbook Activities.
Technology
Workflow Studio is our central, low-code workflow automation builder that consolidates Flow Designer, Process Automation Designer, Decision Builder, and Action Designer into a single design environment.
To build custom activity definitions and activity UI, we can use these product features:
Lastly, we will cover some good practices for building custom playbook activities and the corresponding activity UIs.
Introduction
Playbooks empower organizations to automate business processes. Playbooks leverage flows and add a UI layer to business logic. They allow agents and requesters to visualize and interact with a defined business process. Custom activities extend this functionality by allowing you to create specific actions with a tailored user experience to use in your playbooks.
Instructions
Use Case
The example activity we want to build today will collect arbitrary data from the process worker, process them in a subflow with a decision table, then return some info as subflow outputs for use later in the playbook. We will also create a custom activity UI to display to the agent at runtime.
There are five main steps to creating this activity:
1. Create a data definition to collect data. This data definition will be used to specify the type of data that will be collected by the activity.
2. Build a subflow to process the data. The subflow will define the logic that will be executed by the activity. It will use a decision table to determine values as subflow outputs.
3. Create an activity definition. The activity definition will specify the name, description, and inputs/outputs of the activity. You can optionally add an activity experience to determine how the activity is represented on the Playbook component.
4. Test the activity in the Playbook. Once you have created your custom activity, you can test it within a playbook to ensure that it is working as expected.
5. Create custom activity UI. Duplicate and modify the activity UI in UI Builder.
Step 0: Explore the Decision Table
From the All Application Navigator, I choose Process Automation > Workflow Studio, which opens in a new tab.
My decision table has two inputs, an Integer for the session length, and a String for the session title. From these inputs I can determine the academy type, for which I reuse an existing choice field on my custom table (extended from task).
Step 1: Create a Data Definition
Create Data Definition
Moving back to the main ServiceNow tab, I navigate to Playbook Experience > Data Definitions.
I click on New to create a new Data Definition, give it a meaningful name and save.
Create Flow Data Variables
Next, I can add Flow Data Variables in the related list. For this demo, I’m adding the same two fields that I have in the decision table, Session Length (Integer) and Academy Title (String). Take note of the variable internal name, we will need that later in the subflow.
Flow Data Variables can be any field type that’s generally available on the platform. If you click on “Advanced View”, you can also make one variable dependent on another input, e.g. being able to filter references based on an earlier input.
Step 2: Build a Subflow
Create Subflow with inputs and outputs
Switching back to the Workflow Studio tab, I click on New > Subflow to create a new automation for my playbook. Give your subflow a meaningful name and description.
Optionally add subflow inputs for Assignment Group and Assigned To if you want to restrict who can provide the input for the flow data variables. If the flow data record is assigned to a group or user, they’re the only ones that can update the record.
For the outputs, I’m reusing the existing choice list for the academy type again, just like in the decision table. Additionally, I output the Academy Title from the flow data variables.
Create Flow Data
Add a Create Flow Data action to the flow and choose the data definition from Step 1. Drag and drop the subflow inputs to the assigned to and assignment group fields.
Flow variables for flow data variables
In a future update, we’ll add direct access to variable type fields in flows, but until then, we need to use flow variables that we set with inline scripting to access the data. I create a flow variable for each flow data variable.
Set the flow variables by dot-walking to the flow data record variables’ names.
return fd_data._1__create_flow_data.record.vars.u_session_length;
return fd_data._1__create_flow_data.record.vars.u_academy_title;
Repeat the same for the Academy Title variable.
Make a decision
Next, we use the Make a decision flow logic with the decision table we explored earlier. Uncheck the branches checkbox and use the flow variables as decision table inputs.
Assign Subflow Outputs
Last, we assign the Decision output to the Academy Type subflow output, as well as returning the Academy title for further use in our playbook. Activate/Publish the subflow.
When testing the subflow, open the Flow Data record from the execution details to provide inputs and set the state to complete. If the tests were successful, publish the subflow.
Step 3: Create an Activity Definition
Create Activity Definition
Playbook Activity Definitions can be created either from the activity picker when building playbooks, or directly from the list of activity definitions. In the main ServiceNow Tab, I navigate to Process Automation > Process Automation Administration > Activity Definitions.
I click on New to create a new definition with a meaningful name and description. I choose my new subflow as the Automation Plan and set the Activity Experience to Record.
Experience Settings
After saving, I can connect the associated record fields to tie to the flow data record created in the subflow.
Additionally, I can set the title and description of the activity to the instance description and label. This means that whatever I define as label and description on my playbook definition will be the default values to show in the activity component when the playbook executes.
In the form section, I set the Form fields to ‘vars’ to display the flow data variables that I want to collect for the decision. Save the activity definition.
Activity Actions
Lastly, I need to add an action assignment to surface an activity action to save and complete this activity. I can reuse one of the existing actions and connect it to the desired playbook experience configuration.
Step 4: Test the Activity in the Playbook
Create Playbook definition
Now I can move back to Workflow Studio and create a new Playbook or open the Playbook in which I want to use my new activity.
I give it a meaningful name and description, then define the trigger table and conditions.
Add stage and activity
Next, I create a stage and add both the custom activity I created in step 3 and an instruction activity, merely to surface the decision output from the custom activity for this demo use case.
Test playbook
When I test the playbook, I can now see my custom activity with the inputs defined in the flow data definition. After entering values and clicking Mark Complete, we can see the decision output and title on the Instruction activity.
Step 5: Create custom activity UI
Thus far, our activity has been using the default Record activity UI to display on the playbook component. Sometimes you might come across use cases where you want to extend this and create your own activity UI. When doing so, you should create a copy of one of the existing activity UI layouts, whichever comes closes to your target design, in order to inherit as much configuration as possible, reducing the setup time.
Clone record activity UI layout
First, I navigate to Playbook Experience > Activity UI > Layouts, then open the Record entry. I click Clone to create a copy including the Experience Properties, Playbook Overrides, and a clone of the Default Activity UI.
Now I can give this layout a meaningful name and save. Next, I open the Activity UI which I also rename to fit my use case. Submit to return to the Layout form.
Now I can click on Edit Default UI in UI Builder, which will open this activity layout’s UI configuration in UI Builder.
For demo purposes, I’m only adding a Stylized Text component to this form, but you’re free to use any Next Experience component and wire up any available data resource and event that UI Builder offers.
Save your changes.
Set custom activity UI in activity definition
Next up, I will change the UI layout on the custom activity definition I created in Step 3 of this guide to the newly created custom layout. Save the definition.
This will reset the settings we did for the associated record, label, description, form fields, and activity assignment, so I’m returning these to the same values as before.
Test new activity layout in the playbook
To ensure that the new activity configuration is being used, I refresh my playbook, then delete and re-add the custom activity to my playbook, wiring up everything as before.
Now I can run another test and will see that the custom stylized text shows on the playbook activity at runtime.
Conclusion
This article has provided a step-by-step guide on how to create custom activities for playbooks in ServiceNow.
Here are some additional tips to keep in mind:
- Custom activities do not NEED a custom activity layout, if one of the existing layouts serves your use case, you can reuse them for new activity definitions.
- If you leave the layout field empty on an activity, the automation plan will execute, but there will be no UI representation on the running playbook. This is the workaround for instances prior to the Washington, DC release, which introduced Automation Assets.
- Wrap a decision table in a subflow to use the decision outputs in Playbooks created prior to the Washington, DC release. On a Washington, DC instance, you can use the subflow outputs (and therefore decision results) to create conditional branches in the playbook.
In a future update, you will be able to use decision tables directly in the playbook definition to create these branches.
It is recommended to clone an existing activity layout to save time when creating a custom UI layout. - Custom UI layouts can use any component, data resource, and event setup available in UI Builder.
- Use flow data definition variables to collect arbitrary data at runtime.
I hope this article has been helpful! If you have any questions, please feel free to leave a comment below.
Resources
Workflow Automation CoE
Learn how to get started with Workflow Automation in my Center of Excellence on the Now Community.
Workflow Automation CoE
Getting Started with Playbooks
Getting Started with Decision Tables
Getting Started with Flows
Now Learning
To get hands-on training for Flows, Playbooks, and UI Builder, we have courses and paths for each of these topics on Now Learning:
Workflow Studio
Workflow Studio Fundamentals
Flow Designer
Flow Designer Fundamentals
Process Automation Designer and Playbooks
Introduction to Playbooks and Process Automation Designer
Playbooks and Process Automation Designer Fundamentals
UI Builder
UI Builder Fundamentals
Center of Excellence Navigation
@Lisa Holenstein Thank you for putting this together. I ran into issue with Academy Type and Session Duration fields being read only as I followed through the video. I was able to resolve it by changing "Playbook Experience" field to "Global Playbook Experience" when creating "Playbook Experience Action Assignment Map". Any insight into why would be really helpful. I looked up the docs and it was not very helpful.
Thanks for the article.
I am also facing an issue.
I'm working on card dispute playbook(OOB) of Financial services card operation module, Reason for Dispute one of the activity is not populating in dispute case playbook and I need to activate this, can please guide me how can I activate this.
