Use a ChatOps Step
After adding workspaces to InsightConnect, you can configure the ChatOps action to include in your workflow.
To add a ChatOps step to a workflow:
- When choosing step type for a new step in the workflow builder, click the ChatOps button, then click the Continue button.
- Choose the workspace you want to post messages in and click Continue. If you have no workspaces set up or would like to add a new workspace, follow these instructions.
- Select the action you want to use. Learn more about ChatOps actions in the following sections. InsightConnect currently supports:
- Name the ChatOps action something descriptive, so you can easily refer to it later.
- Check the Continue workflow on step failure box if you want your workflow to continue to run even if the ChatOps step fails.
- Use the instructions in the following sections to configure the ChatOps action you chose.
Format ChatOps Step Input
When configuring a ChatOps step, make sure to follow these conventions for Slack content in InsightConnect input fields:
- Channels must be prepended with
#
, like#channel
- User mentions must be formatted with Slack's new
<userID>
syntax. Learn more about this change at Slack's API documentation: https://api.slack.com/changelog/2017-09-the-one-about-usernames - If using string variables from previous steps as ChatOps input, the variable must be first modified through an Artifact Step in order to prepend the
#
or@
symbols in front of each string of the variable
Private Channels in Step Input
If you'd like to conduct ChatOps actions in a private Slack Channel, you will need to first add the ChatOps slack bot to the private channel.
In the private channel:
- Type '@' to open a list of available users and bots to add to the channel.
- Start typing "InsightConnect" to filter the search.
- Select @Rapid7 InsightConnect.
- When prompted, click the Invite Them button.
If the slack bot is added successfully, you should see that the Rapid7 InsightConnect Slack app joined your private channel by invitation from your username.
Use the Post Message Action
Post messages directly into your Slack workspace in your preferred channels, private groups, or IM channels. You can include data from previous steps in your workflow, as well as Slack message attachments, URLs, and more.
To configure a Post Message ChatOps action:
- Provide the name of the message recipient, such as a channel or username. You can also ingest channel names as input variables from previous Slack steps in your workflow.
- Provide the message you would like to post into the Slack channel.
- You can include variables from previous workflow step. Reference them with the
{{[StepName].[VariableName]}}
syntax. - You can also add URLs and tag people just as you would in Slack. Use the
@
symbol to tag team members by username directly in the message.
- If you would like to include message attachments, format the attachment as a JSON array and paste into the attachment field. Visit Slack’s API documentation to learn more about JSON structure: https://api.slack.com/docs/message-attachments#attachment_structure.
- Click Save Step to add more steps to your workflow as needed.
Use the Post Interactive Message Action
Interactive messages allow your team to respond directly to prompts from the Rapid7 InsightConnect Slackbot in Slack. Use the Post Interactive Message action to seamlessly incorporate your team’s expertise into your workflows, all from your preferred Slack channel or group.
To configure a Post Interactive Message ChatOps action:
- First configure the Interactive Message section. This will display the first part of the Slack message. We recommend using this section to provide as much information as possible for your team to make decisions.
- Enter the name of the message recipient, such as a channel or username. You can also ingest channel names as input variables from previous Slack steps in your workflow.
- In the “Message” field, provide the message you would like to post into the Slack channel before the prompt or question. You can include variables from previous steps as well as
@
user or#
channel mentions in your message. - Enter the question or prompt you want the recipient to answer in the Response Question field.
- If you would like to include message attachments, format the attachment as a JSON array and paste it into the attachment field. Visit Slack’s API documentation to learn more about the JSON structure: https://api.slack.com/docs/message-attachments#attachment_structure.
- Format each response option you want to provide to your team. You should have two options at minimum, and you can add more as needed by clicking on the +Add Response Option button at the bottom of the configuration panel. To configure a response option:
- In the “Button Text” field, type the text you want the button in Slack to display.
- Choose a “Button Style” from Primary, ** Default**, or Danger. Primary buttons display in a green font and border, default buttons display in black, and danger buttons display in red. We recommend using primary buttons for preferred responses. Use danger buttons for responses that require your team to take caution, like in cases of permanent deletion or modification.
- Provide a confirmation message for the Slack bot to display when a user selects a response. You can include variables or Slack channels and usernames in these messages.
- Repeat the previous three steps for every response option you need.
- Click Continue to see a preview of the Slack message and buttons. Use the Previous button to return to the configuration panel and make more edits. Otherwise, click the Continue button .
- Configure the message’s timeout settings. Timeouts occur if none of your team members respond to the Slack message within a pre-configured length of time. Type in your desired number of minutes or seconds and set the unit of time in the “Time out after…” dropdown. Then choose a path from one of the three response options to be the default path in case of timeout.
- Click the Continue button to close the configuration panel.
- Add steps to each of the paths created by your ChatOps step response options.
Use the Look Up User By Email Action
Look up a Slack user in your workspace using an email address. Use the output of this action as data for other steps.
To configure a Look Up User By Email Action:
- Provide the email of the user to lookup. You can also ingest an email address as an input variable from a previous step in your workflow.
- This action will only look up one user at a time. To look up multiple users, use this step as part of a loop in your workflow.
- Click Save Step to add more steps to your workflow as needed.
Use the Create a Channel Action
Add a new public or private channel to your Slack workspace. Choose to include your Slack bot to manage channel details and users with InsightConnect. You can include data from previous steps in your workflow to set a channel name or description or topic.
To configure an Add New Channel ChatOps action:
- Select if the new Slack channel is going to be public or private. Your Slack bot will be automatically added when creating a new channel in order to manage channel details and users.
- When a channel is set to public, any member of your workspace (excluding guests) can view and join it.
- When a channel is set to private, it can only be viewed or joined by invitation. A private channel cannot be made public later on.
- Provide a name for the new channel. You can also set the channel name using input variables from previous steps in your workflow.
- Slack channel names cannot contain spaces, uppercase letters. Spaces in your Slack channel name will be hyphenated and uppercase characters will be converted to lowercase.
- Slack channel names also cannot contain certain special characters. Channel names containing unallowed special characters will cause the workflow step to fail.
- Add a channel description and topic. Similar to the channel name, you can use data from previous steps to set a channel description or topic.
- The channel topic appears in the channel header and lets people know what members in a channel are working on or about important dates such as project deadlines. Topics can be up to 250 characters in length.
- A channel description is visible when viewing channel details and provides information about a channel’s intended use. Descriptions can be up to 250 characters in length.
Use the Add Users to Channel Action
Use this step to add users within your Slack workspace to a public or private channel using their Slack username or ID. Your Slack bot will need to be a member of the selected channel before you can successfully add users.
To configure an Add Users to Channel ChatOps action:
- Provide the name of the channel you would like to add users to. You can also use input variables from previous steps in your workflow to define the channel name. Your Slack bot must be a member of the channel you have selected in order to add users.
- Provide the username or ID of each user you would like to add to the channel e.g. [“@username1”,”@username2”] or use an input variable from an earlier workflow step e.g. ["{{["my step"].[username]}}"] .
- You can use an email address to return a user ID by using the “Lookup User by Email” workflow step.
- You can add up to 1000 users to a Slack channel at once, attempting to add more than 1000 users will cause the workflow step to fail.
For more help formatting Slack messages, visit Slack documentation at https://api.slack.com/messaging/composing/formatting or try the Slack Block Kit to prototype your message https://api.slack.com/block-kit.
Additional Resources
If you have further questions relating to InsightConnect, try starting a discussion in the Rapid7 Discuss community forum.
Related Posts