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

BMC Helix iPaaS, powered by Jitterbit provides a prebuilt integration template that enables you to post messages to a Microsoft Teams channel 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: 

You can define Webhook API qualifiers to define additional filters for incidents for which messages should be posted on Microsoft Teams. 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 Microsoft Teams post. The following message is an example of the post in Microsoft Teams when a new incident is created:

BMC Helix ITSM to Microsoft Teams data flow

The following image gives an overview of the data flow for posting a Microsoft Teams message from an incident or work note created or updated in a BMC Helix ITSM incident:

Before you begin

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

Task 1: To download and import the integration template project file

1. Download the Publish BMC Helix ITSM Incident and Work-notes to a MS Teams Channel Update 2022-07-01 file.
   This file contains the BMC Helix iPaaS Cloud Studio project MSTEAMS_ITSM.
   

   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 MS Teams 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 MSTEAMS_ITSM project and click View/Edit.

Task 2: 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 BMC Helix ITSM, Teams, and BMC Helix iPaaS applications

  Project variable	Action
  BMC Helix ITSM
  ITSM_Endpoint	Enter the BMC Helix ITSM host URL.
  ITSM_APP_TYPE	Enter the name of the application or form name; for example, SmartIT, Midtier.
  ITSM_ServerRoot_URL	Enter the BMC Helix ITSM Server root URL based on ITSM_APP_TYPE variable.
  ITSM_Username	Enter the user ID to access BMC Helix ITSM.
  ITSM_Password	Enter the password of the user to access BMC Helix ITSM
  ITSM_HelpDesk_Qualifier	Enter the qualifiers to add conditions to the Webhook to define urgency filters for incidents for which messages should be posted. 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")
  ITSM_Worknote_Qualifier	Enter the qualifiers to add conditions to the Webhook to define filters for the Work Notes for which messages should be posted. 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 comma-separated names of incident fields to add to the Teams message. Valid values include: Company Description Impact Urgency Priority Incident Type Reported Source Assigned Group Status For example, if you enter Incident Type, Description, Assignee, Impact, Urgency, Priority, Reported Source, Assigned Group, and Company the following details are displayed in the Teams post for the incident creation: ITSM incident created with the following details: Incident Number: "INC000000143642" Incident Type: "User Service Request" Description: "OleDB: Results Error" Status: "Assigned" Impact: "1-Extensive/Widespread" Urgency: "1-Critical" Priority: "Critical" Reported Source: "Email" Assigned Group: "Service Desk" Company: "Calbro Services" Incident URL: "https://mobility244-dsom-ar.trybmc.com/arsys/forms/onbmc-s/SHR%3ALandingConsole/Default+Administrator+View/?mode=search&F304255500=HPD:Help%20Desk&F1000000076=FormOpenNoAppList&F303647600=ShowTicket&F304249330=AGGJFNOTGHDQLAQS17R1QR2S7F8F5E"
  Teams
  MSTeam_Client_Id	Enter the Microsoft Teams Application Client ID.
  MSTeam_Client_Secret	Enter the Microsoft Teams Application Client Secret.
  MSTeam_Tenant_Id	Enter the Microsoft Teams Application Tenant ID.
  MSTeam_User_Name	Enter the Microsoft Azure Account User Name.
  MSTeam_Password	Enter the Microsoft Azure Account Password.
  BMC Helix iPaaS
  BHIP_Url	Enter the BMC Helix iPaaS URL.
  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 variables	Action
  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_Name	Enter 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. This value is added in the BMC Helix iPaaS Jitterbit API.  By default, set to FINAL_TARGET.
  BHIP_API_Security_Profile_Type	Enter a security profile type. Valid values include: BASIC (Default) ANONYMOUS Enter comma separated values to select multiple profile types (ANONYMOUS, BASIC). A 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. 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 user name 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_Authentication_Type	Define which authentication method to use if multiple values are defined in the BHIP_API_Security_Profile_Type project variable.
  ITSM_Webhook_Name	Enter the name for Webhook to be created in the BMC Helix ITSM instance.
  ITSM_Webhook_Security_Profile_Type	Enter a security profile type to be used by the BMC Helix ITSM Webhook to call the BMC Helix iPaaS Jitterbit API Valid values include: BASIC (Default) No Authentication 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.

• Email notification configurations

  Project variable	Action
  BHIP_SMTP_Hostname	Enter SMTP host details for emails configuration.
  BHIP_To_Email_Address	Enter the email address 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	Define if notification emails with a summary should be sent if workflow is successful. By default, this value is set to true. To disable email notifications for successful operations, set the value to false.
  BHIP_Email_Enabled	Define if notification emails should be sent if workflow is successful. By default, the value is set to true. To disable email notifications, set the value to false .
  BHIP_Email_Data_Error	Define if emails should be sent if an error occurs when executing the workflow. By default, this value is set to true. To disable email notifications for errors, set the value to false.

Task 3: To define the channel to post the messages

1. To configure the details of the channel where the messages must be posted, on the Workflows tab of your template, select 4.0 Post Team Message for ITSM Incident > 4.3 Post Teams Channel.
2. To open the configuration options, next to the Send Message activity select the ellipses (...) and then select View/Edit.
   
3. On the configuration screen, select the team that includes the channel to which you want to post the messages, and click Next.
   
4. On the next screen, select the channel to which you want to post the messages, and click Next.
   
5. Review the request and response data schemas, and click Finished.

Task 4: To deploy and enable the project

After you enable the integration, messages are posted on the Teams 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 Teams 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 Teams API.

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:

Create ITSM Webhook

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

Post Teams Message for ITSM Incident

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