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:
| NA |
Update the BMC Helix ITSM incident | NA | Updates the BMC Helix ITSM incident when:
|
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 |
|
---|---|
Authentication and permissions |
|
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. Important: |
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
- 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.
- Register the Microsoft Teams OAuth connection callback URL for the registered application.
- Log in to the Azure portal.
- Navigate to your registered application.
- Select Manage > Authentication.
- Under Redirect URI, add the callback URL for the application deployed in MuleSoft Anypoint platform in the following format:
https://<applicationURL>/callback
whereapplicationURL
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.authorizePath | Value for this variable is defined in project configuration variables defined in Task 2. |
config.oauth.authorization.code.resourceOwnerId | Value 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
- Log in to your Office 365 account.
- To launch the SharePoint application, select Applications > All apps > SharePoint.
- 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.
- 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
- Download the
Publish ITSM Incident and Work-notes to a MS Teams channel 2022-03-01
file for the integration template.
Log in to the MuleSoft Anypoint Platform and select Runtime Manager.
On the Applications tab, click Deploy application and select the .jar file that you downloaded.
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.
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.comsharePoint.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. 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.
- 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.
Log in to the MuleSoft Anypoint Platform and select Runtime Manager.
On the Applications tab, click the project name.
On the application details page, click Schedules.
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 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:
Action | Post |
---|---|
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:
For more information about ITSM incident status, see Statuses for incidents in
Changing ticket status in Smart IT
| @<outgoingWebhookName> <incidentNumber> Status:<validIncidentStatus> Reason:<validStatusReason> Resolution:<validStatusResolution> |
Comments
Log in or register to comment.