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

BMC Helix iPaaS, powered by MuleSoft 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 Microsoft Teams post when:

  • A user or updates creates an incident.
    A link to the incident is also included in the post. Impact values can include Impact 1-Extensive/Widespread or 2-Significant/Large and Urgency 1-Critical.
  • Incient values are auto-updated.
  • A user adds or updates an incident work note with view access Public.
  • An attachment is added to an incident work note.
    The attachment is stored in Microsoft SharePoint and a reference to it is available in the post. 

NA

Update the BMC Helix ITSM incident

NA

Updates the BMC Helix ITSM incident when:

  • A user adds a post to the post created for the incident.
  • A user updates the BMC Helix incident status value by using an outgoing Webhook.

Data flow between BMC Helix ITSM and Microsoft Teams

The following image gives an overview of the data flow for posting a teams message from a BMC Helix ITSM incident:

Data flow between Microsoft Teams and BMC Helix ITSM

The following image gives an overview of the data flow for adding work notes in BMC Helix ITSM from a Microsoft Teams post:

The following image gives an overview of the data flow for updating the status value in BMC Helix ITSM from a Microsoft Teams post:


Before you begin

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

Required versions
  • Microsoft Teams version 1.0 and later
  • BMC Helix ITSM version 19.11 and later
Authentication and permissions
  • Access to the Microsoft Team and the associated channel where the messages are to be posted
  • 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.

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 .

Important:
The client ID is the Application ID provided on the Overview page of your registered application. The client secret is available on the Certificates and secrets page of your registered application.
For more information about generating a new client secret, see Create or update client IDs and secrets in Partner Center .

Task 1: To configure Microsoft Teams and Sharepoint application

Complete the following steps to configure the Microsoft Teams application.

Task 1.1: To register your Microsoft Teams application from Microsoft Azure and define the Redirect URIs

  1. Register your Microsoft Teams application using the Azure Portal.
    For more information about registering your application, see Register an application with the Microsoft identity platform .
  2. Register the Microsoft Teams OAuth connection callback URL for the registered application. 
    1. Log in to the Azure portal.
    2. Navigate to your registered application. 
    3. Select Manage > Authentication
    4. Under Redirect URI, add the callback URL for the application deployed in MuleSoft Anypoint platform in the following format:
      https://<applicationURL>/callback
      where applicationURL is the
      URL displayed on your Applications page of the application deployed in MuleSoft Anypoint platform.

Task 1.2: To perform the OAuth dance to complete the authorization process

To complete the authorization process, complete the OAuth dance which is the authentication process performed by the Mule OAuth 2.0 provider, API, and the client application. 
Run the following OAuth authorize URL:
https://<serverURL>/<config.oauth.authorization.code.authorizePath>?resourceOwnerId=<config.oauth.authorization.code.resourceOwnerId>
where: 

serverURL

URL displayed on your Applications page of the application deployed in MuleSoft Anypoint platform.

config.oauth.authorization.code.authorizePathValue for this variable is defined in project configuration variables defined in Task 2
config.oauth.authorization.code.resourceOwnerIdValue for this variable is defined in project configuration variables defined in Task 2.

Task 1.3: To add an outgoing Webhook for the Teams channel

To update the status of an incident from a Microsoft Teams post, create an outgoing webhook for the Teams channel. For more information about creating an outgoing Webhook, see Create an Outgoing Webhook .

The callback URL we add to the outgoing Webhook is the callback URL for the MuleSoft application to which the data is sent to be processed and forwarded to BMC Helix ITSM. The format of the URL is as follows:
https://<muleSoftApplicationURL>/<http.listener.teamsPath>
where,

    • muleSoftApplicationURL is the application URL displayed on your Applications page of the application deployed in MuleSoft Anypoint platform.
    • http.listener.teamsPath is the value defined for this variable in the HTTP Listener Configuration of the common.properties file located in the src/main/resources > config folder of your template project in MuleSoft Anypoint Studio.

Task 1.4 To configure Microsoft SharePoint for storing attachments

  1. Log in to your Office 365 account.
  2. To launch the SharePoint application, select Applications > All apps > SharePoint.
  3. Do one of the following:
    • To create a new site, click + Create Site and then copy the site address. 
    • Select your existing site and copy the site URL. 
  4. To add attachments, create a new document library for your site and copy the URL as a relative URL. 

Task 2: To download and deploy the integration template project

  1. Download the  Publish ITSM Incident and Work-notes to a MS Teams channel 2022-03-01  file for the integration template.
  2. Log in to the MuleSoft Anypoint Platform and select Runtime Manager

  3. On the Applications tab, click Deploy application and select the .jar file that you downloaded.

  4. On the Runtime tab of the Deploy Application page, select the following values: 

    Field nameValue
    Application NameEnter a unique name for your application.
    Deployment TargetSelect the space for deploying the application, for example, CloudHub.
    Application FileSelect Choose File > Upload file, and select the Integration template .jar file.
    Runtime tab
    Runtime versionSelect the MuleSoft runtime version used to develop the application.
    Work 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:

    keyvalue
    Kafka Properties (Mandatory only if you are using Kafka)

    kafka.use

    To enable the Kafka queuing mechanism for incoming Webhook requests for fault tolerance, set the value to true.

    By default this value is set to false

    kafka.bootstrap.server

    Enter the Kafka server URL in the following format:
    <hostname>:<port>

    Important: If the Kafka messaging system is disabled, enter localhost:9092 in this key.

    Mulesoft API Webhook Properties

    api.integrations.name

    Enter the BMC Helix ITSM Webhook name after the BHIP_ prefix.
    api.integrations.profile.username

    Enter the user name for the Basic type of authentication to configure the Webhook.

    api.integrations.profile.passwordEnter the password for the user name entered.
    ITSM connector properties

    itsm.connector.protocol

    Enter HTTP or HTTPS.

    itsm.connector.url

    Enter the REST enabled, BMC Helix ITSM host URL; for example, https://<hostName>-rest.trybmc.com/rsso/launchpad/

    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 BMC Helix ITSM application for managing the incidents. Valid values include:

    • SmartIT
    • Midtier

    itsm.serverRoot.urlDepending on the itsm.application.type entered, enter the BMC Helix ITSM server URL.
    itsm.worknotes.viewaccess

    Enter the work note view access type for which updates should be posted on Microsoft Teams.

    Valid values include:

    • Public
    • Internal
    itsm.connector.port

    Enter the port number for the BMC Helix ITSM URL.

    The default value is 8080.

    itsm.helpdesk.qualifier

    Enter qualifiers to add conditions to the Webhook to define the filters for incidents for which messages should be posted; for example:

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

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

    itsm.worklog.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"

    BMC Helix Innovation Studio properties

    bhp.connector.username

    Enter the user ID to access BMC Helix Innovation Studio.

    bhp.connector.password

    Enter the password of the user to access BMC Helix Innovation Studio.
    Microsoft Teams properties

    teams.connector.channel

    Enter the ID of the Teams channel to post the updates.

    Important

    To get the channel ID, select the ellipses (...) next to the channel name, and select Get link to the channel. Copy the ID provided after /channel

    The team ID in the following channel link is 19%3a070cbdb5045a49d7b23955ce34c09161%40thread.skype:

    https://teams.microsoft.com/l/channel/19%3a070cbdb5045a49d7b23955ce34c09161%40thread.skype/General?groupId=c1db44f1-81b1-4acc-9caa-fab948bcf3d8&tenantId=92b796c5-5839-40a6-1fad320c69b, 

    teams.connector.teamId

    Enter the ID of the Team in the channel where updates are posted.

    Important

    To get the team ID, select the ellipses (...) next to the channel name, and select Get link to the team. Copy the ID provided after /team

    The team ID in the following team link is 19%3a070cbdb5045a49d7b23955ce34c09161%40thread.skype:

    https://teams.microsoft.com/l/team/19%3a070cbdb5045a49d7b23955ce34c09161%40thread.skype/conversations?groupId=c1d-81b1-4acc-9caa-fab948bcf3d8&tenantId=92b796c5-5839-40a6-8dd9-c1fad320c,

    Microsoft Teams OAuth connection configuration properties

    config.oauth.authorization.code.consumerKey

    Enter the Client ID of the Microsoft Teams application.

    This is the value of the OAuth consumerKey generated when you register your Microsoft Teams application with Microsoft Azure. 

    config.oauth.authorization.code.consumerSecret

    Enter the Client Secret for the Microsoft Teams application.

    This is the value of the OAuth consumerSecret generated when you register your Microsoft Teams application with Microsoft Azure. 

    config.oauth.authorization.code.authorizationUrl

    Enter the authorization endpoint URL in the following format: https://login.microsoftonline.com/<tenantID>/oauth2/v2.0/authorize

    where <tenantID> is the tenant ID for Azure Active Directory. For more information about locating the tenant ID, see How to find your Azure Active Directory tenant ID .

    config.oauth.authorization.code.accessTokenUrlEnter the accessToken endpoint URL of the service provider in the following format: https://login.microsoftonline.com/<tenantID>/oauth2/v2.0/token
    config.oauth.authorization.code.scope

    To provide offline OAuth access permission to Microsoft Graphs API during the OAuth authentication, enter offline_access https://graph.microsoft.com/.default

    For more information about permissions, see Microsoft Graph permissions reference in the Microsoft Graphs documentation.

    config.oauth.authorization.code.resourceOwnerId

    Enter the user ID of the user for whom you want to authorize access by using OAuth.
    Microsoft Teams OAuth connection callback configuration properties

    config.oauth.authorization.code.callbackPath

    Enter /callback.

    This takes the value of the Redirect URI defined in the Authentication page of your Microsoft Teams application, registered in the Microsoft Azure portal. This is the MuleSoft Microsoft Teams connector URL that receives the authorization code for the application in MuleSoft Anypoint Platform.

    config.oauth.authorization.code.authorizePath

    Enter /authorize.

    Enter the path of the local HTTP endpoint that triggers the OAuth authentication dance.

    config.oauth.authorization.code.externalCallbackUrl

    For a callback endpoint behind a proxy or a callback endpoint to be accessed through a non-direct URL, enter the URL to access the callback. This is the application URL from Anypoint platform.

    Add the URL to the Redirect URIs in the Microsoft Azure Authentication page of your Microsoft Teams application, registered in the Microsoft Azure portal.

    SharePoint Properties

    sharePoint.config.onlineUsername

    Enter the Microsoft account user name to access SharePoint.

    sharePoint.config.onlinePassword

    Enter the Microsoft account password to access SharePoint.

    sharePoint.config.siteUrl

    Enter the URL of your Microsoft SharePoint instance in the following format:

    [http/https]://[host name and port]; for example, https://myCompanyName.sharepoint.com

    sharePoint.connector.fileServerRelativeUrl

    Enter the URL of the document library you created for your Microsoft SharePoint site in Task 2.4; for example, https://MyCompanyName.sharepoint.com/sites/mySite/Shared%20Documents/Forms/AllItems.aspx

    MuleSoft API Webhook properties
    api.webhook.profile.typeEnter Basic.
  6. Optionally, if you want to enable email notifications, add the following values:

    Email notification configurations
    email.property.smtp
    Enter the SMTP host details for email configuration.
    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 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 Teams 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 Microsoft Teams
    ITSM-Purge-Integration_Manual Trigger
    Deletes the Webhooks created to enable creation of Teams 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 Microsoft Teams
  5. After you enable this integration, to authenticate the user in the Microsoft Teams application, enter the following URL in your browser, https://<applicationURL>/authorize?resourceOwnerId=<userName>.

After you enable the integration, a Microsoft Teams post is created for the incident that matches the itsm.helpdesk.qualifier criteria and for the work notes that match the itsm.worklog.qualifier criteria defined. 

Task 4: To use teams posts to update incident status and add comments to the incident

To update the incident status or add comments to an incident, you use the outgoing Webhook created for your Microsoft Teams channel. After you post the message, the system displays a success or failure notification.

Use the following commands by replying to a post or adding a new post to update the incident:

ActionPost
To view details for available actions.@<outgoingWebhookName> info
To add comments to a specific incident.@<outgoingWebhookName> <incidentNumber> AddNote: <comments>

To update the status of a specific incident. 

Important:

  • Add a valid ITSM incident status. 
  • Add a status reason when changing the status to Pending.
  • Add a resolution when changing the status to Closed or Resolved.

For more information about ITSM incident status, see Statuses for incidents in Changing ticket status in Smart IT for Smart IT.

@<outgoingWebhookName> <incidentNumber> Status:<validIncidentStatus> Reason:<validStatusReason> Resolution:<validStatusResolution>
Was this page helpful? Yes No Submitting... Thank you

Comments