Using functions and associated scripts

A function is an object that sends data to a remote function processor through a message destination.

The purpose of a function is to start remote code, which runs a program then returns the results to the function.

You can also use a pre-process script to dynamically set the input values, and a post-process script to run an activity based on the function’s result.

For more information about functions, see Functions and Process Scripts.

Functions and input parameters

Each function can have one or more input parameters.

Depending on the type of parameter, you can enter or select a value. However, any value you select or enter becomes a constant value, which means that this value remains the same every time this function is called by any instance of this workflow. If you wish the values to be dynamic, leave the input fields blank and have the pre-process script provide the values.

If the function has multiple inputs, you can have a mix of constant and dynamic values.

The types of input are described in Configure Functions.

Pre-process script

You can use a pre-process script to dynamically retrieve a value then set a function’s input to that value. A pre-process script can only read incident values. It cannot perform activities such as changing incident values and adding artifacts.

You must use Python 3 to write the script. The scope and restrictions that apply to the SOAR scripting feature, as described in Configure Scripts, applies here too.

To provide a value to the function, use the inputs.<field_name> keyword, where field_name is the function field’s API name. If you do not know the field name, type the inputs. keyword and the type-ahead displays the field names.

The pre-process script ignores any attempt to set the value of anything other than input fields, and it does not issue an error message. It also ignores any attempt to create objects; for example, incident.createTask().

The following simple example of a pre-process script retrieves the ID of the incident and places it into a function field called incidentID.

inputs.incidentID = incident.id

You also use workflow.properties to access a property saved earlier by a post-process script of a different function or a regular script in the same workflow. You need to know the name assigned to the property by the script.

Save function output

You can save the output of a function for use in the pre- or post-process scripts for functions further in the workflow.

You do not need to save the output to use the result in the post-process script in the same function.

The output from a function can only be used in its workflow; it cannot be used in the workflow’s child or parent workflow.

You should not save the output if you do not intend to use it at all, which allows the platform to conserve storage space in the workflow.

Post-process script

The post-process script can change incident values, add artifacts, add data table rows, and perform the activities that a script in the Scripts tab can perform, with the exception of logs.

You must use Python 3 to write the script. The scope and restrictions that apply to the SOAR scripting feature, as described in Configure Scripts, applies here too.

In addition, the post-process script has the following unique keywords that allow you to perform the following:

Obtain the saved output from the script's function.
```
results
```
Add or update workflow properties. This can be any value that you need to reuse within the workflow. Use the following command, where propertyName is any name you choose, but must be unique. The <propertyValue> must be a Python dictionary.
```
workflow.addProperty(<propertyName>, <property Value>)
```
Access data previously entered by workflow.addProperty. Use the following property reference, where propertyName is the name of an existing workflow property.
```
workflow.properties.<propertyName>
```

Note that inputs from the pre-process script are not available to the post-process script.

TIP: If there is an existing script or code that you would like to use in a pre- or post-process script, you can copy and paste from any script editor including the scripts in the Scripts tab.

You could have a unique name for the property workflow.addProperty("resultx", <some_dictionary>) so that it can be used later in the workflow. Once the workflow completes, the workflow.property values are no longer available; however, you could use a script in the workflow to explicitly assign the property to the incident; for example:

if workflow is not None:
  desc = []
  for key in workflow.properties.keys():
    desc.append(str(workflow.properties[key]))
  incident.description = helper.createPlainText(",".join(desc))

NOTE: Make sure to review the list in Considerations for writing scripts, which applies to the post-process script as well as the script feature.

Add a function to the workflow

You can add a function to a workflow by dragging it.

To add a function, complete the following:

Drag the function component to the desired place in your workflow. When you release the mouse, a list of functions appear.
Select the desired function. The Functions screen appears with the Input tab selected.
If you are not using a pre-process script to provide values, select the values for each field in the function.
How you enter the values depends on the type of field. You may have to enter text, date, or number, or select a value from the drop-down.

One type of field allows you to select text by clicking the […] button, where each selection represents a large amount of text, or you can enter your own text. The following is an example of such a field:
If you want to use a pre-process script, click the Pre-Process Script tab and write a script that provides the values for one or more of the input fields. For example:
If you wish to save the output of the function for use by pre- or post-process scripts in functions further in the same workflow, click the Output tab and give the output a name.
Note: You can access the function’s output only in this workflow. You cannot access the output in any child or parent workflow.
If you wish to use a post-process script, click the Post-Process Script tab and write a script that performs an operation based on the results of the function. For example:
Click the x in the right corner when done.
Connect the function to the other workflow components as appropriate.