Use functions to communicate with external systems

Create and maintain functions to communicate with external systems or programs.

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.

The Functions tab lists the functions available for use with workflows. Use this tab to create, edit, and delete functions as necessary. To add a function, click New Function. To view or edit a function, click the function name. To delete a function, click the delete icon in the same row as the function name.

App developers use functions to integrate the SOAR Platform with other security programs. When an app developer creates a function for the first time, it needs to be created in the Functions tab. When you create a function, an app developer can deploy functions to another SOAR Platform, which makes them available in this tab.

Each function has the following properties.
  • Name. Name of the function. When you add or edit, use a unique name that describes the purpose of the function.
  • API Name. Generated by the system and based on the Name field. App developers use this name when they create external scripts that call this function. As the function is implemented by external scripts, make the API name unique.
  • Message destination. Used to transport the function call. The message destination is mandatory and must be configured to be type queue and expect an acknowledgment. If a function does not receive an acknowledgment, it continues to wait and can prevent the workflow from completing.
  • Description. Text that describes the function.
  • Inputs. One or more fields whose values are inputs for the function. The values can be statically given by the workflow designer or dynamically specified in a pre-process script.

Choosing inputs for functions

The Input Fields section lists all the fields available for the function.

Similar to the incident layouts, you can create extra fields, and edit or delete existing fields. These fields are available to other functions. These fields are not the same as the fields in the incident layouts.

When you create a function, you decide what types of input are needed for the workflow by dragging a field from Input Fields to the Inputs section. You can also select the order of the fields by dragging the fields. The order, from beginning to end, is how workflow designers see the fields when they add the function to a workflow.

To view or change the contents of a field, click its edit icon in the Input Fields section. When you change to a field, it updates all occurrences of the field in other functions.

The following screen capture shows that the bigfix_artifact_id field was dragged from Input Fields to Inputs.

Creating input fields

If none of the existing fields meets your requirements, click Add Field to create a new field.

Enter the parameters as follows.
  • Type of field. Determines what type of values a workflow designer or pre-process script can provide to this field.
    • Date Picker. Value must be a date.
    • Date Time Picker. Value must be date and time.
    • Text. Value must be text.
    • Number. Value must be a number.
    • Text with value string. Value must be text that a workflow designer or pre-process script can enter or select.

      In the Templates section of the Create Input Field dialog box, you can predefine lengthy text and provide a label for it for ease of use. For example, you can enter Policy 1 in the Display Value column to represent a lengthy paragraph that describes the policy that you enter in the Data Value column. When a workflow designer or pre-process script selects this field and chooses Policy 1, the policy text populates the input field.

      To enter a text value with string, click Add Row, enter a label in the Display Value column then enter the full text in the Data Value column. You can add rows for more text options. Click the green checkmark when done.

      You can also use this field to have a text string represent commonly used settings, such as an LDAP account settings or an SQL query.

    • Select. You provide a list of values, where the workflow designer or pre-process script selects one value. Click Add/Edit Values to enter the values then click the green checkmark when done. In Blank Option, determine whether users can choose to not have a value (leave it blank).
    • Boolean. Values can be Yes, No, or Unknown, which the workflow designer or pre-process script selects.
    • Multiselect. You provide a list of values, where the workflow designer or pre-process script selects one or more values. Click Add/Edit Values to enter the values then click the green checkmark when done.
  • API Access Name. Enter a name for the field so that app developers can access this field from the API. Use underscores instead of spaces.
  • Tooltip. You can also enter descriptive text or a helpful hint. When present, an information icon appears next to the field. Your text displays when a user hovers over the icon.
  • Requirement. Enter Always to make it a required field, where the workflow designer cannot run the function without specifying a value for the field or having the pre-process script provide the value. Select Optional if the workflow designer is not required to enter or select a value.
  • Placeholder. If you enter a placeholder, this value is automatically displayed in the field to provide a hint to the workflow designer.

New in 50.0 Function outputs in playbooks

To assist other playbook designers when they use a function, when you create the function, you can provide information and examples about the output.

When a designer clicks the function, the information about the output appears in the Details window.

If your function produces output, add information to the following output fields. If no output is produced, leave the fields empty.
Output description
Type a description of the function output.
JSON example
If the function returns JSON data, add an example of the expected JSON data. 
{"sev-name" : "High", "sev-value" : 4 }
JSON schema
Provide an example schema for the JSON data. The schema defines the structure of the JSON data. External references are not allowed in the schema, it must be fully defined.
{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
  "sev-name": {
   "type": "string"
  },
  "sev-value": {
   "type": "integer"
  }
 },
 "required": [
  "sev-name",
  "sev-value"
 ]
}

Testing a function

The section provides an example of how to test a function.

If you use playbooks, create a simple playbook to test the function.

If you use rules and workflows, create a rule to trigger the workflow that contains the function. The rule can be a menu-item rule or an automatic rule.

The example uses a menu item rule, which is called Lookup Model with the Type of Artifact, which calls a workflow, which is also called Lookup Model.

The workflow runs on an artifact, so the rule is a menu-item rule that appears as an action in each incident’s artifact action menu, accessible from the […] icon.

Select your action to start the workflow and call your function.

The incident’s Action Status menu shows the status of each rule, which can be pending (queued for delivery to the function processor), processed successfully, or with an error. In the following example, the action is pending. The workflow name is Example: Call REST API and the Function is Utilities: Call REST API.