D3 - Mattermost Bi-Direction Automation Configuration Guide
LAST UPDATED: OCT 9, 2024
D3’s integration with Mattermost facilitates the establishment of a comprehensive automation workflow between Mattermost users and D3 playbooks. Users are not required to log in to the D3 vSOC to approve or deny requests during investigations. Instead, they can interact directly through Mattermost via interactive messages that include menu options or buttons, facilitating a seamless connection between the two platforms.
Supported Interactive Message Contents
The Send Message command supports the following types of interactive message contents:
Menu: Only the selected option will be submitted to D3 via the URL configured for the message.
Buttons: Only the clicked button value will be submitted to D3 via the URL configured for the message.
User Experience Enhancement
To enhance the user experience, D3 recommends incorporating an Update Message task to update the sent message. This task will provide a reply or remove the interactive part to avoid confusing users if the option has been submitted.
Configuration
Command: Send Message
PARAMETER Properties
The interactive message configuration will be set in the parameter as follows:
{
"attachments": [
{
"pretext": "The title of the button section",
"actions": [
{
"name": "Button1 name",
"integration": {
"url": "<<D3Automation>>",
"context": {
"action": "a1",
"other": "1st webhook",
"comment": "the preconfigured comment1"
}
},
"type": "button"
},
{
"name": "Button2 name",
"integration": {
"url": "<<D3Automation>>",
"context": {
"action": "a2",
"other": "2nd webhook",
"group": "group2"
}
},
"type": "button"
}
]
},
{
"pretext": "The message text",
"text": "The title of the menu section",
"actions": [
{
"name": "The message shows on the menu",
"integration": {
"url": "<<D3Automation>>",
"context": {
"action": "predefined value to send back"
}
},
"method": "POST",
"type": "select",
"options": [
{
"text": "Option1",
"value": "opt1"
},
{
"text": "Option2",
"value": "opt2"
},
{
"text": "Option3",
"value": "opt3"
}
]
}
]
}
]
}
$.attachments (Required): The entry key for the interactive message. Each JSON object in this field will represent an interactive message, akin to the adaptive card.
$.attachments[*].pretext (Optional): The message for the interactive message card.
$.attachments[*].text (Optional): The text in the interactive message card.
$.attachments[*].actions (Required): The most critical section for building the interactive message card. When multiple action JSON objects are set in the same array, multiple interactive contents will be displayed in the same interactive message.
$.attachments[].actions[].type (Required): Indicates the type of the action. Valid values are:
select: The type of the menu-type message.
button: The type of the button-type message.
$.attachments[].actions[].name (Optional): The name of the interactive part of the message.
$.attachments[].actions[].integration (Required): The feature that enables D3 to interact with Mattermost.
$.attachments[].actions[].integration.url (Required): If the user wishes to send the action back to D3, use the placeholder <<D3Automation>> to allow D3 to generate the unique webhook URL for this action. The generated URL will be the same in the message, enabling the webhook request to send back the submitted value to the task.
Each button-type action must have a different context to indicate which button has been clicked.
The menu-type message does not need to set the value in the context during configuration. The selected option will be sent back to D3 in the context.
$.attachments[].actions[].integration.context (Optional): The preconfigured value to identify the interactive action. The JSON format value can be set with any fields and values. The preconfigured values will be sent back to D3.
For button types, the context data must be set with different values for each action to indicate which button has been clicked.
Command: Update Message
PARAMETER Update Whole Message
True: Will update the entire message, including the interactive card.
False: Will only update the fields with values.
PARAMETER Message ID
This can be retrieved from the Send Message command.
PARAMETER Message
SAMPLE MESSAGE
**The action has been submitted**
Submitted Action:
- Approval
- ~~Decline~~
The option has been selected
Submitted Option:
- ~~opt1~~
- ~~opt2~~
- opt3
SAMPLE UI
PARAMETER Properties
When the parameter Update Whole Message is set to True, leaving this parameter empty will clear the interactive card from the message.
When the parameter Update Whole Message is set to False, leaving this parameter empty will retain the interactive card in the message.
SAMPLE
{
"attachments": [
{
"pretext": "The button approval has been submitted."
},
{
"pretext": "The option opt3 has been submitted."
}
]
}
Response
The response from Mattermost can be found in the Context Data of the Send Message command task. The following task could use the context data's value to select the next workflow.
Menu Message's Response
The $.context.selected_option is the selected option sent back to D3.
SAMPLE
{
"user_id": "6tqxxoaeutnp9ndxpj3imo7zoe",
"user_name": "jonhD",
"channel_id": "ok7fqqtsbtnyxpaazr4cs9nmfo",
"channel_name": "d3internal",
"team_id": "77573qwdyfyfywdnoc7ie4u1byw",
"team_domain": "d3-security",
"post_id": "xc7tht4peir9pfr5bsjbggiwee",
"trigger_id": "MXExdXJiOWNmdG5tZm03Y2Yxc3duZHk2cWU6NnRxeHhvYWV1dG5wOW5keHBqM2ltbzd6b2U6MTcyODAwODUzMzUzMjpNRVVDSURiTTN3L2VKRkJrSS8rMFhndmU4dmV4VlJVRDRwWnR0VzRLdERYWi8yL29BaUVBOVFYYXo5NlRGTzEwcnh3K2JFTFRlMnNmdFBmeFJxWko5YVQxOTZ3WTFpMD0=",
"type": "select",
"data_source": "",
"context": {
"action": "option1234",
"selected_option": "opt3"
}
}
Button Message's Response
The $.context.action represents the clicked button sent back to D3. The action key is predefined in the Send Message command and can be any key or value the user wishes to use.
READER NOTE
If the context data of the actions is set with the same value, it may cause confusion regarding which button has been clicked.
SAMPLE
{
"user_id": "6tqxxoaeutnp9ndxpj3imo7zoe",
"user_name": "jonhD",
"channel_id": "ok7fqqtsbtnyxpaazr4cs9nmfo",
"channel_name": "d3internal",
"team_id": "77573qwdyfy9dfnoc7ie4u1byw",
"team_domain": "d3-security",
"post_id": "4bbpikeqtjbnjxaghfyoo7c4fo",
"trigger_id": "OXV3N293M25ydHIzNXI5c2cxenhtYjZzcHk6NnRxeHhvYWV1dG5wOW5keHBqM2ltbzd6b2U6MTcyODAwODUyODc5MDpNRVFDSURQaGFGbE5IZlpHOGdRQkxtTVYxc0JmS2t4emJIMlN1UmNLUm85Mzh1V1ZBaUI4VTNRK0hrZzR1T05ZS2p5QUhTTG1BT2l6bWZ0QkllRFVhTVNGbnZKWmNBPT0=",
"type": "button",
"data_source": "",
"context": {
"action": "A1"
}
}