Workflows

Workflows are often designed to notify, remediate, or otherwise bring assets into compliance. A workflow is a repeatable process that you use to generate automatic responses to specific changes or invoke manually as needed. A workflow can take input from a user or the results of a query:

• User input - For example, a user runs a workflow that creates a ticket for an asset. The workflow prompts the user for a summary and a description.
• Results of a query as input - For example, a query returns an asset that is found out of compliance. The workflow sends the information automatically to an endpoint security system with a request to isolate the asset.

You can run a workflow manually on a single asset from a query result or on an entire query result set. You can also configure a workflow to run automatically by associating it with a saved query and scheduling that query to execute periodically. See Assets for details.

When assigned to a query, the workflow is called an action. You can schedule actions to run automatically. To assign and schedule workflows, see Workspace and Queries.

Create a workflow

Before creating a workflow, you should familiarize yourself with the various components that make up a workflow. The components you use in a workflow depends on the purpose of the workflow.

To create a workflow:

1. Log in to the Command Platform.

2. Navigate to Surface Command > Workflows.

3. Click + Workflow.

4. Provide a name for the workflow.

5. Optionally, provide a description for the workflow.

6. Optionally, select an input type from the drop-down menu. The menu shows all unified asset types and information source system types. Select Any type if you want the workflow to be able to run manually on query results or associated with a saved query to run automatically. A workflow without an input type can only be called from other workflows.

7. Optionally, click Add parameter if you need to include data as input to the workflow.

   1. Provide a name for the parameter.
   2. Select the type of data the parameter can accept.
   3. Select the Required checkbox if the parameter is required for the workflow to run.
   4. Optionally add a description for the parameter.
   5. Repeat these steps for each parameter added as necessary.

8. On the workflow graph, click + to add a step to the workflow.

   Workflow step tips

   Using Conditionals

   Conditionals execute different paths depending on if the conditions are met. Surface Command supports the concept of exclusive gateways meaning that if the conditions of multiple paths evaluate to true, only the first path evaluated as true is executed. If no path conditions evaluate to true, then the path marked as the default path is executed.

   The last branch in the conditional begins as the default branch. However, this can be adjusted by choosing a different branch to become the default branch. Default branches have no conditions, so if you select a branch that did have conditions, those are not applied. If you set another branch as the default, the previous conditions (if any) are preserved. The default branch has a star next to the label in the workflow.

   Using Fan Out

   A Fan Out step iterates over each item in an array. When setting up a Fan Out, you choose the array to iterate across and the variable label (referred to as the Item Reference) for referencing the current item from the array while inside the Fan Out. When specifying the array, you can choose one from the dropdown menu that contains the query results array (query_results.items) passed in at invocation of the workflow. You can also choose other arrays that have been returned by previous functions in the workflow. It is quite common to start out a workflow with a Fan Out to iterate across each item within the query_results.items array.

   Alternatively, you can use the toggle to specify the Fan Out array by entering an expression. When using an expression to specify the Fan Out array, you can do things like defining static arrays (e.g. ["Mary", "John", "James"]), or you can reference a nested array properties of an asset item. For example, you had a workflow that operated on a query results returning Assets and you started your workflow out with a Fan Out specifying query_results.items as the array and items_entry as the Item Reference. For each iteration of that Fan Out, the current Asset would be referred to as items_entry. Then, for each Asset you wanted to iterate through all of the values of its sources array (every Asset has an array called sources containing the list of Connector sources that were correlated together for that Asset). You can accomplish this by adding another Fan Out inside of the first one and specify the array for the secondary Fan Out using the expression items_entity.sources.

9. Click Save. Any invalid steps found in the workflow are indicated by an error icon. You cannot run the workflow until the errors are resolved. You can still save a workflow with errors.

Manage workflows

You can monitor workflows, assign tags and review error messages. Navigate to Workflows from the Surface Command navigation menu to see a list of existing workflows. The table displays the following information for each workflow:

• Active Instances - Number of instances of the workflow that are currently running.
• Types - Type of data the workflow can receive as input.
• Tags - Any assigned tags.

Click a workflow to view its details. The panel contains two tabs. In addition to the active instances and type, the Details tab displays the following information:

• Tags - Displays any tags assigned to the workflow. You can use the + Add tag button to assign tags. You can click the X in any tag to remove it. You can use tags to sort workflows in the Workflows page.
• Installed by Connector - If the workflow was installed by a Connector, the section lists the Connector name. You can click the link to view the Connector details.
• Referenced By The Following Queries - If the workflow was assigned to any queries as an action, the section lists each query name. You can click the link to view the query.

The History tab displays a log of each time the workflow was run and its status. If there was an error, you can open the log entry to see the error message.