Posting BMC Helix ITSM incident and work note updates in Slack by using Jitterbit Harmony

BMC Helix iPaaS, powered by Jitterbit 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 variables with details of your systems 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

You can define Webhook API qualifiers to define additional filters for incidents for which messages should be posted on Slack. You also have the option to restrict access based on user roles for the Webhook API. 

Depending on the fields defined in the project variables, details are displayed in the Slack post. Following is an example of a message posted in Slack when a new 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"

Helix ITSM to Slack data flow

The following image gives an overview of the data flow for posting messages in the Slack channel from a BMC Helix ITSM incident:

Before you begin

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

Required versions
  • Slack version 4.11.3
  • BMC Helix ITSM version 20.08 and later
Authentication and permissions
  • Access to the Slack account
  • Access to create and update incidents in Helix ITSM
Jitterbit Harmony subscription

A valid BMC Helix iPaaS subscription

Application registration

BOT OAuth Token UID for Slack.
For more information about BOT OAuth Token UID for Slack, see  Create a BOT for your workspace .

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, under Scopes on the OAuth & Permissions page of the app, 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 import the integration template project file

  1. Download the Publish BMC Helix ITSM Incident and Work-notes to a Slack channel Update 2022-07-01 project file to your system.
    This file contains the BMC Helix iPaaSCloud Studio project Post BMC Helix ITSM Incident and work notes to a Slack channel.

    Important

    Your ability to access product pages on the EPD website is determined by the license your company purchased.

  2. As a developer, log in to BMC Helix iPaaS and navigate to the Cloud Studio.
  3. On the projects page, click Import.
  4. Click Browse to navigate to and select the Publish BMC Helix ITSM Incident and Work-notes to a Slack channel Update.json file you downloaded. 
    The Project Name and Organization fields are automatically populated depending on the values defined. 
  5. From the Environment list, select the environment to which you want to import this integration template, and click Import.
    The project opens after the integration template is imported. 
    To open the project file at a later time, select the environment where the integration templates are available, select the Post BMC Helix ITSM Incident and work notes to a Slack channel project.

Task 3: To update the project variables for the integration template

  1. Next to the Environment name, click the ellipsis ... and select Project Variables.
  2. Update the following project variables:
    • Access points and authentication details for Helix ITSM, Slack, and BMC Helix iPaaS applications

      Project variableDescription
      Helix ITSM
      ITSM_EndpointEnter the BMC Helix ITSM host URL
      ITSM_APP_TYPEEnter the name of the application or form; for example, SmartIT, Midtier.
      ITSM_ServerRoot_URLEnter the ITSM Server root URL based on value you selected for ITSM_APP_TYPE.
      ITSM instance userEnter the user ID to use to access BMC Helix ITSM.
      ITSM_HelpDesk_Qualifier

      To add conditions to the Webhook to define urgency filters for incidents for which messages should be posted, enter the qualifiers.

      You can use qualifiers like =, !=, and so on. Urgency type values include: 1-Critical, 2-High, 3-Medium,4-Low.

      The default value is set to

      ('Urgency' ="1-Critical") AND ('Impact' = "2-Significant/Large" OR 'Impact' ="1-Extensive/Widespread") AND ('Service Type' != "Security Incident")

      BITSM_Worknote_Qualifier

      To add conditions to the Webhook to define filters for the Work Notes for which messages should be posted, enter the qualifiers.

      The default value is set to

      'Work Log Type'="General Information" OR 'Work Log Type'="Customer Communication" OR 'Work Log Type'="Customer Follow-up" OR 'Work Log Type'="Customer Status Update" OR 'Work Log Type'="Resolution Communications"

      ITSM_Message_Fields

      Enter a comma separated list of incident fields to add to the Slack message.

      Valid values include:

      • Company
      • Description
      • Impact
      • Urgency
      • Priority
      • Incident Type
      • Reported Source
      • Assigned Group
      • Status

      For example, if you enter Company, Description, Status, the following details are displayed in the Slack post for the incident creation

      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"

      ITSM_UsernameEnter the user ID to access BMC Helix ITSM.
      ITSM_PasswordEnter the password of the user to access BMC Helix ITSM.
      Slack
      Slack_BOT_OAuth_TokenEnter the unique BOT OAuth Token UID for Slack that you generated in Step 1 - Create the Slack channel and define scope for the BOT OAuth.
      BOT OAuthorization TokenEnter the BOT OAuthorization Token Value from Slack API.
      Slack_ChannelEnter the name of the Slack channel where the messages should be posted.

      BMC Helix iPaaS

      BHIP_Url

      Enter the host URL of BMC Helix iPaaS.

      BHIP_User

      Enter the user ID to access BMC Helix iPaaS.

      BHIP_User_Password

      Enter the password of the user ID to access BMC Helix iPaaS.

    • Webhook API variables

      Project variablesValue
      BHIP_Project_Name

      Enter the name of the BMC Helix iPaaS project for which to create the integration API.

      BHIP_Operation_Name
      Enter the name of the operation to trigger when the Webhook API is triggered. This value is added to the BMC Helix iPaaS Jitterbit API.

      By default, the value is set to Initial Data Loading.

      BHIP_API_NameEnter the name for the Webhook API that is created in BMC Helix ITSM.
      BHIP_API_Response_Type

      Enter the RestAPI response type used by the Webhook API created.

      BMC Helix iPaaS

      By default, set to FINAL_TARGET.

      BHIP_API_Security_Profile_Type
      Enter the Security Profile type defines the authentication type to be used by the Webhook API. This value is added in the BMC Helix iPaaS Jitterbit API.

      Valid values include:

      • BASIC (Default)
      • ANONYMOUS

      Enter comma separated values to select multiple profile types (ANONYMOUS, BASIC).

      Important:

      • For profile types supported by the source application, the security profiles are automatically created by the integration template when you enable the integration. 
      • BMC Helix iPaaS does not support OAuth authentication for this application.
      BHIP_API_Security_Profile_Name_Suffix
      Enter a suffix to be added to the name of security profiles created.
      BHIP_API_Security_Profile_BASIC_Auth_Username For security profile type BASIC, enter the username to be used to create the security profile.
      This username is used for authentication by the Jitterbit API and the Webhook API.
      BHIP_API_Security_Profile_BASIC_Auth_Password
      For security profile type BASIC, enter the password for the security profile created.
      This password is used for authentication by the Jitterbit API and the Webhook API.
      BHIP_API_User_Roles

      Enter a comma separated list of values of the user roles assigned for the BMC Helix iPaaS API.

      Only users with these roles can access the APIs. Leave value blank to restrict access only to administrators.

      ITSM_Webhook_Name

      Enter a name for the Webhook to be created in ITSM instance.

      ITSM_Webhook_Security_Profile_Type

      Enter the security profile used by the ITSM Webhook to call the BMC Helix iPaaS Jitterbit API

      Valid values include:

      • BASIC (Default)
      • No Authentication

      Important:

      • The security profiles are automatically created by the integration template when you enable the integration. 
      • BMC Helix iPaaS does not support OAuth authentication for this application.

      BHIP_API_TimeOut

      Enter an API timeout value, in seconds.

      The minimum value must range between 30 and 180. By default, the value is set to 90.

    • Email notification configurations

      Project variableDescription
      BHIP_SMTP_Hostname
      Enter the SMTP host details for emails configuration.
      BHIP_To_Email_Address
      Enter comma separated values of email addresses to which you want to send the notification emails.
      BHIP_From_Email_Address
      Enter the email address from which the notification emails should be sent.
      BHIP_Email_Summary

      To disable email notifications for successful operations, set the value to false.

      By default, this value is set to true

      This value defines if notification emails with a summary should be sent if workflow is successful

      BHIP_Email_Enabled

      To disable email notifications, update the Default Value to false.

      By default, the value is set to true

      This value defines if notification emails should be sent if workflow is successful.

      BHIP_Email_Data_Error

      To disable email notifications for errors, set the value to false.

      By default, this value is set to true

      This value defines if emails should be sent if an error occurs when executing the workflow

Task 4: To deploy and enable the project

Deployment is a one-time activity that initializes the integration configurations. The UI displays a message for the deployment status.

To deploy the project and then enable the integration:

  1. To deploy the project, next to the project name, click the ellipsis ..., and select Deploy Project.
  2. To enable the integration, next to the Enable Integrations workflow, click the ellipsis ..., and select Deploy

The following image shows the steps to deploy the project and enable it by deploying the workflow:

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.

(Optional) Task 5: To set the time for API debug mode

By default, the debug mode is set to 2 hours after you run the integration. Debug logs are updated for the time set for the debug mode. To increase the debug mode for a longer period of time, perform the following steps:

  1. In BMC Helix iPaaS, powered by Jitterbit, select API Manager > My APIs.

  2. Open the API created for the integration. The API name is the value defined in the BHIP_API_Name project variable.

  3. Select Enable Debug Mode Until: and set it for the required date and time.

  4. Save and publish the API.

Workflows included in the integration template

The following workflows are defined as a part of the integration template. This section describes the details of the operations and configurations defined within each workflow.

Enable Integration

Set up the required details for the integration.

Create and Publish Custom APIs

This workflow defines the operations required to enable the integration after all the required project configurations are completed. The following operations are included in this workflow:

Operation nameActions performed
BHIP Login

Logs in to BMC Helix iPaaS by using the credentials provided in the project variables

BHIP Get Api and Security Profiles detailsVerifies if any custom APIs or security profiles exist for the BMC Helix ITSM integration
BHIP Create Security Profiles or Custom API

Creates the security profiles and RestAPIs in BMC Helix iPaaS

BHIP Delete API or Security ProfileDeletes existing APIs or security profiles, if required
BHIP Publish API

Publishes the custom APIs to BMC Helix iPaaS and BMC Helix ITSM

Create ITSM Webhook

This workflow creates the Webhook required for BMC Helix ITSM. The following operations are included in this workflow:

Operation nameActions performed
Login to ITSMLogs in to BMC Helix ITSM by using the credentials provided in the project variables
Check ITSM Webhook ExistenceVerifies if the Webhook API configurations exist in BMC Helix ITSM

Create ITSM Webhook

Creates the Webhook API configuration to BMC Helix ITSM

Delete Existing ITSM Webhook

If Webhook API configuration exists, deletes the existing configuration
Failure NotificationSends an email notification if the Webhook API configuration is not added to BMC Helix ITSM

Post Slack Message for ITSM Incident

This workflow posts Slack messages when a BMC Helix ITSM incident is created or updated. The following operations are included in this workflow:

Operation nameActions performed
Integration API Flow ControllerEnables all the API entry points by using the details provided in the project variables
Fetch Incident DetailsGets details of the BMC Helix ITSM incident to add details to the Slack channel
Fetch incident Work NoteGets details of the BMC Helix ITSM incident work note to add to the Slack channel
Post Slack MessagesAdds the incident or work note details to the Slack channel
Failure NotificationSends an email notification if incident creation or update fails
Was this page helpful? Yes No Submitting... Thank you

Comments