Using Custom Connectors in Intelligence Automations

Intelligence continues gaining new functionality with each release. Part of what enables new functionality is the capabilities added with each Intelligence Integration (ServiceNow, Splunk, etc.). These integrations, such as integrating Trust Network partners and Workspace ONE UEM, provide out-of-the-box triggers and actions to include in Automation. However, these integrations don't necessarily include the full gamut of APIs and potentially automated tasks. Administrators can easily add new functionality to Intelligence using Postman and the Workspace ONE UEM Rest API without waiting for new releases or built-in updates. In a sample I recently published to GitHub, I'm interacting with the MDM version one, Commands Version one REST API in order to issue a specific MDM command type: CustomMDMCommand. The CustomMDMCommand parameter provides a way to send any properly formatted MDM command directly to a device. Some examples of how admins might use this functionality include:

• Sending the RefreshCellularPlan to a Cellular-enabled iOS device upon enrollment to activate the eSIM
• Bulk sending the RecommendationCadence setting to Apple devices to control whether new major OS updates are shown or hidden.

Details on how to use the sample Postman collection in Workspace ONE Intelligence are included in the Readme. That said, I wrote this blog to give you a high-level understanding of how to get started with Postman and Custom Connectors.

Getting Ready to Integrate

To exercise Workspace ONE UEM API calls with Postman (and eventually Workspace ONE Intelligence), you'll need to get the following pre-requisites in order:

1. Ensure REST API Access is enabled and Add a new service at Settings > System > Advanced > API > REST API. Copy the API Key (later referred to as the aw-tenant-code) and the domain component of the REST API URL (in other words, the ####.awmdm.com URL without "https://" and "/API"). This domain component is referred to as the Base URL in later steps.
2. If using basic authentication, you'll need to create a new Admin account with permissions in an admin role appropriate to the actions you're attempting to automate.
3. Workspace ONE Intelligence licensed and integrated with your Workspace ONE UEM tenant via the opt-in process.
4. If you want a starting point, download the example Postman collection published at EUC-Samples.

NOTE: For brevity, I'll assume you know how to use Postman. If you don't, the Postman docs include an awesome tutorial into Postman basics and how to carry out specific tasks.

Modeling REST API Calls in Postman

The documentation for the Workspace ONE UEM REST APIs can be accessed at https://<API_Server>/api/help.   Within these docs, you'll see what APIs are available, what parameters to pass (in the query, headers, or body), and what the expected output should be. In the Postman collection on the EUC-Samples GitHub Repository, you can see I've included 5 separate API calls (all of which send a device a Custom MDM Command). As you start modeling how to interact with these APIs, it's crucial to keep the following in mind:

• Be mindful of the specified HTTP Verb (i.e., Post, Get, Update, and more). If you use the wrong one, you'll most likely see HTTP 404 responses.
• Make use of Environments in Postman to enable rapid testing or testing against different environments (or Base URLs) using different credentials or variable values. You can reference environment variables using the variable notation: {{variablename}}
• While variables (sourced from environments or Collections) are a great way to make Collections shareable, they may not upload properly to Intelligence. If the collection will be used as an import for Workspace ONE Intelligence Automation actions, hard code necessary values (such as the aw-tenant-code and Content-Type) in each API call.

As you start looking to model REST API calls in postman, there's a few basic items you need to make sure you've included in the API call in Postman:

1. The HTTP Verb – Post, Get, Update, etc.
2. The Base URL (such as https://as###.awmdm.com/api/) with the location of the API (such as /devices/commands). This gives you a starting point of https://as###.awmdm.com/api/devices/commands
3. A list of parameters (entered on the Params screen in Postman) as specified in the API documentation (see Figure 1).
4. The header key-value values, such as authorization, accept, aw-tenant-code, and content-type (see Figure 2).
5. The body, if required in the API documentation (see Figure 3).

Figure 1:  Postman Params screen

Figure 2:   Postman Headers Screen

Figure 3:   Postman Body Screen

Building Intelligence Automations from Postman Collections

Once you've gotten the Workspace ONE UEM Rest API working in Postman, you can begin setting up a Custom Connector and Automation to leverage the API. Much of how to do this is covered in the ReadMe file associated with the CustomMDMCommand sample, but I'll leave you with the following high-level guide:

1. Export the Postman Collection to a JSON file.
2. Build a Workspace ONE Intelligence Custom Connector (at Integrations > Workflow Connectors (view) > Add Custom Connector).
   
   1. If you opt to use Basic Authentication, the credentials you supply in the Custom Connector setup override the credentials supplied by your Postman collection.
   2. If your UEM is hosted in SaaS, you may opt to use oAuth rather than Basic Authentication, which also eliminates the need to supply the aw-tenant-code header in your Postman collection.
3. Build an Intelligence Automation that leverages the Custom Connector (and Actions created by importing your Postman collection).
   
   1. Constrain your target list of devices for initial test purposes
   1. Ensure the parameters are configured correctly in the Action.
   2. After successful testing, modify the Automation to scope in more devices.
   3. Be mindful of the behavior when saving and enabling. If you select to enable a One Time Manual Run, all devices known and not blocked by the filters will receive the Automation.
   4. If you see a 403 forbidden result containing a message that aw-tenant-code is missing, you need to add and save that header into your Postman collection before using it in your Custom Connector.

Wrapping Up

I've included more detail in the ReadMe file for the Custom MDM Commands sample on GitHub. Again, most of the Workspace ONE components have an API which can be used to automate tasks which aren't built-in from the start. I encourage you to explore the API, try new things in Postman, and feel free to contribute any Postman Collections you’ve created back to our GitHub repository to share with other EUC admins in the community!