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:

Use case

BMC Helix ITSM to Slack

Create a Slack post

Creates a Slack post when:

  • An incident is created and then auto-updated in BMC Helix ITSM
  • An incident is updated in BMC Helix ITSM
  • The incident work note with view access Public is created or updated in BMC Helix ITSM

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.

Example of a slack message

ITSM incident created with the following details:
Incident Number: "INC000000146214"
Incident URL: "https://itsm.trybmc.com/smartit/app/#/incident/IDYHFS6GAQKVXAQK4GT9Q95SKL6C0K"
Company: "Calbro Services"
Description: "Email server failure"
Status: "Assigned"

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:

221_Slack_ITSM_PostMessages.png

Before you begin

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

Required versions

  • Slack version 4.3.2 and later
  • BMC Helix ITSM version 19.11 and later

Authentication and permissions

  • Access to the Slack account
  • Access to create and update incidents in BMC Helix ITSM

MuleSoft Anypoint platform subscription

A valid MuleSoft Anypoint platform license

Important: BMC provides pre-build integration templates for the MuleSoft platform, targeting common integration use cases for BMC products. To obtain a MuleSoft platform license, contact MuleSoft support.

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.