Workspace One Intelligence, Custom Connectors and Microsoft Teams
Creating a Custom Automation with WS1 Intelligence
Workspace One Intelligence has a number of pre-built integration options that you can take advantage of with a click through wizard process to enable them. This guide will focus on the integration of Workspace One Intelligence and another service via the custom connector functionality of the Intelligence tools. This example will focus on integration of Microsoft Teams as the service that we want to post notifictions of device enrollments to. This same process will allow us to integrate into any serivice - have fun!
Pre-reqs
Postman
Workspace one UEM
Workspace one Intelligence
Office 365 and Microsoft Teams
Create a new Microsoft Teams Channel
Login to Office365 in my case I am using the web apps for this work, so in your web browser head to portal.office.com and login.
From the left hand menu launch Teams
Inside of teams we are going to create a new channel for our UEM status updates to be posted for monitoring later on
In my case I begin by clicking the 3 dots next to the org group and select add channel
Fill out the channel details as necessary
In my example I am calling my Channel Workspace One Notifications
Give the channel a description - here I am noting mine as a place that Workspace One is sending notifications for monitoring
Now that we have our channel that we want to send the notifications to, we need to generate a webhook. The webhook is going to be the endpoint that Teams will be listening on for messages to post to it from our Intelligence automation engine.
Select the 3 dots next to your channel name
Select connectors
Select the incoming webhook connector
Give your connector a meaningful name and an icon. These will show in the message channel, so I am referring to the WS1-Intelligence service in the name and using the WS1 Hub icon.
Click create
After a moment the page will refresh and if you scroll down a webhook URL will be generated. Copy this to a notepad for later use.
Create a new Postman Collection
Our next action will be to setup a Postman collection. This Postman collection will contain the api actions we to send commands to the Teams webhook we just created. There are 2 possible status messages we can post into Teams, a simple message - think a basic text string, or a "card". The Card has a bit more formatting to it, things like a title, heading and message body. Our postman collection will ultimately allow us to post either type.
If you don’t already have Postman, head to https://www.postman.com/downloads/
It should autodetect your OS type and give you the right download for your machine
Download, install and launch
Inside postman our first step will be to create a new collection
This new collection will hold all our API calls. Once we have a working set of API calls, we will export the collection and import it into Intelligence.
Click new collection
Give the collection and name description
In the left-hand column of the postman window, you should see your new collection you just created
click the 3 dots and select the new request menu option
Give the new request a name and description and Save
this first request will be the plain text message that will be sent to our team’s channel
this will open a new request in the main postman window
change the request type from Get to POST
In the URL Request URL window paste the webhook URL we copied from our connector in teams in the previous step.
Select the Headers tab and define a new content-type header with the value of "application/json"
Select the body header and click the Raw data type enter someplace holder example text
{
"text": "Hello from Postman"
}
Hit the Send button
If it works you will see a simple response of "1" in the postman application
Click Save response, save as example and then hit the Save Example button again in the new tab that opens
Switch back to the Team Application and check your channel for the Hello from Postman message - and it’s there - great!
Now let’s create a request that send the Card formatted message in Teams
Microsoft Cards docs here - this explains the options and gives some example XML to use
In the left-hand column of the postman window click the 3 dots and select the new request menu option of your collection
Give the new request a name and description and Save. This second request will be the card message type that will be sent to our team’s channel.
In the URL Request URL window paste the webhook URL we copied from our connector in teams in the previous step.
As in the previous step select the Headers tab and define a new content-type header with the value of "application/json"
We will reference the Microsoft documents to see how the formatting of the API call needs to be completed. In our case we will create a card that contains some device information in key value pairs and a link to the UEM console to view the device record
Select the body header and click the Raw data type enter our XML for the Card formatted message.
We will use this code to create our card. This will give us 5 values we can dynamically update, as well as a URL that will update to link to the specific device in the UEM console.
{
"@context": "https://schema.org/extensions",
"@type": "MessageCard",
"title": "Card Title",
"summary": "Card summary",
"themeColor": "0072C6",
"sections": [
{
"text": "Card Text",
"facts": [
{
"name": "Item 1:",
"value": "Value 1"
},
{
"name": "Item 2:",
"value": "Value 2"
},
{
"name": "Item 3:",
"value": "Value 3"
},
{
"name": "Item 4:",
"value": "Value 4"
},
{
"name": "Item 5:",
"value": "Value 5"
}
]
}
],
"potentialAction": [
{
"@context": "http://schema.org",
"@type": "ViewAction",
"name": "View in UEM",
"target": [
"https://UEMConsole.awmdm.com/AirWatch/#/AirWatch/Device/Details/Summary/1234"
]
}
]
}
Hit the Send button
If it works you will see a simple response of "1" in the postman application
Click Save response, save as example and then hit the Save Examle button agian in the new tab that opens
switch back to teams to see the sample message posted - great!
Back in postman save both requests and lets export the requests for use in Workspace One Intelligence Custom connectors
Click the 3 dots next to your collection, hit the export option
select the current recommend format and save the JSON file
Create the custom connector in Workspace One Intelligence
Login to the UEM console and in the left-hand menu select the monitor pane and then Intelligence and launch
This will take you into the Intelligence console. From the main intelligence console, across the top select the Integrations menu, then workflow connectors and then Add a Custom connector
Give your connector a descriptive name, like Teams WS1 Channel integration and a description.
Set the base URL to https://outlook.office.com
The team’s connector does not require authentication in its current configuration so select the no authentication type.
and click save
in the custom connector now, we will import our postman collection by clicking the import actions button
select the postman collection we exported in the previous step
Once imported you will see the 2 actions shown in the Intelligence console - 1 for sending the simple message text and 1 for sending the card notification type
we can test each one again here to ensure that it works from the Workspace One Intelligence tool as expected
select the 3 vertical dots next the simple message and click test
Change our text from hello from postman to hello from intelligence and hit test
Check the team’s channel for the update that has the new text in it
next lets test the card notification
Close the test we just completed and click the 3 dots next the card message action
click test
when you see the successful response in the console switch back to teams to verify the card was posted
Great we have 2 message types being able to post into our teams channel from intelligence!
now lets create an automation action to post a notification every time a device is enrolled into UEM with some device details and a link to view the device
Creating the automation
After we have created our Custom connector and verified both actions work as expected
select automations across the top menu bar and click Add to generate a new workflow
There are a number of prebuilt workflows you can use as templates or wizards to configure and I encourage you to review those. In our case we will create our own by selecting the Devices: Create your own card.
Give your workflow a name and description
On the trigger we are going to set it to Automatic so that it will kick off every time a device matches the configured rules
In the filer section click the first box and a list of conditions will appear. you can type to search in this box, in our case search for and select enrollment status, and then leave the middle option as includes and set the final value to enrolled. This will allow us to capture all enrolled devices. And new devices as they enroll and get that status set will trigger a notification to the Teams channel.
In the actions section click the + button to add an action. Select the Teams Connecter we just configured and select the card notification. This will open the card so we can change the default values we configured in postman to something more meaningful. one of the best things about this is that we can use the lookup value functionality to create some really dynamic values links. In our example we will configure a card that shows some basic user and device info and has a link to the device in the UEM console so if someone wanted to review it more details there is a direct link to take them there.
We are going to change a few fields - Title, Card text, Items and Values 1 - 5, and the potential target URL
For the tile, I am going to title my cards in Teams as "Workspace One Notification"
For the Card text, "this is an automated notification that a device was enrolled into UEM"
For the Items and Values, I am going to change mine to include some user and device info
Item and Value 1 become - User : ${device_enrollment_user_name} respectively. for the values as mentioned we are using the lookup values
Item and Value 2 become: Device Org Group: ${device_location_group_name}
Item and Value 3 become: Device OS Version: ${device_os_version}
Item and Value 4 become: Device Model: ${device_model}
Item and Value 5 become: Status: ${device_enrollment_status}
potential target URL needs to be updated to be your Console URL and the end of the URL should be changed from 1234 to ${device_id}
so, for example it would be: https://cn1506.awmdm.com/AirWatch/#/AirWatch/Device/Details/Summary/${device_id}
With that configured when a device enrolls a message card will be posted to the Teams channel that notifies a new device enrollment has occurred, and who the user was, what org group did they just enroll to, the make and model of the device and a confirmation of the device enrollment status. It will also have a link that if clicked will launch the UEM console and load the device record.
scroll to the very bottom and click save
We are taken back to our automations home page - our automation is currently saved but disabled.
When we are ready to be activate it click the 3 dots and enable it. You have the option to do a 1-time manual run at activation or to just enable it for future devices. If you do the manual run it will process and send notifications for ALL devices that match the current filter - in this case a notification would be sent for ALL currently enrolled devices - I don’t want that, so I am just going to enable and not do the manual run.
The status changes to enabled on the automation connector.
Verify!
Now let’s enroll a test device and see our automation in action
Enroll an iOS device - I am assuming if you are this far in the doc you know how to enroll an iOS device - but here are the enrollment docs link if needed
Once our device is enrolled and we can see it in the uem console lets head back to the Intelligence admin console and check the activity status of our automation
On the Automation card, click the view link
This will load the automation, across the top select the activity tab to see the history of actions the automation has done
You should see an activity with a current time stamp
Now let’s check our Teams Channel for the card
In teams navigate to the channel we created to receive these messages and that we posted our test messages to earlier
and there it is! we received a notification of a device enrollment along with the device and user details, and if I click the link to UEM I am taken right to the device record for further review if necessary
