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:

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: 

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: 

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

   key	value
   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.password	Enter 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.url	Depending 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.accessTokenUrl	Enter 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.type	Enter 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: