Slack Integration

This extension adds the capability to send notifications based on actions and triggers to collaboration tool Slack. This page describes how to configure and work with the extension in order to send notifications to Slack.

By default the only available kind of action consists in sending email. This extension defines a new type of Action: Slack Notification. You are able to:

• Send notifications to Slack
• Configure the target of the notification (slack workspace, channel, person)
• Configure display bot name of the incoming notification in Slack
• Format the messages by adding Headlines, links, edit the color etc.
• notice and react faster to changes in your iTop

• While iTop works with HTML to format messages, Slack uses an own markdown like language. This extensions transform HTML to markdown. But due to the limitations of the slack markdown currently images will not send to Slack and headings will only be displayed as bold.
• Until now it is not possible to send slack notifications asynchronous. So keep an eye on the config parameter “timeout”.

• Existing Slack workspace
• Configured webhook
• URL of the webhook (it looks like: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX)

• Use the Standard installation process for this extension.
• Check Slack Integration in the list of extensions at the end of the interactive wizard.

The following settings are available to configure the module:

Slack Notification is a special type of Action. It is based on Action/Triggers. The usage is quite similar to an email notification.

To view your Slack notifications use the link “Notifications” in the “Admin tools” menu and click on the tab “Actions”.

To create a new action, go to the “Actions” tab and click on “New…”. The following wizard appears:

The mandatory fields for a slack notification are:

• Name: iTop Name of the Slack Notification
• Slack URL: URL of the Slack webhook. (see: https://get.slack.help/hc/en-us/articles/115005265063-Incoming-WebHooks-for-Slack)
• Status: Only in state production notifications will send to slack (Default: Being tested)
• Debug trace: If enabled the extension writes an on log for debug purpose in log/slackintegration.log (Default: no)

Without any other Information iTop will send an empty notification to Slack.

Beside the Slack URL you are able to specify the following attributes:

• Channel or Person: If you enter a channel name (i.e. #general) or a person name (i.e. @personname) the message will to this channel or person. If left blank the message will send to the default channel configured in the Slack webhook.
• App name: Enter a bot name which will displayed as the sender name of the notification in slack. If left empty the default name configured in the slack webhook will be displayed.

You can add content to your notification by editing the attribute “simple text”. It is possible to format your message via HTML and add placeholders. Placeholders works in the same way like they do in the email notification. Fore more information please see this site.

For an improved formatting you can use a slack message attachment. An attachment will be shown below the simple text, indented and marked with a color at the left side.

To enable the attachment set the attribute “Use an attachment?” to “yes” and edit the following attributes:

• Attachment title: Title above the attachment text.
• Attachment link: Enter an OQL query to an Object. The Slack notification will add a link to the attachment title pointing to the Object defined in the OQL. If the OQL matches more than one object currently just the first object will be linked. You are allowed to use placeholders in the OQL. For instance:

SELECT Ticket WHERE id= :this->id

• Attachment Color: Specify the color of the attachment message by using hexadecimal color value
• Attachment Text: Text of the attachment. You are able to using HTML and placeholders.
• Attachment Fallback: Fallback in case of Slack is not able to display the the Attachment (i.e. in a notification preview) You are able to using HTML and placeholders.

To define when an notification have to be sent, you have to define a Trigger and link the notification to the trigger. Switch to the tab “Related Triggers” an click “Add Triggers…” to add an existing Trigger to your Notification.