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

Use case

BMC Helix ITSM to Microsoft Teams

Microsoft Teams to BMC Helix ITSM

Create a Microsoft Teams post

Creates a post in Microsoft Teams when an incident is created or updated in BMC Helix ITSM.

A link to the incident is also included in the post.

NA
Creates a post in Microsoft Teams when an incident work note with view access Public is created in BMC Helix ITSM

Creates a post in Microsoft Teams when an attachment is added to an incident in BMC Helix ITSM.

The attachment is available in the post. 

Creates a post in Microsoft Teams when the status of the incident status is updated
Synchronize commentsNA

Synchronizes the comments posted on the Microsoft Teams channel for a specific incident with the BMC Helix ITSM incident work notes

Update statusesNA

Updates the status of a specific incident from a Microsoft Teams post

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:

Example of a Teams message

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"

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: 

Required versions
  • Microsoft Teams version 4.8.25.0 or later
  • BMC Helix ITSM version 21.05 or later
Authentication and permissions
  • Access to the Teams channel where the messages are to be posted
  • Access to create and update incidents in BMC Helix ITSM
Jitterbit Harmony subscription

A valid  BMC Helix iPaaS Open link  subscription

Application registration

Register your application and generate a client ID and client secret for Microsoft Teams. For more information about registering your application and getting access tokens, see  Get access without a user Open link .

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 Open link 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 variableAction
    BMC Helix ITSM
    ITSM_EndpointEnter the BMC Helix ITSM host URL.
    ITSM_APP_TYPEEnter the name of the application or form name; for example, SmartIT, Midtier.
    ITSM_ServerRoot_URLEnter the BMC Helix ITSM Server root URL based on ITSM_APP_TYPE variable.
    ITSM_UsernameEnter the user ID to access BMC Helix ITSM.
    ITSM_PasswordEnter 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_PasswordEnter 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 variablesAction
    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. 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_TypeDefine 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 variableAction
    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

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 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:

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

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

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:

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 Teams channel
Fetch incident Work NoteGets details of the BMC Helix ITSM incident work note to add to the Teams channel
Post Teams MessagesAdds the incident or work note details to the Teams channel
Failure NotificationSends an email notification if incident creation or update fails
Was this page helpful? Yes No Submitting... Thank you

Comments