- 14 Oct 2022
- 15 Minutes to read
Building and Activating a Workflow
- Updated on 14 Oct 2022
- 15 Minutes to read
Building a Workflow
To create a new Workflow, click the New… button at the upper-right corner of the Workflows screen and select New Workflow. The New Workflow screen will be displayed (Figure 1).
- Name: Enter a name for the Workflow. The name should be brief, yet descriptive.
- Default Assignee: Select the name of the user or user group to whom a Case using this Workflow will be assigned by default, or select No Default Assignee if there is to be no default assignee.
- Active slider: After the Workflow has been fully configured, toggle the Active slider on to set the Workflow as active.
- Description: Enter a description for the Workflow. This text will be displayed at the bottom of the Workflow card.
Adding an Attribute
Adding Attributes to a Workflow ensures that Cases created using the Workflow are preloaded with those Attributes. To add an Attribute in the Workflow, click the No attributes in this template. Click to add an attribute. text in the Attributes section, or click the New… button at the upper-right corner of the Workflow and select Add Attribute. The Add Attribute drawer will be displayed on the left side of the screen (Figure 2).
- Type: Select the type of System-level or Organization-level Attribute that will be added to the Attributes card of a Case that is created using the Workflow. By default, there are no pre-configured Attribute Types for Cases. This means that this dropdown menu will be empty unless Attribute Types for Cases are created in the System or Organization in which a Case will reside.
- Create a new attribute type: Click this link to create a new Organization-level Attribute Type for Cases. The Org Config screen for the Organization in which the Workflow is being created will open in a new browser tab. See Creating Custom Attribute Typesfor more information about creating custom Attribute Types at the Organization level.NoteOnly users with a System role of Administrator can create Attribute Types at the System level. Similarly, only users with a System role of Administrator or Operations Administrator, or an Organization role of Organization Administrator, can create Attribute Types at the Organization level.NoteIf you use the Create a new attribute type link to create a custom Attribute Type, you must refresh the Workflows screen in order for it to be displayed in the Type dropdown menu.ImportantIf you try to add an Attribute to a Workflow when the Attribute Type’s Max Allowed limit has been reached, an error message will be displayed stating that the maximum allowed for the Attribute Type has been exceeded on the current Workflow, and you will be directed to select an alternative Attribute Type or remove an existing Attribute of the maxed-out Attribute Type from the Workflow. See the “Attribute Administration” section for instructions on removing an existing Attribute from a Workflow.
- Description: After an Attribute Type is selected from the Type dropdown menu, the description that was entered when the Attribute Type was created will be automatically displayed.
- Click the SAVE button.
The selected Attribute will be displayed in the Attributes section of the New Workflow screen (Figure 3).
To add another Attribute to the Workflow, click the Click to add an attribute. text displayed below the newly added Attribute, or click the New… button at the upper-right corner of the Workflow and select Add Attribute, and follow the steps in this section.
The Attributes section of the New Workflow screen (Figure 3) provides the following information about each Attribute in a Workflow:
- Attribute: The name of the Attribute added to the Workflow.
- Description: A description of the Attribute that was added to the Workflow.
- Actions: Click the vertical ellipsis to display a menu with the following administrative options for each Attribute:
- Edit: Selecting this option will display the Edit Attribute drawer, which is similar to the Create Attribute drawer (Figure 2). Select a different Attribute Type from the Type dropdown menu, and then click the SAVE button.
- Remove: Selecting this option will display the Confirm Remove Attribute window. Click the CONFIRM button to remove the Attribute.
- =: Click on the = icon and drag the Attribute up or down to adjust its position in the display order, which will be reflected in the Attributes card of a Case that is created using the Workflow.
Adding a New Task
To add a Task in the Workflow, click the No tasks in this phase. Click to add tasks to create this phase. text in the Phase 1 row at the bottom of the Workflow, or click the New… button at the upper-right corner of the Workflow and select Add Task. The Create Task drawer will be displayed (Figure 4).
- Name: Enter a name for the Task. The name should describe the goal of the Task (e.g., “Identify Target CVE,” “Prioritize the Incident,” “Review Analytic Standards,”).
- Task Completion Required: Select this checkbox to make completion of this Task a requirement for completion of the Case.
- Description: Provide a detailed description of the Task in the text box, which supports Markdown.
- Phase: Phases are logical groupings of Tasks. Select a Phase for this Task. Because the Task in this example is the first Task in the Workflow, Phase 1 is the only available choice, but as you build out the Workflow, subsequent Tasks may be placed into other Phases.
- Default Assignee: Select a default assignee for this Task. The assignee for a Task is the user responsible for carrying out and completing the Task within a Case. When configuring the Case itself, an assignee other than the default one may be selected. If there is to be no default assignee for the Task, select No assignee.
- Dependency: Select a Task within the Workflow upon which this Task’s completion depends. If the Task has no dependencies, select No Dependency. This dropdown menu will not be displayed if the Task is the first Task being created in the Workflow.NoteFor a Case using a Workflow, all Tasks are available for completion at any time unless they have an unfulfilled dependency.
- Due In: Select the unit of time (Days, Hours, or Minutes) and enter the amount of time until the Task is due. For example, if you enter 5 for the amount of time and select Days as the unit of time, the Task will be due 5 days after the Case using the Workflow is created or, for Tasks with a dependency, the Task on which it depends is completed.
- Automated Task: To make this Task an automated Task (i.e., a Task that is accomplished by a Workflow Playbook), toggle this slider on. Otherwise, the Task will be performed manually by a user. This example demonstrates the creation of a manual Task. See the “Adding an Automated Task” section for more information.
Adding an Artifact Field
Artifact Fields define the Artifacts (i.e., the pieces of data) to be collected during the execution of the Task. To add and configure an Artifact Field in a Task, click the plus icon in the Artifact Fields section of the Create Task drawer (Figure 4). The drawer will display options for configuring an Artifact Field (Figure 5).
- Variable: Enter a name to identify the Artifact Field (e.g., emailSubject). This name must be unique within a Task (i.e., no two Artifact Fields within the same Task may have the same Variable).
- Label: Enter a brief description of the Artifact Field (e.g., Subject Line of the Email).
- Required: Toggle the slider on to require the collection of the Artifact during the execution of the Task. Toggle the slider off to make the collection of the Artifact optional.
- Allow Multiple Values: Toggle the slider on to allow multiple values to be collected for this Artifact during the execution of the Task. Toggle the slider off to ensure that only one value is collected for this Artifact during the execution of the Task.
- Artifact Type: Select the data type for the Artifact. The potential Artifact types include all Indicator types, as well as a large variety of other data types, which are determined by ThreatConnect and your System Administrator.
- UI Element: This field is automatically populated with the user interface (UI) element—that is, the way in which the user executing the Task is prompted to enter information—that corresponds to the selected Artifact Type. For example, for an Artifact Type of “Address,” the UI Element will be “String,” and for an Artifact Type of “Timestamp,” the UI Element will be “DateTimePicker.”
- Data Type: This field is automatically populated with the data type that corresponds to the selected Artifact Type. For example, for an Artifact Type of “Address,” the Data Type will be “String,” and for an Artifact Type of “Timestamp,” the Data Type will be “TimeStamp.”NoteIf the Allow Multiple Values slider is toggled on, then the Data Type will be an Array. For example, for an Artifact Type of “Address,” the Data Type will be “StringArray,” and for an Artifact Type of “TimeStamp,” the Data Type will be “TimeStampArray.”
- Related Intel Type: If the selected Artifact Type maps to a ThreatConnect Indicator type, this field will be populated automatically with that ThreatConnect Indicator type. For example, for an Artifact Type of “File” or “File Hash,” the Related Intel Type is “indicator-File.”ImportantThis mapping works only for single-value Indicator types. For example, the Registry Key Indicator type contains more than one value (key name, value name, and value type), so there will be no Related Intel Type provided when “Registry Key” is selected as the Artifact Type.
- Click the SAVE button to save the Artifact Field.
The Artifact Field will now be displayed in the Artifact Fields section of the Create Task drawer (Figure 4).
Editing or Deleting an Artifact Field
To edit or delete an Artifact Field, click the vertical ellipsis to the right of the Required column. A menu with Edit and Remove options will be displayed (Figure 6).
Selecting Edit will display the Create Task drawer with the Artifact Field’s configured options (Figure 5). Make any desired changes to the Artifact Field’s options, and click the SAVE button.
Selecting Remove will display the Confirm Remove Field window. If any automated Tasks in the Workflow use the Artifact Field as a variable, then deleting the Artifact Field will invalidate those references. Click the CONFIRM button to delete the Artifact Field.
Changing Artifact Field Order
After more than one Artifact Field has been entered into the Task, you can change the order in which the Artifact Fields are displayed by clicking on the = icon to the left of a field (Figure 6) and dragging it to its new location.
Saving a Task
Once the Artifact Fields and all other information for a Task have been entered, click the SAVE button at the lower-right corner of the Create Task drawer to save the Task. The Task will now be displayed in the selected Phase in the Workflow. If the Task was the first Task created in its Phase, a new Phase will be added to the Workflow (Figure 7).
Saving a Workflow
It is recommended to save the Workflow after each Task has been created or modified. To save the Workflow, click the SAVE button at the lower-right corner of the New Workflow screen. Once the Workflow is saved, the Workflows screen will be displayed, showing all of the available Workflows in your Organization, including the newly saved Workflow. Select that Workflow to continue working on it.
Once a Workflow has been saved for the first time, it is assigned a unique identification number, as shown above the name of the Workflow at the top left of the screen–e.g., Workflow Template #7 in Figure 8.
Adding an Automated Task
An automated Task is executed by a Workflow Playbook. To create and configure an automated Task, click the No tasks in this phase. Click to add tasks to create this phase. text in an empty Phase, or click the New… button at the upper-right corner of the Workflow and select Add Task. The Create Task window will be displayed (Figure 4).
See the “Adding a New Task” section for instructions on filling out the fields above the Automated Task slider. To add an automated Task, toggle the Automated Task slider on. The Create Task drawer will display all Workflow Playbooks in your Organization (Figure 9).
- Use the search bar displayed above the table to filter Playbooks by name, if desired.
- To create a new Workflow Playbook that will run the automated task, click CREATE NEW PLAYBOOK. The Create Playbook window will be displayed. Enter the name and, if desired, description of the new Workflow Playbook, and click the SAVE button. The Playbook Designer will open in a new browser tab and display the newly created Playbook with a Workflow Trigger added to it. After configuring and activating the Playbook, return to the browser tab with the Create Task drawer open and click REFRESH to refresh the list of Playbooks and display a status of Active for the newly created Playbook.
Select the Workflow Playbook that is to run the automated Task. The Playbook will be displayed at the bottom of the Create Task drawer (Figure 10).
- CHANGE: To select a different Workflow Playbook, click the CHANGE text under the name of the Playbook, and the drawer will display all active Workflow Playbooks again (Figure 9).
- Run automatically after dependent task completion or Run automatically at case creation checkbox: If the automated Task has a dependency, such as in the example in Figure 10, the Run automatically after dependent task completion checkbox will be displayed. Select this checkbox to configure the automated Task to run immediately after the Task on which it is dependent is completed. If the automated Task does not have a dependency, the Run automatically at case creation checkbox will be displayed instead. Select this checkbox to configure the automated Task to run automatically once a Case using this Workflow is opened.NoteSelecting either of these checkboxes will remove the Default Assignee, because the Task will run automatically and thus does not require a user to ensure its execution.NoteIf you select the Run automatically after dependent task completion checkbox, you must configure all required inputs for the Workflow Playbook before you can save the Task.
Click INPUTS > at the lower-right corner to display the inputs required by the Workflow Playbook (Figure 11).
- Required input fields: The bottom left of the drawer will display all required inputs for the Workflow Playbook. To ensure that the same inputs are provided to the Workflow Playbook for all Cases run using this Workflow, fill out values for these fields now. If the value for a field can differ from Case to Case, leave the fields blank so that the user will be prompted for their values when the automated Task is run within a Case.
- artifact(s): The table at the bottom right of the drawer will be empty, as you cannot create Artifacts in a Workflow. However, users completing the automated Task in a Case created using the Workflow will be able to populate the inputs with the Case’s Artifacts, variables in their Organization, or, if applicable, output variables from the Task on which it is dependent (i.e., Workflow variables) when they run the automated Task within the Case.
Click OUTPUTS > at the lower-right corner of the Create Task drawer to view the outputs that the Workflow Playbook is configured to produce (Figure 12).
To save the Workflow Playbook’s outputs as Artifacts in Cases created using the Workflow, toggle the Save to Artifact slider on. Fields for configuring the Artifact will be displayed (Figure 13).
- Artifact Name: Enter a name for the Artifact.
- Artifact Type: Select the type of Artifact being saved. Only Artifact Types that map to the Data Type of the output will be provided in the dropdown menu. For example, if the Data Type is String, then the Artifact Type menu will display only types that are Strings.
- Configure Artifact: Select the failure option(s) for the Playbook. Note that no selection is required for this field, and more than one option may be selected. Available options include the following:
- Output is required: Select this option to make the Playbook fail if it does not produce any output.
- Fail playbook if artifact validation fails: Select this option to make the Playbook fail if it produces output that fails Artifact validation.
- Click the SAVE button to save the Task. It will be displayed in the Workflow (Figure 14).
The Tasks section of a Workflow (Figure 7) provides the following information about each Task in the Workflow:
- Type: This column designates whether the Task is manual () or automated ().
- Name: This column provides the name of the Task.
- Assignee: This column provides the name of the default assignee of the Task. The default assignee can be a user or a user group.
- Artifacts: This column provides the number of Artifact Fields or Artifacts produced by the Task. Manual Tasks produce Artifact Fields, and automated Tasks produce Artifacts in the form of outputs of the Workflow Playbook.
- Required: This column displays whether completion of the Task is required.
- Dependency: This column displays the name of the Task on which the Task is dependent, if any.
- Actions: Use the vertical ellipsis menu to display a menu with the following administrative options for each Task:
- Edit: Selecting this option will display the Edit Task drawer, which is similar to the Create Task drawer. Make any desired changes to the Task, and click the SAVE button.
- Copy: Selecting this option will immediately place a copy of the Task at the bottom of the Phase. The name of the copy will be the name of the original Task followed by the word “Copy.”
- Remove: Selecting this option will display the Confirm Remove Task window. Click the CONFIRM button to remove the Task.ImportantRemoving a Task will invalidate any references to the Task’s fields that may have been used in automated Tasks dependent on the removed Task. Similarly, renaming a Task will invalidate any references to the Task’s fields that may have been used in automated Tasks dependent on the renamed Task.
- =: Click on the = icon to drag a Task up or down to a new location within the Phase or in a different Phase.
Activating a Workflow
To activate a Workflow, toggle the Active slider at the upper-right corner of the Workflow on, as in Figure 15.
After toggling the Active slider on, click the SAVE button at the bottom right. If the SAVE button is not clicked, the Workflow will not be activated.
ThreatConnect® is a registered trademark of ThreatConnect, Inc.