The UserAction Trigger
  • 20 Oct 2022
  • 4 Minutes to read
  • Dark
    Light

The UserAction Trigger

  • Dark
    Light

Minimum Role: Organization role of Read Only User to view Playbooks with a UserAction Trigger; any other Organization role to use the UserAction Trigger in a Playbook and to execute a Playbook from the Playbook Actions card of an object’s Details screen

Prerequisites: Playbooks enabled by a System Administrator

Overview

A Playbook Trigger is an event that initiates the actions defined within a Playbook to occur. The UserAction Trigger allows ThreatConnect® users to run Playbooks on demand from the Details screen of Indicators, Groups, Tracks, or Victims. This Trigger is contextually aware and user driven, and it allows a customized response (HTML or plain text).

Note
If a Playbook's design includes a UserAction Trigger with a connection from an App or Operator back to the Trigger, the Playbook's priority level will automatically be set to High, regardless of the priority level manually set for the Playbook.

Creating a New UserAction Trigger

  1. On the top navigation bar, click Playbooks to display the Playbooks screen.
  2. Create a new Playbook or open an existing one.
  3. Click Icon  Description automatically generated Triggers on the side navigation bar of the Playbook Designer to view all available Triggers (Figure 1). A picture containing table  Description automatically generated

     

  4. Select UserAction from the External menu to add a UserAction Trigger to the design pane (Figure 2). A picture containing diagram  Description automatically generated

     

    • Hashtag icon: Hover the cursor over this icon at the upper-left corner of the Trigger in the design pane to display a scrollable list of output variables, which are values that the Trigger can send to other Apps and Operators.
    • Information icon: Hover the cursor over this icon at the upper-left corner of the Trigger in the design pane to display the object type(s) configured to run the Trigger, the Trigger’s timeout length, and whether the Run as current user checkbox is selected.
    • Menu Icon  Description automatically generated icon: Click this icon at the upper-right corner of the Trigger box to display a menu with options to edit, disable, clone, or delete the Trigger.
  5. Double-click the Trigger. The Configure section of the Edit Trigger pane will be displayed on the left side of the screen (Figure 3).
    Note
    Click the Display Documentation Icon  Description automatically generated icon at the upper-right corner of the Edit Trigger pane to view information about the Trigger, including a description of the Trigger, its input parameters, and its output variables.
    Graphical user interface, text, application, Teams  Description automatically generated

     

    • User Action Name: Enter a name for the Trigger. This name will be displayed on the Playbook Actions card of the Details screen for the object type(s) selected from the Type dropdown menu.
    • Type: Select the type(s) of Indicators, Groups, Tracks, or Victims to which the Trigger will apply.
    • Timeout: By default, the Trigger’s timeout length (that is, the amount of time the Trigger can run before timing out) is set to 5 minutes. Click in the box to edit this value, if desired.
    • Run as current user: Select this checkbox to execute the Playbook under the name of the user that initiated the execution from the Playbook Actions card on the Details screen of an object rather than the user selected in the Run As dropdown list of the SettingsIcon  Description automatically generatedmenu at the upper-right corner of the Playbook Designer.
      Note
      If you select the Run as current user checkbox, the Run As dropdown list will be disabled under the Settings Icon  Description automatically generated menu at the upper-right corner of the Playbook Designer and replaced with the text “Overridden by UserAction.”
    • Click the NEXT button.
  6. The Response Body section of the Edit Trigger pane will be displayed (Figure 4). The Response Body is the message you will see after the Playbook execution is complete. Graphical user interface, text, application, Teams  Description automatically generated

     

    • Render as Tip: Select this checkbox to display the text entered in the Body section as a pop-up tooltip in the Playbook Actions card on the Details screen after the Playbook execution is complete. If this checkbox is not selected, the text will be displayed in the Status column of the Playbook Actions card.
    • Body: Enter the text (HTML or plain text) that will be the Trigger’s response when it is run.
      Note
      You can use variables in the Response Body parameter.
    • Click the SAVE button.

Now you can continue to build out and then execute the Playbook.

Example Playbook

The Get VirusTotal Results Playbook (Figure 5) uses the UserAction Trigger to display results from VirusTotal™ on the Playbook Actions card of the Details screen for File Indicators. In this example, the Trigger is named “Get VirusTotal Results.”

Diagram  Description automatically generated

 

To view the results of the Playbook, set the status of the Playbook to Active and then navigate to the Details screen for a File Indicator (Figure 6).

Graphical user interface, application, Teams  Description automatically generated

 

The Playbook Actions card is displayed at the top right of the Overview tab of the Details screen. Click Run  to run the Playbook.

Because the Render as Tip checkbox was selected when building the Get VirusTotal Results Playbook, the results are displayed as a tooltip in the Playbook Actions card (Figure 7). If this checkbox was not selected, a status of Completed would be displayed in the Status column for the Playbook. For more information about how statuses are displayed in the Playbook Actions card, see the “Playbooks with a UserAction Trigger” section of Executing a Playbook.

Graphical user interface, application, Teams  Description automatically generated

 

Note
If the Playbook does not fully complete its workflow after the amount of time specified for the UserAction Trigger’s Timeout parameter, the Trigger will time out and display a status of “Error 500”, but the Playbook will continue to run. If the Render as Tip checkbox was selected, the tooltip will return a response after the entire Playbook workflow is complete. Associating a midstream App to the Trigger to generate an earlier response (i.e., before the Playbook workflow is complete) is not a supported workaround.

ThreatConnect® is a registered trademark of ThreatConnect, Inc.
VirusTotal™ is a trademark of Google, Inc.

20055-01 v.06.C


Was this article helpful?