Playbook Components

Last Updated: Oct 25, 2018 11:00PM EDT
User (for creating and editing); Organization Administrator (for activating and de-activating)
None for creating a Component, but if a Component is to be used, a Playbook must call it


Playbook Components are Apps that consist of modules of Playbook elements (Apps and Operators, with a single initial Trigger) that can be called from a Playbook in ThreatConnect®. They make Playbook design more convenient when a group of elements is used repeatedly by allowing the elements to be packaged together and called as a single element. See Playbooks for more details on Playbooks in general.

Creating a Component

  1. On the top navigation bar (Figure 1), click PLAYBOOKS to display the Playbooks screen (Figure 2). The leftmost column displays icons illustrating the Type of item in each row of the table. Components are indicated by the icon. See “The Playbooks Screen” section of Playbooks for more details about this screen.
  2. Click the + NEW button at the top left and select New from the dropdown menu that appears. The Create Playbook window will appear (Figure 3).
  3. Select the Component radio button.
  4. Enter the Name of the Component and an optional Description of the Component, and then click the SAVE button. The Component Designer will open (Figure 4). By default, a Component Trigger is created when a Component is created, because that is the element that causes the Component to execute. It defines the behavior of the Component (i.e., the inputs and outputs) when it is used in a Playbook. No other Triggers may be added to a Component.
    NOTE: It is recommended that a Description be entered, as the Description defines what the Component does and will be in the Display Notes for the Component when adding it to a Playbook and editing its parameters. (See Figure 15.)
    NOTE: The Description supports Markdown.
  5. The Description may be edited in the Playbook Metadata card at the top. Labels, which are keywords that are used to classify Playbooks and Components, may be added and edited in the Playbook Metadata card as well. For example, labels such as “In Design” and “QA” can be used to track the development or status of Playbooks and Components, and labels such as “Enrichment” and “Reporting” can be used to make filtering by Playbook and Component type more manageable. If desired, click the gray Playbook Metadata box at the top right to collapse the Playbook Metadata card, or toggle the Auto display Metadata slider to gray to collapse the Playbook Metadata card by default.
  6. Double click on the Component Trigger. The Edit Trigger: Component pane will appear on the left with the Inputs section displayed (Figure 5). This section is where specifications for the variable(s) that pass information from a Playbook into the Component are entered.
    • Name: Enter a name for the Component Trigger.
    • Variable: Enter the name of a variable that will pass information into the Component.
    • Label: Enter a brief, descriptive label for the variable. The label is what will appear above the field where the user will provide information for the variable, in a similar place as “Name*,” “Variable*,” “Label,” “UI Element, “Data Type,” and “Advanced Options” in Figure 5.
    • UI Element: Use the dropdown list to choose the type of element (TextField, Dropdown, Checkbox, Multiselect Dropdown, or Key/Value List) that will render for this variable in the configuration pane of the Component when designing the Playbook that calls it.
    • Data Type: Use the dropdown list to select the type(s) of data that will be required by the UI Element. This box will be grayed out if the data type is not relevant to the selected UI Element (e.g., Checkbox).
    • Advanced Options or Dropdown Options: If the UI Element is a TextField or Key/Value List, a dropdown list for Advanced Options will be displayed with options for requiring or encrypting the element and for allowing Text $Variables and Keychain $Variables. If the UI Element is a Dropdown or Multiselect Dropdown, a box for entering pipe-delimited dropdown options will be displayed, along with a checkbox for specifying whether selection is required. If the UI Element is a Checkbox, no further options are available.
      NOTE: Internal variables such as ${OWNERS} (i.e., the list of all available owners in the user's Organization) may be entered as a dropdown option so that the user does not have to enter every element contained within the variable manually.
      NOTE: The Display Notes slider at the top right of the Edit Trigger: Component pane displays a blank card when toggled, as users provide the parameter information for Components, so there are no pre-generated parameter notes to display.

  7. Once all the data for a variable have been entered, click the Add  button. The new input variable will appear in a table at the bottom of the Inputs section (Figure 6).
  8. Hovering over the vertical ellipsis to the right of the Data Type cell for a variable will cause a summary of the information entered for the variable to appear in a pop-up box (Figure 7).
  9. Input variables may be deleted by clicking the trash icon on the right side of the table row for the variable. Note that clicking the trash icon immediately deletes the variable. No window or message will appear to ask for confirmation first.
  10. Repeat Steps 6 and 7 to add information for all of the input variables. Once all input variables have been entered, click the NEXT button. The Outputs section will be displayed (Figure 8).
  11. Click the SAVE button without adding output variables. Output variables are used to pass information back to the Playbook that called the Component, but the list of potential values will first need to be populated by the Apps that connect to the Component Trigger. As such, the output variables must be added after all Apps are added to the Component.
  12. Add Apps and Operators to the Component in the same way that they would be added to a Playbook. It is good practice to connect the end of all possible pathways back to the Component Trigger so that it receives the final output from the pathway(s) the Component takes and can pass that information back to the calling Playbook.
  13. Double click on the Component Trigger to edit it again. Click the NEXT button (Figure 6) to navigate to the Outputs section (Figure 8). For each output variable, enter a name in the Name field, and then type a hashtag (#) in the Value field to bring up a dropdown list of possible values (Figure 9). The actual values provided will depend on the Apps in the Component. Choose a value from the list. Click the Plus  button to confirm that all information for the variable has been added. Enter more variables as necessary. When all variables have been entered, click the SAVE button.

    NOTE: Components may also be built by adding Apps before configuring any part of the Component Trigger (i.e., before adding input variables). Once the Apps are all configured and the pathways are built, the Component Trigger may be configured in full (i.e., input variables and then output variables).

  14. Once the Component is fully configured, click the Active slider in the top right-hand corner so that it turns orange, indicating that the Component is active (Figure 10). A Component must be active in order to be called by a Playbook.

NOTE: Apps and Operators within Components do not have an individual log level, and as such, there is no Log option in their menus. The log level for the Component as a whole can be set within the calling Playbook. In addition, the logging information for the Component is available within the execution and logging information for the calling Playbook.

Editing, Exporting, Cloning, Deleting, and Exporting a Component

  1. To edit a Component, click on its name (in blue text) on the Playbooks screen (Figure 2). The Component will open in the Component Designer. Make sure to toggle the Active slider at the top right of the screen to gray (inactive), as only inactive Components can be edited.
    NOTE: Active Components are indicated by green checkmarks above the Component icon in the Type column on the Playbooks screen.
  2. Hover the cursor over the vertical ellipsis icon in the upper right-hand corner of the Component Designer to clone (copy) the Component, delete the Component, or export the Component (Figure 11). The same menu may be accessed at the far right of the row for the Component on the Playbooks screen (Figure 2).

NOTE: A Component that is being used in a Playbook cannot be deleted. Attempting to do so will result in an error message listing all Playbooks, active and inactive, that use the Component. The Component must be deleted from all of the Playbooks that use it before it can be successfully deleted from the user's ThreatConnect instance.

Using a Component in a Playbook

  1. Follow the steps in the "Creating a Component" section to create and activate a Component. Inactive Components cannot be added to Playbooks.
  2. Create a new Playbook or open an existing Playbook. Click on the + APP button at the top left of the Playbook Designer. All active Components will be listed in the Components section (Figure 12).
  3. Click on a Component, and a Component App will appear in the Playbook Designer (Figure 13).
  4. Click on the App. The Edit App pane will open on the left. The example in Figure 14 demonstrates all of the UI Elements that may be chosen when configuring the Component.
  5. Toggle the Display Notes slider to view a description of the Component and information about variables (Figure 15).
  6. Enter values for all of the variables, and then click the SAVE button. Make sure to connect the Component App to one of the other elements in the Playbook.
  7. The Menu button on the Component has options similar to those for Playbook Apps, with the addition of View (Figure 16), which opens a new tab with the Component in the Component Designer.

Cloning a Playbook as a Component

  1. To clone a Playbook as a Component (i.e., convert an existing Playbook into a Component), select the Clone as Component option from the vertical ellipsis menu at the top right of the Playbook Designer screen for the Playbook to be cloned. The Clone Playbook window will appear (Figure 17).
  2. If there is no Trigger in the Playbook being cloned, then a Component Trigger will be added to it (Figure 18). If there is a Trigger in the Playbook being cloned, then that Trigger will be turned into a Component Trigger (Figure 19).

NOTE: Variables in Triggers that have been converted to Component Triggers will be invalidated. They will need to be changed manually within the Apps that reference those variables in the new Component.

20069-02 EN Rev. A

Contact Us

  • ThreatConnect, Inc.
    3865 Wilson Blvd.
    Suite 550
    Arlington, VA 22203

    Toll Free:   1.800.965.2708
    Local: +1.703.229.4240
    Fax +1.703.229.4489

    Email Us
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found