Add functionality to your playbook in using the Utility block

Use the Utility block to expand the functionality of your playbooks in . You can use custom functions and APIs from the Utility block. Custom functions enable you to use your Python skills to expand the kinds of processing performed in a playbook, such as applying string transformations, parsing a raw data input, or calling a third party Python module. Custom functions can also interact with the REST API in a customizable way. You can share custom functions across your team and across multiple playbooks to increase collaboration and efficiency.

Configure a utility block

To configure a Utility block, follow these steps:

1. Drag and drop the half-circle icon attached to any existing block in the editor. Select a Utility block from the menu that appears.
2. Use the tabs to select whether to use a Custom Function or API utility and continue with the appropriate section in this article.
• Expand playbook functionality with a custom function
• Set parameters with the API utility
3. Complete the configuration by following the instructions in Finish editing the playbook at the end of this article.

Expand playbook functionality with a custom function

Prerequisite: You must define custom functions - or locate existing custom functions in a local or community repository - before you can call them from a Utility block. See Add custom code to your playbook with a custom function for details.

To call a custom function from within the Utility block, complete the following steps:

1. In the Utility block configuration, select the Custom Functions tab.
2. Locate and select the desired custom function in the displayed list. Optionally use the search bar, repository chooser, and sorting feature to help you locate the desired custom function.
   Hover over the name of a custom function to see its description, inputs, outputs, and other playbooks where it is used.
3. Configure the values of the input parameters.
4. (Optional) To repeat this custom function within the utility block, select the Loop tab to specify looping. For details on looping, see Repeat playbook blocks with looping. Looping is not available for APIs within utility blocks.
5. Finish working on your playbook by continuing with Finish editing the playbook at the end of this article.

Set parameters with the API utility

Use the Utility block API to set parameters of the container it's running in. For example, you can use a utility call from the Utility block to set the severity of a container.

To call a an API from within the Utility block, complete the following steps:

1. In the Utility block configuration, select the APIs tab.
2. Select the utility property you want to set. The table at the end of this section summarizes the properties that you can set.
3. Specify the required configuration for the API. For example, the set sensitivity API requires that you select a sensitivity level from the provided list.
4. Finish working on your playbook by continuing with the next section of this article, Finish editing the playbook.

Property	Description
add comment	Add a comment to the container. You can either supply a variable or a static string in the input.
add note	Add a note to the container.
add tag	Add a tag to the container.
add to list	One of two API calls that doesn't operate directly on the container itself. The add list property takes two parameters: the list that you want to add to, and the data you are adding. If the list doesn't exist, it is created by . You can point the data field to a variable by selecting from the drop-down menu or you can type in a fixed string.
pin	Pin data to the summary tab in the container with a HUD (head up display) card. Data pins are displayed in a table. This property takes the following parameters: Message Data Pin Type Pin Color Name
promote to case	Promote the container to a case. Verify the location of the container or workbook. If the Utility block cannot find that container or workbook, it will not be promoted and you will not see an error message.
remove list	One of two API calls that doesn't operate directly on the container. The remove list property takes a list name as the single parameter, and deletes that list when it has run.
remove tag	Remove a tag from the container.
set label	Set the label of the container. The drop-down lists all of the labels available on your instance.
set owner	Set the owner of the container.
set sensitivity	Set the sensitivity of the container.
set severity	Set the severity of the container.
set status	Set the status of the container, such as closed.

Finish editing the playbook

When you have finished editing your playbook, do the following:

1. Click Save to enter your desired settings and playbook name.
2. After you have selected a utility, configure the datapaths and, optionally, create a custom datapath. For details on creating datapaths, see Specify data in your playbook.
3. Click Done.

You can configure multiple utility calls in any utility block. For example, you can set the label, severity, and status of a container using one utility block.