POST Cherwell Data into Channels within Microsoft Teams
CSM/CAM Version : CSM 9.60

I've been asked a few times from our local user group to share some insight into how we post data from Cherwell into Channels within Microsoft Teams. Let's dive in...

Goal: Build a connector that will allow the posting of data from Cherwell into an ActionCard Message within an MS Teams Channel, resulting in a notification such as:

Requirements:

  1. User must have admin role for Microsoft Team, in order to be able to add the Incoming Webhook Connector.

Resources:

  1. Microsoft Article regarding crafting MS Teams Connector Messages.  Please review! This is my first interaction with the MS Teams actioncard API, and all information was sourced from this article.

https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/connectors/connectors-using

Steps:

1. Add the Webhook Connector to your Microsoft Teams Channel. Make sure you are in the desired channel within your desired team for which you want the messages to post to: 

2. Create the Webhook Uri for a specific channel and put it in a secret and safe place.

3. Confirm you can post to Teams channel via PowerShell (or Curl, refer to MS article). If Post fails, determine if the failure was with the powershell cmdlet or whether it was something else.  Check with your O365 tenant admin to see if there are any restrictions placed on this ability, as your organization may have locked things down in O365. If successful, go to #4.

Powershell Command:

Invoke-RestMethod -Method post -ContentType 'Application/Json' -Body '{"text":"Hello World!"}' -Uri <YOUR WEBHOOK Uri FROM THE SECRET AND SAFE PLACE>

4. Welcome to #4.  Before we can build the message body content, we need to add the Web Service into Cherwell.  Create a new Blueprint with a new Web Service from the Web Services Manager.  Several things to note:

  • Since I plan to use the same Web Service for different MS Teams/Channels, I truncated the URL to the parent domain. In doing so, I will need to ensure I populate the remaining half of the Uri into the Method’s EndPoint in the subsequent steps. Alternatively, you can paste the entire Uri into the URL field and just call it a day, but will you will need to create multiple Web Services for each Team/Channel you plan on posting to.
  • Service Type must be REST.
  • Your tenant may have different security settings for ‘Security Type’

5. Click on the Methods icon and add a new one. Give it a name. If you truncated your Uri in the previous step, then you will need to place the remaining part into the endpoint, otherwise leave it blank. Set your Result Type to JSON, and Request Type to POST.

6. Time to add the Parameters. If you recall from Step #3, we have the parameters “ContentType” and “Body”. Click the Add button and enter “ContentType” for the name, select TEXT for the data type, and set the Param to HEADER.

7. Click ADD again and create the parameter for the Body, as shown below. Ensure you have set the Param Type to Standard and checked “Is Content”.

8. Your WebService is now all set to go. Let’s work on the OneStep that will post the json payload.

9. Create a One Step and add the “Call A Web Service” advanced action. Give it a proper name and select the Web Service we created moments ago.

10. Click on Method. Select your Method from the pulldown list. Under parameters, you will see the ContentType and Body entries. For ContentType, set the value to application/json (note it is a forward slash and not a backslash).

11. For the Body Parameter, you need to craft a json payload with proper structure/properties. To save you time, here is my JSON that renders the actioncard as:

**See Code in Comment Thread**

A few things regarding my json file. First, I use a free online service, ui-avatars.com, for "images" as we cannot insert images that are stored in Cherwell into this json payload.  Second, I have highlighted in grey the fields that are pulled from the Change Record. Lastly, you can add more buttons, a comment field, etc...so refer to the article.

12. Run your onestep or trigger it via automated process. You should see the card get posted into the Teams Channel.  If not, it'll likely be the json file as it is quite delicate and needs some TLC.  Post your issues down below.

  • This is awesome! Thank you Elias. 

  • Some are having issues with the json formatting.  Hope this file will allow better copy/paste/download.

    example.json.txt
    {   "@type": "MessageCard",
        "@context": "http://schema.org/extensions",
        "themeColor": "0076D7",
        "summary": "Change Approved",
    	"title": "Approved",
    	"sections": [{
            "activityTitle": "ID #Title",
            "activitySubtitle": "Reason",
            "activityImage": "https://ui-avatars.com/api/?background=0D8ABC&color=fff&name=:P",
    		"facts": [{
                "name": "Type:",
                "value": "Type"
            }, {
                "name": "Implementer:",
                "value": "Implementer Name"
            }, {
                "name": "Proposed Start:",
                "value": "Proposed Start Date"
            }, {
                "name": "Description:",
                "value": "Description"
            }],
            "markdown": true
        }],
        "potentialAction": [{
            "@type": "ActionCard",
            "name": "Visit Record in Cherwell",
            "actions": [{
                "@type": "OpenUri",
                "name": "Go to Full Record",
                "targets": [{ "os": "default", "uri": "https://localhost" }]
        }]
        }]
    }