Posting BMC Helix ITSM incident and work note updates in Slack by using MuleSoft Anypoint platform

BMC Helix iPaaS, powered by MuleSoft provides a prebuilt integration template that enables you to post Slack messages when an incident or an incident work note is created or updated in BMC Helix ITSM. To use the integration template with the values defined out of the box, you update the project configuration with details of your systems, create the required Webhook registrations, and deploy the integration template. 

The template provides the following capabilities:

Depending on the fields defined in the project configuration, details are displayed in the Slack post. Refer to the following example of a message posted in Slack when a new BMC Helix ITSM incident is created.

BMC Helix ITSM to Slack data flow

The following image gives an overview of the data flow for posting Slack messages for an incident or work note created or updated in BMC Helix ITSM:

Before you begin

You require the following items to successfully set up and use this integration: 

Task 1: To create the Slack channel and define scope for the BOT OAuth

1. Create an App in Slack and assign a Slack Workspace (channel) to the app.
2. When you create the App, on the Basic Information page, the App Credentials section displays the credentials that are required to access the App API.
3. To be able to post messages to the Slack channel, define the scope for the app and install it to the Slack workspace.
   1. To add permissions for the app, on the OAuth & Permissions page, under Scopes, click Add an OAuth Scope.
   2. Add the chat:write permission.
   3. To generate the OAuth token to authenticate your app, click Install App to Workspace.
   4. To provide the permission required to access the Slack workspace, when prompted, click Allow.
      The OAuth token is automatically generated and displayed on the OAuth Tokens & Redirect page. You need to add this value to the Target_BOT_OAuth_Token project variable.

   5. Navigate to the Slack Workspace (channel) created for the App. 

   6. Enter the following message to join:
      type msg : "invite @appName" 

   7. When promoted, click Invite Them to enable users to add messages to the Slack channel.

For detailed information about creating the app and defining the scope for the BOT OAuth, see  Create a BOT for your workspace .

Task 2: To download and deploy the integration template project

1. Download the  Publish ITSM Incident and Work-notes to a Slack channel 2021-06-01  file for the integration template.

2. Log in to the MuleSoft Anypoint Platform and select Runtime Manager. 

3. To configure your integration template, click Deploy application.

4. To select the .jar file that you downloaded, and enter project details, on the Runtime tab of the Deploy Application page, select the following values:

   Field name	Value
   Application Name	Enter a unique name for your application.
   Deployment Target	Select the space for deploying the application, for example, CloudHub.
   Application File	Select Choose File > Upload file, and select the Integration template .jar file.
   Runtime tab
   Runtime version	Select the MuleSoft runtime version used to develop the application.
   Worker size	Select a core size for your application.  The core size defines resource allocation for your application and impacts performance.  For more information about worker size, see  Cloudhub workers .
   Workers	Select the number of dedicated instances of Mule for the application. Deploying your application with more than one worker balances incoming load across allocated worker nodes. It also provides a backup if any of the worker nodes is not responding.

5. On the Properties tab of the Deploy Application page, add the following values:

   key	value
   ITSM properties
   itsm.connector.url	Enter the host URL For BMC Helix ITSM.
   itsm.connector.userName	Enter the user ID to access BMC Helix ITSM.
   itsm.connector.passWord	Enter the password of the user to access BMC Helix ITSM.
   itsm.application.type	Enter the name of the application or form name; for example, SmartIT, Midtier
   itsm.serverRoot.url	Enter the root URL for the BMC ITSM Server, based on itsm.application.type value
   itsm.worknotes.viewaccess	Set the value to Public. This value defines the permission for viewing the BMC Helix ITSM worknotes.
   Slack properties
   slack.connector.token	Enter the unique BOT OAuth Token UID for Slack. Use the value generated in Task 1.
   slack.connector.channel	Enter the name of the Slack channel where the messages should be posted.
   MuleSoft API Webhook properties
   api.webhook.profile.type	Enter Basic.
   api.webhook.profile.username	For Webhook Profile type as BASIC, provide the username for authentication.
   api.webhook.profile.password	For Webhook Profile type as BASIC, provide the password for authentication.

6. Optionally, if you want to enable email notifications, add the following values:

   Email notification configurations
   email.property.smtp	Enter the SMTP host details to configure the email.
   email.property.recipients	Enter a comma separated list of email addresses for recipients who should receive the failure notification, if the request fails.
   email.property.sender	Enter the email address to be used for sending emails.

7. Click Deploy Application. 
   While the application is being deployed, the log updates are displayed. After the application is successfully deployed, a green circle is displayed next to the template name.

Task 3: To register Webhooks for Incident and Worklog forms

1. Log in to Mid Tier. 

2. Enter the following URL to access the AR System Webhook Registration form: 
   https://<serverName>/arsys/forms/onbmc-s/AR+System+Webhook/Default+Administrator+View.

3. Click New Request, and add the following values to the AR System Webhook Registration form:

   Field name	Action
   Form Name	To add a Webhook for the BMC Helix ITSM incident form, enter HPD:Help Desk. To add a Webhook for the work notes, enter HPD:WorkLog.
   Events	Select Yes for the Create and Update events.
   Callback Information
   Callback URL	Enter the callback URL in the format: https://<serverURL>/<basePath>/<itsmPath> where, serverURL— serverURL is the Domain url displayed on the application details page in Anypoint Platform basePath— http.listener.basePath defined in the # HTTP Listener Configuration section of the common.properties file in the Anypoint Studio project itsmPath— http.listener.itsmPath defined in the # HTTP Listener Configuration section of the common.properties file in the Anypoint Studio project
   Authentication Type	Select the api.webhook.profile.type defined in the # Mulesoft API Webhook Properties section of the common.properties file in the Anypoint Studio project
   User Name	Select the api.webhook.profile.username defined in the # Mulesoft API Webhook Properties section of the common.properties file in the Anypoint Studio project
   Password	Select the api.webhook.profile.password defined in the # Mulesoft API Webhook Properties section of the common.properties file in the Anypoint Studio project

4. Save the form.

Task 4: To enable the integration

To enable the integrations, you need to run the webhook creation scripts from your MuleSoft Anypoint Platform. These scripts automatically create the required webhooks for the integration.

1. Log in to the MuleSoft Anypoint Platform and select Runtime Manager. 

2. On the Applications tab, click the project name.

3. On the application details page, click Schedules. 

4. Select the appropriate option from the list displayed, and click Run Now. The following options are available:

   Name	Description
   ITSM-Create-Integration_Manual Trigger	Creates the required Webhooks to enable creation of Slack posts from BMC Helix ITSM incidents or work notes
   ITSM-Pause-Integration_Manual Trigger	Pauses the sync of incident and work notes between the BMC Helix ITSM incidents and Slack
   ITSM-Purge-Integration_Manual Trigger	Deletes the Webhooks created to enable creation of Slack posts from BMC Helix ITSM incidents or work notes
   ITSM-Resume-Integration_Manual Trigger	Resumes the sync of incident and work notes between the BMC Helix ITSM incidents and Slack

   After you enable the integration, messages are posted on the Slack channel when an incident record or work note in an incident is created or updated in BMC Helix ITSM. The BMC Helix ITSM Incident ID is displayed is also displayed in the Slack message.