Solution

  • Workspace ONE

Type

  • Document

Level

  • Intermediate

Category

  • Operational Tutorial

Product

  • Workspace ONE UEM

Phase

  • Manage

Automating Notifications: VMware Workspace ONE Operational Tutorial

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment.

A common challenge among distributed workforces is how to provide informational and actionable notifications to users, regardless of their location or available devices. Workspace ONE Notifications provide a flexible method for alerting and informing your users that can also integrate with your other business systems. You can build Workspace ONE Notifications using an administration console or REST APIs.

This tutorial details how to enable Workspace ONE Notifications and how to use the administration console and REST APIs to send a myriad of notification types to your users. 

Audience

This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Knowledge of interacting with REST APIs is a bonus but not required.

Prerequisites

Before you can perform the exercises in this tutorial, you must meet the following requirements.

  • An administrator account for Workspace ONE UEM 1810 and later. Workspace ONE UEM 1904 and later is required to support macOS.
  • An administrator account for a cloud-hosted (SaaS) Workspace ONE Access tenant. 
  • Access to a supported web browser:
    • Internet Explorer 11
    • Google Chrome 42.0 and later
    • Mozilla Firefox (latest version)
    • Safari 6.2.8 and later
    • Microsoft Edge (latest version)
  • Access to a supported enrolled device in your Workspace ONE UEM tenant:
    • iOS devices 9.0 and later
    • Android devices 4.4 and later
    • Windows 10 devices version 1709 and later
    • macOS devices 10.12 and later
  • Postman or your preferred API testing platform

For a full list of system requirements, see System Requirements for Cloud-Hosted Deployments with Hub Services.

Workspace ONE Hub Services Setup

Introduction

Workspace ONE Notification Services requires Workspace ONE Hub Services to be enabled for your Workspace ONE UEM organization group.

In this section, you will enable Hub Services from the Workspace ONE UEM admin console and then configure Hub Services for notifications.

Configuring Workspace ONE Hub Services

To get started, log in to your Workspace ONE UEM admin console.

1. Open Workspace ONE Hub Services

Enable Workspace ONE Hub Services in Workspace ONE UEM Admin Console
  1. Click the My Services button in the upper-right corner of the Workspace ONE UEM admin console.
  2. Click Workspace ONE Hub Services.

2. Get Started with Hub Services

Get Started with Workspace ONE Hub Services

Click Get Started.

3. Activate Hub Services

Hub Services is co-located with Workspace ONE Access, so you must provide your Workspace ONE Access tenant details to activate Hub Services.

Activate Workspace ONE Hub Services

If you do not have a Workspace ONE Access tenant, you can request a SaaS Workspace ONE Access tenant through this process.  On the Activate Hub Services screen, click Request Cloud Tenant and then return to this step after you have access to your SaaS Workspace ONE Access tenant.

  1. Enter your Workspace ONE Access Tenant URL.
  2. Enter the Username of an administrator account for your Workspace ONE Access tenant.
  3. Enter the Password of the provided administrator account for your Workspace ONE Access tenant.
  4. Click Test Connection and ensure a successful test connection message is displayed. If an error is shown, check your Tenant URL and confirm that the account credentials provided have administrator access to your Workspace ONE Access tenant.
  5. Click Save.

4. Launch Hub Services

  1. The dialog box confirms that Hub Services has been successfully activated with our Workspace ONE Access tenant.
  2. The Hub Services URL is co-located with your Workspace ONE Access tenant, so the Tenant URL entered in the previous step is displayed here.
  3. To start configuring Hub Services, click Launch.

5. Activate Hub Services Notifications

Activate Workspace ONE Notifications in Workspace ONE Hub Services console
  1. Click Notifications.
  2. Click Get Started.

6. Review Notification Settings

Click Settings to access Notification Settings from the Notifications page in Hub Services. These settings allow you to configure notifications, such as enabling or disabling notifications, choosing to send new app notifications to employees, or changing your default notification image.

 Feel free to explore the options available to you in the Settings menu and make any adjustments as desired before continuing.

Managing Notifications in Workspace ONE Hub Services

Introduction

You can create notifications from the Notifications page in Workspace ONE Hub Services. This feature allows administrators to create, preview, and send notifications to relevant users and devices.

In this section, you will create a custom notification and then, on an enrolled device, confirm that notification is received in the Workspace ONE Intelligent Hub app. 

Creating Notifications in Hub Services

1. Create Notification

Create custom Workspace ONE notifications in Workspace ONE Hub Services

To get started, navigate to the Notifications page (if not there already) and click Create Custom Notification.

2. Define Notifications

Define Workspace ONE Notifications in Workspace ONE Hub Services

There are three definitions required for each notification you create:

Name: Defines the friendly name of the notification. You can find your created notifications by name and click them to view their details later.

Target Audience Type: Defines who will receive this notification. There are four categories to select:

  • All Devices: The notification is sent to all managed devices. If a single user has multiple managed devices, they receive a notification on each device.
  • Organization Group: The notification is sent to all managed devices in a target organization group. If a single user has multiple managed devices in this organization group, they receive a notification on each device.
  • Smart Group: The notification is sent to all managed devices in a target smart group. If a single user has multiple managed devices in this smart group, they receive a notification on each device.
  • Platform: The notification is sent to all managed devices of the selected platform(s), which can be iOS, Android, Mac, and Windows. If a single user has multiple managed devices across the selected platforms, they receive a notification on each device.

Priority: Defines the importance and priority of the notification, which customizes some behavior and display properties of the notification.

  • Standard: Used for informational notifications such as approvals, maintenance notices, and organizational updates that do not require a timely response or any response at all.  
  • High-Priority: Is displayed at the top of the notification listings above Standard notifications. Used for time-sensitive notifications that require a timely response, such as a password expiring or important company notices.
  • Urgent: Is displayed as a notification card in Intelligent Hub that must be dismissed or interacted with before the user can continue interacting with the Intelligent Hub app. Used for extremely urgent notifications that alert users about important updates such as emergencies or actions that require immediate attention and/or response.

3. Create a Sample Standard Notification

Create Standard Workspace ONE Notification in Workspace ONE Hub Services

In this example, create a notification to deliver corporate updates to all devices. Because this is informational with no immediate response required, we use Standard as the priority.

  1. Enter a Name for the notification, such as Standard Sheets-Corp Update.
  2. Select All Devices as the Target Audience Type.
  3. Select Standard as the Priority.
  4. Click Next.

4. Create the Notification Content

Configure Notification content in Workspace ONE Hub Services

The Template allows you to choose between Actionable, which has prompts for user interaction, or Informational, which contains a message with no actionable prompts. In this example, create an Actionable notification that allows employees to navigate directly to the corporate website containing the latest changes.

  1. Select Actionable for the Template.
  2. Enter a Title, such as Corporate Website Updated.
  3. Enter a Description, such as The corporate website has been updated with the latest news. Check it out!.
  4. Your updates to the notification content appear on the preview card — this is how it will look to the end user.

5. Create the Notification Action

Notification actions allow your users to interact with your notifications by providing actionable buttons. You can include multiple buttons to open links, or even send API commands to other systems to accomplish automated tasks, such as confirming your availability for an event.  

In this example, configure a button that allows users to quickly view the updated corporate web page. Or they can dismiss the event without viewing the webpage.

Configure Notification Actions in Workspace ONE Hub Services
  1. Enter some Action Button Text, which is the label for your button. For example, Show Me!.
  2. Select Open In for the Action Button Behavior.
  3. Provide the Link to open. For example, https://www.vmware.com.
  4. Enable the Make Action Repeatable option. This allows the user to interact with the button multiple times if required. To perform the action only once, disable this.
  5. Optional - If additional actions are required, you can use the Add Action button.
Preview Notification Card in Workspace ONE Hub Services

Tip: You can check your preview at the top.

6. Optional - Add Attachments

Workspace ONE Hub Service - Google Chrome
  1. You can optionally include up to 10 attachments with your notification by clicking Add Attachment, but is not required in this example.
  2. Click Next.

7. Review and Create

Review Workspace ONE Notification in Workspace ONE Hub Services

The final preview of your notification is available here to confirm the notification card and settings. Review and then click Create.

Confirming Notifications in Hub Services

The created notification should now be sent to your targeted devices, which was all devices in this case. Check one of your enrolled devices that meets the criteria of your Notification audience to view the result.

NOTE: At the time of writing, the native Windows 10 Intelligent Hub app does not support receiving notifications.  If you are testing with a Windows 10 device, you will need to access Intelligent Hub via the web browser in order to interact with the For You tab seen in the following steps.

Confirm Workspace ONE Notification on device enrolled with Intelligent Hub app

Launch the Workspace ONE Intelligent Hub app on your targeted device.

  1. Tap For You to view notifications.
  2. Confirm that the actionable notification displays with your title, description, and actions. Tap Show Me! to open the action link.

The action link to open https://www.vmware.com was completed for the user.

2. View Notification History

View Notification History on enrolled device with Intelligent Hub app

To review past notifications, navigate to the History tab on the Intelligent Hub notifications page.

  1. Tap For You.
  2. Tap History.
  3. View the notification history.

Automating Workspace ONE Notifications

Introduction

You have seen how to create custom notifications through the Hub Services Notifications page, but how do you generate notifications programmatically or in response to other third-party system triggers? The Workspace ONE Notification REST APIs let you do just that.

This section walks through the setup and uses some REST APIs but here are some useful references for further reading:

Setting Up the Service Client Token in Workspace ONE Access

The first step in using the Workspace ONE Notification REST APIs is authentication. The Workspace ONE Notification REST APIs are provided through Workspace ONE Access, so you must set up a service client token which your service or app can exchange for an OAuth 2.0 access token to authorize REST API requests.  

The OAuth 2.0 client credentials authentication flow for Workspace ONE Access is as follows:

  1. Register your app as an OAuth client in Workspace ONE Access. This generates a client ID and a client secret.
  2. Your application sends the client ID and client secret to Workspace ONE Access.
  3. Workspace ONE Access returns an access token for your application to authorize REST API calls.
  4. When your access token expires, your app can refresh the access token or re-send the client ID and client secret to receive a new access token.

In this exercise, learn how to set up your OAuth client in Workspace ONE Access and properly authenticate.

1. Navigate to Workspace ONE Access Settings

Log in as an administrator to the Workspace ONE Access administration console and complete the following steps.

Settings in Workspace ONE Access Admin console
  1. Click the drop-down arrow by the Catalog tab.
  2. Click Settings.

2. Create OAuth Client

  1. Click Remote App Access.
  2. Click the Clients tab.
  3. Click Create Client.

3. Configure the OAuth Client

Configure the OAuth Client in Workspace ONE Access admin console
  1. Set the Access Type as a Service Client Token.
  2. Enter a Client ID. For OAuth2 clients, this name is usually an indicator to which app will be using this OAuth client. In this example, we use a generic name, such as WS1-Notification-Client.
    Important: You must use this client ID later when authenticating, so copy it to a secure location.
  3. Select the Advanced tab to show more details.
  4. Click Generate Shared Secret. This generates the client secret that the client requires to pass as part of the authentication process.
    Important: Copy the generated secret before the final step. After this page has been completed, you cannot go back and view the existing secret. You would have to generate a new secret instead, which invalidates any applications attempting to authenticate using the current client ID and client secret pair.
  5. Copy the generated secret to a secure location.
  6. If required, modify the access token, refresh token, and idle token Time-To-Live (TTL) values. The default values are generally recommended, but you can adjust them based on your security requirements. These values dictate how long the tokens remain valid.
  7. Click Add.

Your OAuth client is now created. You can test authentication using the Workspace ONE Notification REST APIs to confirm your OAuth client is set up correctly.

Configuring Postman

For this exercise, I used Postman and have provided a Postman collection for your convenience to easily interface with the Notification REST APIs.

Postman is a free API platform that allows you to easily test APIs and is available at https://www.postman.com. If you have another preferred API testing product, you can follow these steps with your preferred platform – Postman is not required.  

However, using Postman will streamline your testing process, as any REST API calls we mention going forward are included in the attached Postman collection. If you plan to use Postman, continue with the steps in this exercise. If not, continue to Retrieving an access token with the Notification REST APIs.

Postman Recommendations

The provided Postman collection uses variables with an environment to eliminate the need for copying and pasting your Workspace ONE UEM and Workspace ONE Access environment details between different REST API requests.

To begin, download the attached Postman Collection and Postman Environment files.

1. Import the Collection and Environment

  1. If not already installed, download and install Postman for free at https://www.postman.com.
  2. Launch the Postman app.

Click Import.

Select files to import to Postman
  1. Select the Import File tab.
  2. Either drag and drop or click Choose Files and select both the downloaded Postman Collection file (WS1 Notification APIs.postman_collection.json) and the Postman Environment file (Access - WS1 Notification REST API Environment Sample.postman_environment.json).

2. Select REST API Sample Environment

  1. Select the Collections tab.
  2. Ensure the WS1 Notification APIs folder imported. You can click the WS1 Notification APIs folder to expand it and see a list of all the REST APIs that have been provided with the collection.
  3. Click the Environment drop-down from the upper-right corner.
  4. Click the imported Access | WS1 Notification REST API Environment Sample environment.
  5. Click the Gear icon to edit the environment.

3. Edit REST API Sample Environment

Select environment in Postman

Click the imported Access | WS1 Notification REST API Environment Sample to edit the environment details.

4. Configure Environment Details

Configure Postman variables
  1. Environment Name: Optionally, edit your Environment Name to a more friendly name for clarity. For example, Access | My Access Environment.
  2. access_tenant_host: Enter your Workspace ONE Access tenant URL without the scheme, so do not include the preceding https://.
  3. client_id: Enter the Client ID that you configured in Workspace ONE Access in the Service Client Token Setup steps.
  4. client_secret: Enter the Shared Secret generated in the Workspace ONE Access in the Service Client Token Setup steps.
  5. access_token: Leave this blank; this is populated for you automatically when running the OAuth | Get Access Token request in Postman thanks to the "tests" feature.
  6. uem_tenant_host: Enter your Workspace ONE UEM tenant URL without the scheme, so do not include the preceding https://.
  7. uem_api_key: Enter the Workspace ONE UEM REST API key. Log in to the Workspace ONE UEM administration console, navigate to Groups & Settings > All Settings > System > Advanced > API > REST API, and copy the AirWatch API key.
  8. uem_admin_username: Enter the Workspace ONE UEM administrator username that has permission to authenticate the REST APIs.
  9. uem_admin_password: Enter the password for the above Workspace ONE UEM administrator account.
  10. Click Update.

The WS1 Notification APIs collection is now imported and your Environment is configured.

Saving your environment and access token details in your Postman environment will significantly reduce the amount of work required to run the Notification APIs.

5. Use Postman Requests

When you use the provided Postman Collection, you will generally follow these same steps each time to run a sample request:

  1. If collapsed, expand the imported WS1 Notification APIs folder.
  2. Click a saved request under the WS1 Notification APIs folder to open it. To test that the OAuth client id and client secret were setup correctly, click the Get Access Token request under the Authentication folder.
  3. If you haven't already done so, click the Environment drop-down and select the Postman Environment you imported and updated previously.
  4. You can inspect the method (GET, POST, and so on) and the URL of the request.
  5. You can inspect the parameters, authentication, headers, and body of the request. The other tabs are Postman settings, which are pre-request scripts, test scripts, and settings.
    Note: If you inspect the Tests tab, you can how we are using Javascript to save the returned access_token from this request to your environment variables for easy reuse. This prevents you from needing to copy and paste the access token to each of your requests you wish to test and run from Postman.
  6. Click Send when you are ready to test the API.
  7. After it has processed, you can view the body, cookies, headers, and test results of the request. In this example, the API was successfully completed (Status Code 200 OK) and you can see the JSON response below.

6. Review Postman Variables

All Postman variables are notated by the {{variable_name}} syntax. When you click Send for a request with variables, the value of the variable defined by your Postman Environment is replaced automatically for you, increasing the ease of reusing a shared Postman collection for you or your team.

  1. Open a request from the WS1 Notification APIs collection, such as the Get Access Token under the Authentication folder.
  2. Hover your mouse over the {{access_tenant_host}} variable in the request URL.
  3. The access_tenant_host value is found from your environment and displays the value that will be substituted into your request when you click Send.
  4. Select the intended Postman Environment for your requests. You can have multiple environments to easily switch between multiple configurations if desired.

REST APIs - Sending Single-User Notifications

With your OAuth client ID and client secret in hand, you are ready to start testing some Workspace ONE Notification REST APIs. First, you must retrieve an OAuth access token to authorize your REST API requests.

1. Retrieve an Access Token

In OAuth 2.0, an access token authorizes a client to make requests to a service based on the scope that was provided to the client. In our case, the service client token was generated as a scope of admin, meaning all methods will be available to our client.

To retrieve an access token, you must send a POST request to the OAuth token endpoint as follows:

Postman Request: Authentication > Get Access Token

Request:

POST | https://{YOUR_ACCESS_TENANT_URL}/SAAS/auth/oauthtoken

Headers:

Key Value
Authorization Basic Authorization string in format Basic abcd...wxyz where the abcd...wxyz string is replaced by a Base 64 encoded string in format: CLIENT_ID:CLIENT_SECRET.
Note: Provide a Base 64 encoded string that combines the Client ID and Client Secret values together separate by a colon (:) character. In pseudocode, this would be: Base64.encode(client_id:client_secret).

Body:

Format: x-www-form-urlencoded

Key Value
grant_type client_credentials

Successful Response:

Status Code: 200 OK

{
    "scope": "admin",
    "access_token": "eyJ0eXA........WEMmXE",
    "token_type": "Bearer",
    "expires_in": 10799,
    "refresh_token": "YjBlY2Q.........NDM1NA"
}

The following properties are returned from the successful /SAAS/auth/oauthtoken request:

  • scope: The set of permissions that are available to this client. You define the scope in the OAuth client that you created in Workspace ONE Access. In this example, the scope is set to admin.
  • access_token: This is the access token that your client must provide in future requests in the Authorization header to prove it is authorized to make protected REST API requests.
  • token_type: This is the type of access token that is returned. For simplicity, this token_type (Bearer) is used together with the access token in the Authorization header to signify the type of access token. There can be multiple access token types in OAuth 2.0. Bearer is the most common.
  • expires_in: How long the access token is valid for, notated in seconds. This value is defined in the OAuth client you created in Workspace ONE Access and is set by the Token TTL field.
  • refresh_token: A refresh token can be provided to retrieve a new Bearer access token after the expires_in time has passed.

Note and save the token_type (Bearer) and the access_token fields as you require them to authorize upcoming REST API requests.

Note: If you are using the provided Postman Collection, the Get Access Token request will automatically populate the access_token variable for future requests thanks to the "tests" and environment features in Postman.

1.1. 401 Unauthorized

If you receive a 401 Unauthorized response, double-check that you have:

  1. Provided the correct client ID and client secret in the expected Base64 encoded format for the authorization header. The correct format is Base64 encode the combined client ID and client secret values separated by a colon (:) character. In pseudocode: Base64.Encode(client_id:client_secret).
  2. Set up your post body correctly. The body format is x-www-form-urlencoded with the key set to grant_type and the value set to client_credentials.

2. Find User and Device UDIDs

If you inspect the Notification API reference, you can see that creating notifications requires one of the following identifiers:

  • User UUID: The universally unique identifier of the user account that should receive the notification.
  • Device UDID: The universally unique identifier of the device that should receive the notification.

Creating a notification for a User posts a notification to each device that the target user has enrolled. Creating a notification for a Device posts a notification directly to a device, regardless of the user that has the device enrolled.

With this in mind, the next section reviews how to retrieve these values to build a notification request.

2.1. Find User UUIDs: Determine Authentication Source

With Workspace ONE, you must use either the Workspace ONE UEM or Workspace ONE Access REST APIs depending on the Source of Authentication for Intelligent Hub setting you have configured.

Groups and Settings in Workspace ONE UEM administration console

First, log in to the Workspace ONE UEM admin console.

  1. Click Groups & Settings.
  2. Click All Settings.
  1. Click Devices & Users.
  2. Click General.
  3. Click Enrollment.
  4. Scroll down to find the Source of Authentication for Intelligent Hub settings.
  5. Confirm if your Source of Authentication for Intelligent Hub is set to Workspace ONE UEM or Workspace ONE Access.
    If Workspace ONE UEM is selected: Use the Workspace ONE UEM REST APIs to locate your User UUIDs.
    If Workspace ONE Access is selected: Use the Workspace ONE Access REST APIs to locate your User UUIDs.
  6. Click Close.

2.2. Find User UUIDs: Workspace ONE Access

If your Source of Authentication for Intelligent Hub setting is set to Workspace ONE Access, use the Workspace ONE Access REST APIs to locate your User UUIDs.

Postman Requests:

  • Query Users and Devices > Access | Find User IDs (All Users)
  • Query Users and Devices > Access | Find User IDs (Filtered)

Requests:

  • GET | https://{{YOUR_ACCESS_TENANT_URL}}/SAAS/jersey/manager/api/scim/Users
  • GET | https://{{YOUR_ACCESS_TENANT_URL}}/SAAS/jersey/manager/api/scim/Users?filter=userName eq "{USERNAME}"

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.

Successful Response:

Status Code 200 OK

{
    "totalResults": 1,
    "itemsPerPage": 1,
    "startIndex": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0",
        "urn:scim:schemas:extension:workspace:1.0",
        "urn:scim:schemas:extension:enterprise:1.0",
        "urn:scim:schemas:extension:workspace:mfa:1.0"
    ],
    "Resources": [
        {
            "externalId": "148cbe6d-2ad8-4d4a-8c85-582163d5dc1e",
            "active": true,
            "userName": "johnsmith",
            "id": "25940adf-8140-4f85-a792-9a61ed26a7e7",
            "meta": {
                "created": "2020-04-28T18:01:54.842Z",
                "lastModified": "2020-04-29T12:37:07.902Z",
                "location": "https://sheetscorp.vidmpreview.com/SAAS/jersey/manager/api/scim/Users/25940adf-8140-4f85-a792-9a61ed26a7e7",
                "version": "W/\"1588163827902\""
            },
            "name": {
                "givenName": "John",
                "familyName": "Smith"
            },
            "emails": [
                {
                    "value": "johnsmith@sheets.corp"
                }
            ],
            "phoneNumbers": [
                {
                    "value": ""
                }
            ],
            "groups": [
                {
                    "value": "6cb9d301-278e-42a3-8945-0553c1df1f2e",
                    "type": "direct",
                    "display": "ALL USERS"
                },
                {
                    "value": "42101771-6cbb-45db-a224-8adf81faf6c8",
                    "display": "Users@sheets.corp"
                }
            ],
            "roles": [
                {
                    "value": "53bb48ee-43b1-49b1-9be9-047ac4300250",
                    "display": "User"
                }
            ],
            "urn:scim:schemas:extension:workspace:1.0": {
                "internalUserType": "PROVISIONED",
                "distinguishedName": "CN=John Smith,CN=Users,DC=sheets,DC=corp",
                "userStatus": "1",
                "domain": "sheets.corp",
                "userStoreUuid": "a02791df-2f05-40c2-968f-0dee167cd993",
                "externalUserDisabled": false,
                "userPrincipalName": "johnsmith@sheets.corp"
            }
        }
    ]
}

In the previous example, we updated the request URL to filter on a user in the organization that we want to send a request to, which is johnsmith: https://{{YOUR_ACCESS_TENANT_URL}}/SAAS/jersey/manager/api/scim/Users?filter=userName= eq "johnsmith"

We did this to limit the number of items in the Resources array in the response. The User UUID can be found by locating the id property for a given user in the Resources array. In this example, we locate the id property for johnsmith, which is:

"id": "25940adf-8140-4f85-a792-9a61ed26a7e7"

So the User UUID for the user johnsmith is 25940adf-8140-4f85-a792-9a61ed26a7e7.  Find a User UUID to test in your environment and copy this value to a secure location for use in upcoming steps to send a notification to a user.

2.2.1. Additional References

There are many filter and search options available in the Workspace ONE Access REST APIs which are outside the scope of this tutorial. For a full API Reference, see the Workspace ONE Access API Reference.

2.3. Find User UUIDs: Workspace ONE UEM

If your Source of Authentication for Intelligent Hub setting is set to Workspace ONE UEM, use the Workspace ONE UEM REST APIs to locate your User UUIDs.

Postman Requests:

  • Query Users and Devices > UEM | Find User IDs (All Users)
  • Query Users and Devices > UEM | Find User IDs (Filtered)

Requests:

  • GET | https://{{YOUR_UEM_TENANT_HOST}}/api/system/users/search
  • GET | https://{{YOUR_UEM_TENANT_HOST}}/api/system/users/search?username={USERNAME}

Headers:

Key Value
Authorization Basic Authorization string in format Basic abcd...wxyz where the abcd...wxyz string is replaced by a Base 64 encoded string in format: UEM_ADMIN_USERNAME:UEM_ADMIN_PASSWORD.
Note: Provide a Base 64 encoded string that combines the Workspace ONE UEM administrator username and administrator password together separate by a colon (:) character. In pseudocode, this would be: Base64.encode(uem_admin_username:uem_admin_password).
aw-tenant-code Enter the REST API key obtained from Workspace ONE UEM.

This key is located in the Workspace ONE UEM administration console. Navigate to: Groups & Settings > All Settings > System > Advanced > API > REST API and copy the AirWatch API token.
Content-Type application/json or application/xml

Successful Response:

Status Code 200 OK

{
    "Users": [
        {
            "UserName": "johnsmith",
            "FirstName": "John",
            "LastName": "Smith",
            "Status": true,
            "Email": "johnsmith@sheets.corp",
            "SecurityType": 1,
            "ContactNumber": "",
            "MobileNumber": "",
            "MessageType": -1,
            "EmailUserName": "",
            "Group": "Sheets Corp",
            "LocationGroupId": "1591",
            "OrganizationGroupUuid": "8d3a2c0b-a8ba-4a81-9f62-566af4d2ceee",
            "Role": "Full Access",
            "EnrolledDevicesCount": "1",
            "CustomAttribute1": "",
            "CustomAttribute2": "",
            "CustomAttribute3": "",
            "CustomAttribute4": "",
            "CustomAttribute5": "",
            "ExternalId": "148cbe6d-2ad8-4d4a-8c85-582163d5dc1e",
            "StagingMode": 0,
            "DeviceStagingEnabled": false,
            "Id": {
                "Value": 1566
            },
            "Uuid": "41dc0ad8-e284-4a32-89fd-0cc1026b1a4b"
        }
    ],
    "Page": 0,
    "PageSize": 500,
    "Total": 1
}

In the previous example, we updated the request URL to filter on a user in the organization that we want to send a request to, which is johnsmith: https://{{YOUR_UEM_TENANT_URL}}/api/system/users/search?username=johnsmith.

We did this to limit the number of items in the Users array in the response. The User UUID can be found by locating the Uuid property for a given user in the Users array.  In this example, we locate the Uuid property for johnsmith, which is:

"Uuid": "41dc0ad8-e284-4a32-89fd-0cc1026b1a4b"

So the User UUID for the johnsmith user in UEM is 41dc0ad8-e284-4a32-89fd-0cc1026b1a4b. Find a User UUID to test in your environment and copy this value to a secure location for use in upcoming steps to send a notification to a user.

2.3.1. Additional References

There are many filter and search options available in the Workspace ONE UEM REST APIs which are outside the scope of this tutorial. For a full API Reference, see the REST API Help page available for your Workspace ONE UEM tenant, which is available at: https://{{YOUR_UEM_TENANT_URL}}/api/help. Specifically, check out the System REST API references for the endpoint we used (/api/system/users/search).

2.4. Find Device UDIDs: Workspace ONE UEM

Unlike finding User UUIDs, device UDIDs are only available through the Workspace ONE UEM REST APIs because UEM is responsible for managing your devices and their configurations.

Postman Requests:

  • Query Users and Devices > UEM | Find Device IDs (All Devices)
  • Query Users and Devices > UEM | Find Device IDs (Filtered by User)

Requests:

  • GET | https://{{uem_tenant_host}}/api/mdm/devices/search
  • GET | https://{{uem_tenant_host}}/api/mdm/devices/search?user={USERNAME}

Headers:

Key Value
Authorization Basic Authorization string in format Basic abcd...wxyz where the abcd...wxyz string is replaced by a Base 64 encoded string in format: UEM_ADMIN_USERNAME:UEM_ADMIN_PASSWORD.
Note: Provide a Base 64 encoded string that combines the Workspace ONE UEM administrator username and administrator password together separate by a colon (:) character. In pseudocode, this would be: Base64.encode(uem_admin_username:uem_admin_password).
aw-tenant-code Enter the REST API key obtained from Workspace ONE UEM.

This can be obtained from the Workspace ONE UEM administration console by navigating to: Groups & Settings > All Settings > System > Advanced > API > REST API and copying the AirWatch API token.
Content-Type application/json or application/xml

Successful Response:

Status Code 200 OK

{
    "Devices": [
        {
            "Udid": "8d6b19ec60227b86f09f733746d188a350224b5e",
            "SerialNumber": "##########",
            "MacAddress": "###########",
            "Imei": "#############",
            "EasId": "",
            "AssetNumber": "8d6b19ec60227b86f09f733746d188a350224b5e",
            "DeviceFriendlyName": "johnsmith iPad iOS 12.4.5 FLMJ",
            "LocationGroupId": {
                "Id": {
                    "Value": 1591
                },
                "Name": "Sheets Corp",
                "Uuid": "8d3a2c0b-a8ba-4a81-9f62-566af4d2ceee"
            },
            "LocationGroupName": "Sheets Corp",
            "UserId": {
                "Id": {
                    "Value": 1566
                },
                "Name": "John Smith",
                "Uuid": "41dc0ad8-e284-4a32-89fd-0cc1026b1a4b"
            },
            "UserName": "johnsmith",
            "DataProtectionStatus": 0,
            "UserEmailAddress": "johnsmith@sheets.corp",
            "Ownership": "C",
            "PlatformId": {
                "Id": {
                    "Value": 2
                },
                "Name": "Apple"
            },
            "Platform": "Apple",
            "ModelId": {
                "Id": {
                    "Value": 2
                },
                "Name": "iPad Mini with Retina LTE (16 GB Space Gray)"
            },
            "Model": "iPad Mini with Retina LTE (16 GB Space Gray)",
            "OperatingSystem": "12.4.5",
            "Id": {
                "Value": 952
            },
            "Uuid": "484553a3-3390-4ad7-8a03-07baa183f836"
        }
    ],
    "Page": 0,
    "PageSize": 500,
    "Total": 1
}

In the previous example, we updated my request URL to filter on a user in the organization that we want to send a request to, which is johnsmith: https://{{YOUR_UEM_TENANT_URL}}/api/mdm/devices/search?user=johnsmith.

We did this to limit the number of items in the Devices array in the response. The device UDID can be found by locating the Udid property for a given device in the Devices array. In this example, we locate the Udid property for johnsmith's iPad mini device, which is:

"Udid": "8d6b19ec60227b86f09f733746d188a350224b5e"

So the device UDID for johnsmith's iPad mini device is 8d6b19ec60227b86f09f733746d188a350224b5e. Targeting device UDID's when sending notifications is optional and allows you to send the notification to a single enrolled device that a user has rather than all of the enrolled devices that the user has. This can be useful if you want to send a device-specific notification, such as having your user download an iOS app, and don't want to confuse the user by sending the notification to a non-iOS device that cannot install the iOS app.

In this exercise, we focus on sending notifications to users but will have some examples of sending notifications to a specific device of a user if you are interested in this feature. If you want to test sending notifications to a specific device later on, save a device UDID you can use.

3. Send a Simple Notification Card

There are several methods for distributing notifications to your users and devices and several customization options for building your notification cards. This section shows how the REST API post body matches up with the Custom Notification view from earlier in the Workspace ONE Hub Services page.

For this example, create a simple notification card with the following characteristics:

  • The notification is sent to johnsmith user's UUID (which is 25940adf-8140-4f85-a792-9a61ed26a7e7).
  • The notification is sent to every device enrolled to johnsmith because you specified a user UUID and not a device UDID.
  • The notification card is informational with no prompts and contains a title, description, and an optional subtitle.

Postman Collection Request: Notifications > Send Single-User Notifications > Users > Send Standard Notification to User
Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/notifications
Request: POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"header": {
		"title": "REQUIRED: Notification Title Here",
		"subtitle": ["OPTIONAL: Subtitle Here"]
	},
	"body": {
		"description": "REQUIRED: Notification description here"
	}
}

The post JSON body is made up of the Header object and the Body object. The Header object contains a title string property and an optional subtitle string array property. The Body object contains a description string property.

These properties directly correlate to the Title, Subtitle, and Description fields in the Workspace ONE Hub Services custom notification builder.

Successful Response:

Status Code 200 OK

{ "created_at": "2020-04-29T17:21:50.365Z", "updated_at": "2020-04-29T17:21:50.365Z", "id": "8d0f02dd-74fe-4249-a901-40cf45df4bc3", "tenant_id": "sheetscorp", "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7", "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b", "device_id": null, "batch_id": null, "read_at": null, "last_action_id": null, "notification_card": { "header": { "title": "REQUIRED: Notification Title Here", "subtitle": [ "OPTIONAL: Subtitle Here" ] }, "body": { "description": "REQUIRED: Notification description here" } } }

After sending the request, you receive a response with the details of the notification. Some important fields to note are:

  • id: This is the notification id, which can be used with other API requests to get the notification details, update the notification, or delete the notification.
  • read_at: Updates with a timestamp for when your user read the notification.
  • last_action_id: If you send a notification with a prompt, this contains the id of which button prompt was performed by the user. (We will review this in a later exercise.)

If you have not already done so, send your request and then check your device to see if you received the notification.

  1. John Smith's iPad mini received an Apple push notification for the Workspace ONE notification card.
  2. John Smith then taps the Hub app to view the notification card details.
  1. John Smith taps the For You section in the Intelligent Hub app to view notifications.
  2. This notification card is based on the specifications of the JSON post body.

4. Send High-Priority and Urgent Notifications

In addition to the standard priority notifications, you can also send high-priority and urgent notifications to your end users.

High-priority notifications have the following characteristics:

  • High-Priority notifications are put in a Priority section of the For You section of the Intelligent Hub app which displays above all other notifications.
  • High-Priority notifications do not reduce the notification count for the Intelligent Hub app or in the For You section of the Intelligent Hub app until the user manually marks the notification as read or manually dismisses the notification.
  • If the user has the Intelligent Hub app opened when a priority notification is sent to them, a dialog box at the bottom of the screen alerts the user to the newly received notification.

Urgent Notifications have the following characteristics:

  • Urgent notifications are put in a Priority section of the For You section of the Intelligent Hub app which displays above all other notifications.
  • Urgent notifications do not reduce the notification count for the Intelligent Hub app or in the For You section of the Intelligent Hub app until the user manually marks the notification as read or manually dismisses the notification.
  • Urgent notifications take complete control of the Intelligent Hub app and the user cannot proceed past the notification prompt until they manually click mark as read.

So, how do you send these high-priority and urgent notifications with the REST APIs? You must include one additional property for your notification card JSON post body, which is the importance field. The importance field accepts an integer value that notates the following:

  • 0: Urgent
  • 1: High-priority
  • 2: Standard

If the importance field is omitted, the notification defaults to a Standard notification as seen in the previous simple notification example.

To send an Urgent Notification:

{
	"importance": 0,
	"header": {
		"title": "Alert - Tornado Warning"
	},
	"body": {
		"description": "A tornado warning is in effect near you, please head to the nearest designated shelter zone."
	}
}

To send a High-Priority Notification:

{
	"importance": 1,
	"header": {
		"title": "Alert - Tornado Warning"
	},
	"body": {
		"description": "A tornado warning is in effect near you, please head to the nearest designated shelter zone."
	}
}

Based on the information so far, follow the next steps to resend a new Urgent notification to John Smith.

Postman Collection Request:

  • Notifications > Send Single-User Notifications > Users > Send High-Priority Notification to User
  • Notifications > Send Single-User Notifications > Users > Send Urgent Notification to User

Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/notifications 
Request: POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"importance": 0,
	"header": {
		"title": "Alert - Tornado Warning"
	},
	"body": {
		"description": "A tornado warning is in effect near you, please head to the nearest designated shelter zone."
	}
}

The importance field relates to the Priority seen in the Hub Services Notifications UI.

Successful Response:

Status Code 200 OK

{ "created_at": "2020-05-01T12:30:24.550Z", "updated_at": "2020-05-01T12:30:24.550Z", "id": "c09a1e9c-174a-4632-8c7c-3a231d0f6bd9", "tenant_id": "sheetscorp", "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7", "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b", "device_id": null, "batch_id": null, "read_at": null, "last_action_id": null, "notification_card": { "importance": 0, "header": { "title": "Alert - Tornado Warning" }, "body": { "description": "A tornado warning is in effect near you, please head to the nearest designated shelter zone." } } }

John Smith received the urgent notification which required interaction before he could dismiss the notification and continue working in the Intelligent Hub app. Consider how to best leverage these notification priority levels to categorize how urgent your notifications are for your users.

5. Send a Simple Notification Card to a Device

The previous examples sent a notification to every device that the user has enrolled. There might be scenarios where you want to send a notification to a single device for a user rather than all devices for that user. Consider a case where you want to send platform-specific instructions to a user via a notification. To avoid confusion for your user, you may decide to send this notification only to the device platform that the instructions are relevant to.

In this example, create a simple notification card with the following characteristics:

  • The notification is sent to johnsmith user's UUID (which is 25940adf-8140-4f85-a792-9a61ed26a7e7).
  • The notification includes johnsmith's iPad device UDID (which is 8d6b19ec60227b86f09f733746d188a350224b5e) because we want this notification to be received only on this specific device.  
  • The notification card is informational with no prompts, and contains a title, description, and an optional subtitle.

Postman Collection Request: Notifications > Send Single-User Notifications > Devices > Send Standard Notification to Device
Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/devices/{TARGET_DEVICE_UDID}/notifications
Request:
POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/devices/8d6b19ec60227b86f09f733746d188a350224b5e/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"header": {
		"title": "REQUIRED: Notification Title Here",
		"subtitle": ["OPTIONAL: Subtitle Here"]
	},
	"body": {
		"description": "REQUIRED: Notification description here"
	}
}

The response details are identical to our previous examples of sending notifications to a user UUID, so we will not review those details again. After you send the notification, only the device specified by the device UDID in your request received the notification.  

REST APIs - Sending Multi-User Notifications

The previous exercise demonstrated how to send a notification to a specific user, but what if you have a group of users and/or devices that should all receive the same notification, such as a company-wide announcement or an update to an entire team?

In this activity, learn how to send notifications to multiple users.

1. Send Notifications to Multiple Users

There are two requests that allow us to send the same notification to multiple recipients:

  • https://{{YOUR_ACCESS_TENANT_HOST}}/ws1notifications/api/v2/distributed_notifications
  • https://{{YOUR_ACCESS_TENANT_HOST}}/ws1notifications/api/v2/distributed_notifications_async

There are two primary distinctions between these available options:

  • When sending notifications to 100 recipients or less, you can use the /distributed_notifications endpoint. This synchronously sends the notification to all recipients.
  • When sending notifications to more than 100 recipients, it is recommended to use /distributed_notifications_async instead. This asynchronously creates and sends the notifications to all recipients as quickly as possible.

The request post body is the same between both endpoints, so you only need to change the request URL between using the /distributed_notifications and /distributed_notifications_async depending on whether you are targeting less than or more than 100 users respectively.

Example:

This example uses two user UUIDs to send a notification to each user simultaneously:

  • Jane Doe: 22056712-5e3c-40dc-9190-4bfecd9b0c57
  • John Smith: 25940adf-8140-4f85-a792-9a61ed26a7e7

If you do not have two user UUIDs for your test, you can use the existing user UUID from previous requests and modify the upcoming post body to only include a single user UUID record. Follow the next steps to send a notification to John and Jane.

Postman Collection Requests:

  • Notifications > Send Multi-User Notifications > Send Notification to 1-100 Users (Synchronous)
  • Notifications > Send Multi-User Notifications > Send Notification to 100+ Users (Asynchronous)

Request Formats: 

  • POST | https://{{access_tenant_host}}/ws1notifications/api/v2/distributed_notifications
  • POST | https://{{access_tenant_host}}/ws1notifications/api/v2/distributed_notifications_async

Requests:

  • POST | https://{{access_tenant_host}}/ws1notifications/api/v2/distributed_notifications
  • POST | https://{{access_tenant_host}}/ws1notifications/api/v2/distributed_notifications_async

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"notification_card": {
		"importance": 2, 
		"header": {
			"title": "REQUIRED: Notification Title Here",
			"subtitle": ["OPTIONAL: Subtitle Here"]
		},
		"body": {
			"description": "REQUIRED: Notification description here"
		}
	},
	"recipients": [
		"22056712-5e3c-40dc-9190-4bfecd9b0c57",
		"25940adf-8140-4f85-a792-9a61ed26a7e7"
	]
}

The first important note about the request post body is that the notification card details are now moved under the notification_card object. The following screenshot depicts the previous notification request to 1 user and this notification request for multiple users.

You can reuse your same notification card properties for single and multi-user notifications but the multi-user notifications require these details to be included as part of the notification_card object.

The second important note about the request post body is to understand the recipients formats that can be provided to target users and devices.

There are three formats for supplying a target for the notification:

  1. "{USER_UUID}": Supply the User UUID as a string. This sends the notification to every device registered to this user account.
  2. { "user_id": "{USER_UUID}" }: Supply an object with the key "user_id" and the target User UUID as a string. This result is the same as option 1, the notification sends to every device registered to this user account.
  3. { "user_id": "{USER_UUID}", "device_id": "{DEVICE_UDID}" }: Same as option 2, except you also supply the "device_id" key with the target Device UDID as a string. This sends a notification only to the target device of the supplied user, meaning the notification does not arrive on all of their devices as seen in options 1 and 2. If Jane has two devices and a device_id is specified, only the target device specified by the device UDID will receive the push notification instead of all of Jane's devices.

For this example, we use option 1 to provide the user UUIDs for Jane and John respectively as an array of user UUID strings because we want the notification to be delivered to all of their devices.

Successful Response:

Status Code 200 OK

{ "created_at": "2020-05-19T17:53:57.457Z", "updated_at": "2020-05-19T17:53:58.010Z", "id": "70e0b866-b476-4ac3-bdac-9812936107af", "tenant_id": "sheetscorp", "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b", "success_count": 2, "failure_count": 0, "results": "[{\"user_id\":\"22056712-5e3c-40dc-9190-4bfecd9b0c57\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"9326838f-7d05-48b6-8c9e-be20bd2029c2\"},{\"user_id\":\"25940adf-8140-4f85-a792-9a61ed26a7e7\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"3a922842-c9d1-4b2f-a806-ebc7a7a44db5\"}]", "total_recipients_count": 2, "batch_completed": true, "actioned_count": 0 }

Another important differentiation between the single and multi-user notification is that the response for your multi-user notification returns information about the batch of notifications that was sent. Important values to note here are:

  • id: This is the id of the batch of notifications that was created. You need this id to query the details about your batch of notifications if you want to monitor the progress of the batch, especially for notifications with hundreds or thousands of recipients.
  • results: A JSON object which details which users and devices (if provided) have received the notification and if the notification to that user and/or device was successful. You can also choose to query the notification_id of the user and/or device in question to see the details of only that notification.
  • total_recipients_count: The total number of users that this notification was sent to.
  • batch_completed: A boolean that indicates if the batch has finished (true) or if the batch is still completing (false).

As a result, both Jane and John received a notification on their registered devices. When sending notifications to multiple users, use the /v2/distributed_notifications_async endpoint when targeting 100 or more users, otherwise, the two methods function identically.

REST APIs - Building Notification Actions

You have now generated notifications for a single user and multiple users, but so far our notifications have been informational and have not allowed our users to take any meaningful action other than to mark them as read.

In this activity, create some actionable notifications so that our users can complete a task from the notification itself.

1. Build Notification Actions

Notification actions are configured by including the actions property in your notification card object. The actions property must be an array of cardAction types.

When building notification actions, we recommend referencing the card response schema. Expand the card object, then expand the cardAction object to see a list of properties that can be included in cardAction objects. Properties in bold, such as id and action_key, are required properties.

Your cardActions, at a minimum, must include the following required fields:

  • id [string]: A unique GUID for the action.
  • action_key [string]: A defined action key detailing what happens when the action is interacted with. This can be "OPEN_IN", "USER_INPUT", or "DIRECT".
  • label [string]: The text displayed on the button for this action.
  • completed_label [string]: The text displayed on the button for this action after the action has been taken.
  • url [link]: The link or API endpoint that is interacted with when the action is taken.
  • type [string]: The HTTP method used for submitting the action request. This can be any HTTP method: "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "TRACE".

There are also optional properties that can be included to modify the behavior or the appearance of the notification card:

  • mutually_exclusive_set_id [string]: A unique string you create that allows grouping of actions. When an action in this group completes, other actions with the same mutually_exclusive_set_id string will hide.
  • primary [boolean]: If true, the action is colored differently to differentiate it from other actions. If not provided, the button is rendered as a non-primary action.
  • request [object]: If included, sends the defined hard-coded fields with the action request.
  • allow_repeated [boolean]: Allows the action to be clicked again after completing an action.
  • user_input [cardActionUserInput]: Allows the end user to enter data that is submitted when completing the action

The last property, user_input, is only rendered to the user when your action_key is set to "USER_INPUT". The cardActionUserInput object schema is defined on the card response schema page, but the notable properties are:

  • id [string]: A defined id for this user input field. When the response is submitted for the user's input, this id is used as the key for the response object. The value of the response object will be the user's entry into the provided input field.
  • label [string]: The field's text label, which is displayed to the user to describe the expected content of the field.
  • format [string]: Defines the type of the user input field. Currently, only "textarea" is supported for notification cards and thus is completely optional to include because "textarea" is the default value.

Actions have a lot of configurations that can be used. Follow the next steps to review some working examples.

2. Action: Open a Web Page

Consider this common administrative task as an example: John Smith's password is about to expire and we want to encourage John to update his password before it expires. We send an actionable notification card to his device with a button prompt that navigates John to the password reset page.

Note: You can use any method to send a notification with this notification card post body. We use the /api/v1/users/{USER_UUID}/notifications endpoint for simplicity to send a notification to the single user account: John Smith. These examples work with single-user or multi-user notifications.

Postman Collection Request: Notifications > Send Single-User Notifications > Users > Send Notification with Action (Open URL)
Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/notifications
Request: POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"importance": 1,
   "header": {
		"title": "Password Expiration Notice"
	},
	"body": {
		"description": "Your password is expiring soon. Follow the link below to update it!"
	},
	"actions":[
		{
			"id": "fdde28ed-ff91-4add-977e-164bf902a48e",
			"label": "Update Password",
			"completed_label": "Password upated",
			"action_key": "OPEN_IN",
			"type": "POST",
			"url": {
				"href": "https://sheetscorp.vidmpreview.com/SAAS/auth/forgotPassword"
			},
			"primary": true,
			"allow_repeated": false
		}
	]
}

The post body has the following properties:

Importance: The importance field dictates if it is an Urgent (0), High-Priority (1), or Standard (2) notification. For this example, we send a High-Priority (1) — we want this password expiration notice to be on the top of the user's notifications list because it is time-sensitive and important.

The "header": { "title": "..." } } and "body": { "description": "..." } } sections notate the title and description of the notification. We have elected to forgo sending any subtitles in this notification.

Then the actions array must be populated with a valid cardAction object that defines what the action looks like and how it responds when the user interacts with it:

  • id: Provide a GUID (Globally Unique Identifier) in string format to serve as a unique identifier for this action.
  • label: This string field notates the text on the actionable button displayed for the notification card. In this case, a button with the text "Update Password" is presented to the user.
  • completed_label: This string field causes the actionable button to change to the provided text after the user has interacted with the button. In this example, the button text changes from "Update Password" to "Password Updated". If completed_label is not provided, the button label will not change after the user presses it.
  • type: This string field notates the method used to interact with the given url field, in this case, issue a POST method for my link.
  • url: This object has a child property of href, which takes a string using the type property notating the URL to target when this button is clicked. In this case, we want to send the user to the password reset page of the SaaS Access tenant.
  • action_key: This string field notates the behavior action to be used when the user interacts with the button. Our example specifies "OPEN_IN" to open the target link.

The example also includes the following optional fields:

  • primary: This boolean field (true/false) notates if the button is the primary button, which changes the style of the button to draw the user's attention to it. If this field is not provided, the button defaults to the non-primary skin. We want to style the button as the primary button in the notification card.
  • allow_repeated: This boolean (true/false) field allows the button to be interacted with multiple times if true instead of just once. If allow_repeated is not provided, it defaults to false and the button can only be interacted with once. We want this action to only be taken once, so it is set to false. You could omit this value because the default is false. However, we included it to show where this mapped to in the Notifications UI in Hub Services.

Compare the actions object array against the Actions UI in the Workspace ONE Hub Services Notifications page to see how the object provided in the REST API post body matches up against the fields in the Notifications page.

Successful Response:

Status Code 200 OK

{ "created_at": "2020-05-06T12:44:25.744Z", "updated_at": "2020-05-06T12:44:25.744Z", "id": "7e8890cf-bfae-4f39-80ba-652f5d7ea845", "tenant_id": "sheetscorp", "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7", "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b", "device_id": null, "batch_id": null, "read_at": null, "last_action_id": null, "notification_card": { "importance": 1, "header": { "title": "Password Expiration Notice" }, "body": { "description": "Your password is expiring soon. Follow the link below to update it!" }, "actions": [ { "id": "fdde28ed-ff91-4add-977e-164bf902a48e", "label": "Update Password", "completed_label": "Password upated", "primary": true, "allow_repeated": false, "type": "POST", "url": { "href": "https://sheetscorp.vidmpreview.com/SAAS/auth/forgotPassword" }, "action_key": "OPEN_IN" } ] } }
Notification in Intelligent Hub
  1. John Smith receives the push notification on his device and taps it to enter the Intelligent Hub App.
  2. The For You section shows a notification count for our High-Priority notification.
  3. The notification card is displayed with the configured actionable button.
  4. John Smith clicks the Update Password button.
  5. The password reset page is opened on John's device.

3. Action: API Call

Another available action type is DIRECT, which allows the user to interact with an action and trigger a REST API request. This can be used to integrate Hub Notification actions with your own or other systems that expose REST APIs by sending a request in response to user interactions.  

For example, John Smith's office is limiting the number of concurrent users in the building, so urgent notifications are sent to employees explaining that anyone who requires access to the building must confirm their visit in advance. The Hub notification can facilitate this communication by presenting the employee with two options: one for confirming they will be onsite, and another for declining the need to be on site.

Note: You can use any method for sending a notification with this notification card post body. We are using the /api/v1/users/{USER_UUID}/notifications endpoint for simplicity to send a notification to the single user account: John Smith.

Postman Collection Request: Notifications > Send Single-User Notifications > Users > Send Notification with Action (API Call)
Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/notifications 
Request: POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
    "importance": 0,
    "header": {
		"title": "Important: On Site Access"
	},
	"body": {
		"description": "Employees wishing to enter the building must respond prior to their visit to confirm available capacity. Do you require access to the building?"
	},
    "actions": [
        {
            "id": "07e6463f-5595-4e6a-abcd-123456789012",
            "action_key": "DIRECT",
            "label": "Yes",
            "completed_label": "Submitted",
            "type": "POST",
            "url": {
                "href": "https://responses.yoursite.com"
            },
            "request": {
                "requireAccess": "yes"
            }
        },
        {
            "id": "536525c8-252c-4b78-8c54-6cb5ab50bc8f",
            "action_key": "DIRECT",
            "label": "No",
            "completed_label": "Submitted",
            "type": "POST",
            "url": {
                "href": "https://responses.yoursite.com"
            },
            "request": {
                "requireAccess": "no"
            }
        }
    ]
}

This post body is similar to our previous example of opening a web page, so we will skip discussing all the properties we've already reviewed. However, we want to highlight the differences between the two examples:

  • actions: They actions array now contains two cardAction objects, one for sending a "Yes" and one for a "No" response. The id fields must be unique for each action to differentiate them.
  • action_key: The action key property is now "DIRECT", signaling to send the type (POST) to the defined URL (https://responses.yoursite.com).
  • request: You can optionally include a request object to pass data with your request. In each case, we are passing the object { "requireAccess": "VALUE" } where VALUE is either yes or no.  This request object is received with the POST request and allows our service hosted at the defined URL to read the data and see if the employee requires access to the building or not.
    Note: The request object is converted to application/x-www-form-urlencoded format when sent, so your request key-value pairs must be strings.

Successful Response:

Status Code 200 OK

{
    "created_at": "2020-05-26T17:05:54.436Z",
    "updated_at": "2020-05-26T17:05:54.436Z",
    "id": "18a4c587-c478-4c7c-a0eb-72cd47f0ac08",
    "tenant_id": "sheetscorp",
    "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "device_id": null,
    "batch_id": null,
    "read_at": null,
    "last_action_id": null,
    "notification_card": {
        "importance": 0,
        "header": {
            "title": "Important: On Site Access"
        },
        "body": {
            "description": "Employees wishing to enter the building must respond prior to their visit to confirm available capacity. Do you require access to the building?"
        },
        "actions": [
            {
                "id": "07e6463f-5595-4e6a-abcd-123456789012",
                "action_key": "DIRECT",
                "label": "Yes",
                "completed_label": "Submitted",
                "type": "POST",
                "url": {
                    "href": "https://responses.yoursite.com"
                },
                "request": {
                    "requireAccess": "yes"
                }
            },
            {
                "id": "536525c8-252c-4b78-8c54-6cb5ab50bc8f",
                "action_key": "DIRECT",
                "label": "No",
                "completed_label": "Submitted",
                "type": "POST",
                "url": {
                    "href": "https://responses.yoursite.com"
                },
                "request": {
                    "requireAccess": "no"
                }
            }
        ]
    }
}
Notification on Intelligent Hub app
  1. John Smith receives the push notification on his device and taps it to enter the Intelligent Hub App.
  2. The notification card is displayed with the configured actionable buttons.
  3. John clicks the Yes or No button based on his requirements.
  4. The response details are sent to the configured URL.
  5. John's request is now logged on the service running at the configured URL, and the office can monitor how many employees require building access to take appropriate action.

3.1. Server Response

Unlike opening a web page, the process hosted at your configured URL (https://responses.yoursite.com) with the configured type (POST) for your DIRECT action_key must respond to this request to confirm that it was either received and processed successfully or that an error occurred.

Sending a successful response, such as a 200 OK or 202 Accepted, causes the notification card to close and marks the action as completed. Sending an unsuccessful status code, such as 400 Bad Request or 500 Internal Server Error, causes a prompt to display which informs the user that the response was unsuccessful and prompts them to try again or mark the notification as completed anyway.

If a timeout occurs and the server does not respond in a timely manner, a similar prompt is displayed which informs the user that a timely response could not be received and allows them to try the action again.

When errors occur, it is best practice to include a message with your response to the notification card action so that this information can be displayed to the user informing them of proper next steps. Perhaps they should contact an administrator or be told specifically why the request is failing (in the event of missing information or other issues) to provide a better employee experience.

4. Action: User Input

Responding to an action with additional request details is useful, but what about a scenario where you want users to enter their own input? Another available action type is USER_INPUT which allows the user to submit a custom response back as part of the action. Perhaps we want to collect some user feedback on a recent event or session and have opted to allow our users to respond using the Intelligent Hub.

Note: You can use any method to send a notification with this notification card post body. We are using the /api/v1/users/{USER_UUID}/notifications endpoint for simplicity to send a notification to the single user account: John Smith.

Postman Collection Request: Notifications > Send Single-User Notifications > Users > Send Notification with Action (User Input)
Request Format: POST | https://{{YOUR_ACCESS_TENANT_URL}}/ws1notifications/api/v1/users/{TARGET_USER_UUID}/notifications 
Request: POST | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/users/25940adf-8140-4f85-a792-9a61ed26a7e7/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Body:

{
	"importance": 2,
	"header": {
		"title": "Requesting Feedback"
	},
	"body": {
		"description": "How was the latest session? Tell us your thoughts!"
	},
	"actions":[
		{
			"id": "fdde28ed-ff91-4add-977e-164bf902a48e",
			"label": "Send Feedback",
			"completed_label": "Feedback Submitted",
			"primary": true,
			"allow_repeated": false,
			"type": "POST",
			"url": {
				"href": "https://responses.yourfeedbacksite.com"
			},
			"action_key": "USER_INPUT",
			"user_input": [
				{
					"id": "feedback_response",
					"label": "Feedback",
					"format": "textarea"
				}
			]
		}
	]
}

This post body is similar to our second example of sending an API request, so we will skip discussing the properties we have already reviewed. However, we want to highlight the differences between the two examples:

  • action_key: The action_key property is now "USER_INPUT", signaling to display the input fields that are defined in user_input array to the user when they interact with this action.
  • user_input: The user_input property accepts an array of cardActionUserInput objects, which we defined to provide a text area for feedback input. The key of the response will be the id property ("feedback_response") and the value would be the user entry in the field. So the request object sent to the defined URL would be { "feedback_response": "{USER INPUT HERE}" }.
  • request: Although the request field was not included in this example, you could still include it. For example, perhaps the request object could contain a meetingId which could be used to log this feedback against the appropriate meeting details in your system.

Successful Response:

Status Code 200 OK

{
    "created_at": "2020-05-21T11:17:22.853Z",
    "updated_at": "2020-05-21T11:17:22.853Z",
    "id": "e5fade29-9a85-4772-866f-6e95842830da",
    "tenant_id": "sheetscorp",
    "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "device_id": null,
    "batch_id": null,
    "read_at": null,
    "last_action_id": null,
    "notification_card": {
        "importance": 2,
        "header": {
            "title": "Requesting Feedback"
        },
        "body": {
            "description": "How was the latest session? Tell us your thoughts!"
        },
        "actions": [
            {
                "id": "fdde28ed-ff91-4add-977e-164bf902a48e",
                "label": "Send Feedback",
                "completed_label": "Feedback Submitted",
                "primary": true,
                "allow_repeated": false,
                "type": "POST",
                "url": {
                    "href": "https://responses.yourfeedbacksite.com"
                },
                "action_key": "USER_INPUT",
                "user_input": [
                    {
                        "id": "feedback_response",
                        "label": "Feedback",
                        "format": "textarea"
                    }
                ]
            }
        ]
    }
}
Workspace ONE Notifications on Intelligent Hub
  1. John Smith receives the push notification on his device and taps it to enter the Intelligent Hub App.
  2. The notification card is displayed with the configured actionable button.
  3. John clicks the Send Feedback button.
  4. The configured user input details are displayed, allowing John to enter feedback.
  5. John clicks Send Feedback, which sends his typed message using the configured type (POST) and URL (https://responses.yourfeedbacksite.com).

4.1. Server Response

Identical to the DIRECT (API Call) action, the process hosted at your configured URL (https://responses.yourfeedbacksite.com) with the configured type (POST) for your DIRECT action_key must respond to this request to confirm that it was either received and processed successfully or that an error occurred.

Sending a successful response, such as a 200 OK or 202 Accepted, causes the notification card to close and marks the action as completed. Sending an unsuccessful status code, such as 400 Bad Request or 500 Internal Server Error, causes a prompt to display which informs the user that the response was unsuccessful and prompts them to try again or mark the notification as completed anyway.

If a timeout occurs and the server does not respond in a timely manner, a similar prompt is displayed which informs the user that a timely response could not be received and allows them to try the action again.

When errors occur, it is best practice to include a message with your response to the notification card action so that this information can be displayed to the user informing them of proper next steps. Perhaps they should contact an administrator or be told specifically why the request is failing (in the event of missing information or other issues) to provide a better employee experience.

REST APIs - Querying Notifications

Now that you have created notifications and notification actions, this section discusses how to query notifications and batches of notifications, and how to delete notifications.

1. Query Sent Notifications

When creating notifications, the response includes an id property.  

In single-user notifications, this id property represents the identifier of the notification that was sent to the user and includes details such as if and when the notification was read, what action was taken, and more.

For multi-user notifications, this id property represents the batch identifier of the group of notifications that were sent and includes details such as how many notifications have been sent, how many total notifications are scheduled to be sent, and more.

1.1. Query Single-User Notifications

To confirm if and when users have read and acted against a notification, follow the next steps.

To begin, refer to one of your previously created notification responses to retrieve a valid notification id or send a new notification request to retrieve a valid notification id. Save the id property returned in the response.  

For this example, a notification has been sent to a single user account, John Smith, with a simple notification card that has a title and description.

{
    "created_at": "2020-05-26T18:15:43.793Z",
    "updated_at": "2020-05-26T18:15:43.793Z",
    "id": "febce3a0-9bf8-47b6-a513-ddf86d990ef8",
    "tenant_id": "sheetscorp",
    "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "device_id": null,
    "batch_id": null,
    "read_at": null,
    "last_action_id": null,
    "notification_card": {
        "header": {
            "title": "Sample Single-User Notification"
        },
        "body": {
            "description": "Notification description here"
        }
    }
}

After you have retrieved the id property of your notification response, enter the following commands in Postman:

Postman Collection Request: Notifications > Query Notification Details > Get Notification Info
Request Format: GET https://{{access_tenant_host}}/ws1notifications/api/v1/notifications/{NOTIFICATION_ID} 
Request: GET | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/notifications/febce3a0-9bf8-47b6-a513-ddf86d990ef8

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Successful Response:

Status Code 200 OK

{
    "created_at": "2020-05-26T18:15:43.793Z",
    "updated_at": "2020-05-26T18:16:05.927Z",
    "id": "febce3a0-9bf8-47b6-a513-ddf86d990ef8",
    "tenant_id": "sheetscorp",
    "user_id": "25940adf-8140-4f85-a792-9a61ed26a7e7",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "device_id": null,
    "batch_id": null,
    "read_at": "2020-05-26T18:16:05.925Z",
    "last_action_id": "EA77A25C-D101-4D38-8467-46FACD13BCB1",
    "notification_card": {
        "header": {
            "title": "Sample Single-User Notification"
        },
        "body": {
            "description": "Notification description here"
        }
    }
}

This notification can be queried after being sent to retrieve the details of the notification. The following items are not populated when the notification is created but might be of interest to the administrator:

  • read_at: If the notification has been read by the user, a timestamp is provided. If it has not been read yet, this field is null.
  • last_action_id: If the notification has had an action taken against it, that action id is populated here. Otherwise, this field is null.

1.2. Query Multi-User Notifications

You can also query details of multi-user notifications, which will inform you if all of the notifications were successfully delivered to the provided list of user UUIDs and/or device UUIDs.

To begin, refer to one of your previously created multi-user notification responses to retrieve a valid notification id or send a new notification request to retrieve a valid batch id. Save the id property returned in the response.  

For this example, we sent a notification to two user accounts, John Smith and Jane Doe, with a simple notification card that has a title and description.

{
    "created_at": "2020-05-19T17:53:57.457Z",
    "updated_at": "2020-05-19T17:53:58.010Z",
    "id": "70e0b866-b476-4ac3-bdac-9812936107af",
    "tenant_id": "sheetscorp",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "success_count": 2,
    "failure_count": 0,
    "results": "[{\"user_id\":\"22056712-5e3c-40dc-9190-4bfecd9b0c57\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"9326838f-7d05-48b6-8c9e-be20bd2029c2\"},{\"user_id\":\"25940adf-8140-4f85-a792-9a61ed26a7e7\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"3a922842-c9d1-4b2f-a806-ebc7a7a44db5\"}]",
    "total_recipients_count": 2,
    "batch_completed": true,
    "actioned_count": 0
}

After you have retrieved the batch id property of your notification response, enter the following commands in Postman:

Postman Collection Request: Notifications > Query Notification Details > Get Notification Batch Info

Request Format: GET https://{{access_tenant_host}}/ws1notifications/api/v1/batches/{BATCH_ID} 
Request: GET | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/batches/70e0b866-b476-4ac3-bdac-9812936107af

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Successful Response:

Status Code 200 OK

{
    "created_at": "2020-05-19T17:53:57.457Z",
    "updated_at": "2020-05-19T18:15:01.010Z",
    "id": "70e0b866-b476-4ac3-bdac-9812936107af",
    "tenant_id": "sheetscorp",
    "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
    "success_count": 2,
    "failure_count": 0,
    "results": "[{\"user_id\":\"22056712-5e3c-40dc-9190-4bfecd9b0c57\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"9326838f-7d05-48b6-8c9e-be20bd2029c2\"},{\"user_id\":\"25940adf-8140-4f85-a792-9a61ed26a7e7\",\"device_id\":\"\",\"status_code\":\"success\",\"notification_id\":\"3a922842-c9d1-4b2f-a806-ebc7a7a44db5\"}]",
    "total_recipients_count": 2,
    "batch_completed": true,
    "actioned_count": 1
}

You will notice some new fields when compared to the single-user notification result. Notable fields when querying batches include:

  • success_count: The number of notifications that were successfully sent.
  • failure_count: The number of notifications that failed to send to the intended recipient.
  • results: A JSON formatted array of objects that specifics the user UUID (user_id) that received a notification, the device UUID (device_id) that was provided, if the notification was delivered successfully or not (status_code), and the notification id (notification_id) which can be used to query single-user notification details to see if the notification was viewed or acted against.
  • total_recipients_count: The total number of recipients that were set to receive this notification. When success_count and failure_count total this number, all notifications have been sent.
  • batch_completed: Notates if the batch of notifications has finished sending to all target recipients. If any notifications are still waiting to be sent, this field is false.
  • actioned_count: The total number of actions across all target recipients that have been taken. To see exact action ids, query the notification_id field for a particular user in the results field using the query single-user notification REST API detailed in the previous section.

2. Query Device Notifications

In the previous examples, you saved your notification id or batch id to query the details of the notification. However, you can also query notifications that were sent to a particular device to check if the notification was received and if it has been read or had actions taken against it.

To begin, you need a valid device UDID to query notifications for. This example uses johnsmith's iPad device (device UDID: 8d6b19ec60227b86f09f733746d188a350224b5e). After you have retrieved a valid device UDID that you have sent notifications to, perform the next steps:

Postman Collection Request: Notifications > Query Notification Details > Get Notifications for Device
Request Format: GET https://{{access_tenant_host}}/ws1notifications/api/v1/devices/{TARGET_DEVICE_UDID}/notifications 
Request: GET | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/devices/8d6b19ec60227b86f09f733746d188a350224b5e/notifications

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Successful Response:

Status Code 200 OK

[
    {
        "created_at": "2020-05-01T18:05:09.364Z",
        "updated_at": "2020-05-01T18:05:09.364Z",
        "id": "f755b09f-d625-49b6-b284-817ec4fe2bfc",
        "tenant_id": "sheetscorp",
        "user_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
        "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
        "device_id": "8d6b19ec60227b86f09f733746d188a350224b5e",
        "batch_id": null,
        "read_at": null,
        "last_action_id": null,
        "notification_card": {
            "header": {
                "title": "REQUIRED: Notification Title Here",
                "subtitle": [
                    "OPTIONAL: Subtitle Here"
                ]
            },
            "body": {
                "description": "REQUIRED: Notification description here"
            }
        }
    },
    {
        "created_at": "2020-04-28T18:23:04.317Z",
        "updated_at": "2020-04-28T18:23:04.317Z",
        "id": "1c6efd95-da29-4004-a472-3d75c690efab",
        "tenant_id": "sheetscorp",
        "user_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
        "creator_id": "7857516c-4c0d-433f-b00e-f2c5cd35c14b",
        "device_id": "8d6b19ec60227b86f09f733746d188a350224b5e",
        "batch_id": null,
        "read_at": null,
        "last_action_id": null,
        "notification_card": {
            "header": {
                "title": "Alert - Tornado warning"
            },
            "body": {
                "description": "A tornado warning is in effect near you. Please head to the nearest designated shelter zone."
            }
        }
    }
]

Each notification sent to the device is available through this request. For a specific device, it might be easier and faster to query notifications by using the device UDID.

The notification id can be retrieved by referencing the id field of each object in the array. If the notification is part of a batch (multi-user notifications), the batch_id is also populated for that object, which you can use to query the batch details.

3. Conclusion

For insights into your delivered single-user and multi-user notifications to verify the delivery or confirm reads or actions, use the REST APIs. For large multi-user asynchronous deployments (100+ users), querying the batch details will also show you if all of the notifications have been delivered or not, similar to the Hub Services Notifications administration console.

 

REST APIs - Deleting Notifications

The final topic explores how to delete notifications. Deleting notifications can be useful if you discover that you sent a notification to the wrong user or device, or perhaps to retract the notification to make corrections to the message or actions.  

1. Delete Notifications

To begin, retrieve the notification id of a notification that has been sent to a user and/or device. For this example, a simple notification was sent to the user account, johnsmith, and the notification is unread on johnsmith's device. The notification id in this example is: 0e2f43c8-be34-4e5d-b8c8-ee08356faaa9.

After you have retrieved the id property of your notification response, perform the next steps in Postman:

Postman Collection Request: Notifications > Delete Notifications > Delete Notification
Request Format: DELETE https://{{access_tenant_host}}/ws1notifications/api/v1/notifications/{NOTIFICATION_ID} 
Request: DELETE | https://sheetscorp.vidmpreview.com/ws1notifications/api/v1/notifications/0e2f43c8-be34-4e5d-b8c8-ee08356faaa9

Headers:

Key Value
Authorization Bearer {ACCESS_TOKEN}

Note: You must include the access_token retrieved from the previous /SAAS/auth/oauthtoken request to authorize this request.
Accept application/json
Content-Type application/json

Successful Response:

Status Code 204 No Content

After the request has been processed, return to your device and refresh the For You notifications page. The pending notification that was sent has now been deleted from the device without any input required from the user.

2. Delete Batches

At the time of writing, deleting a batch of notifications is not supported. To delete all notifications sent to multiple users using the multi-user notifications, you must perform the next steps:

  1. Query the notification batch details (GET https://{{access_tenant_host}}/ws1notifications/api/v1/batches/{NOTIFICATION_BATCH_ID})
  2. In the notification batch details response, all sent notifications are contained in the results object in JSON format.
  3. Parse the results object and loop through all entries, which contain a notification_id field. Call the delete notification request (https://{{access_tenant_host}}/ws1notifications/api/v1/notifications/{NOTIFICATION_ID}) for each notification_id contained in the results object.

Summary and Additional Resources

Conclusion

This operational tutorial provided the steps required to set up and use notifications for Workspace ONE.  

These procedures included:

  • Configuring Workspace ONE Hub Services
  • Creating Notifications in the Workspace ONE Hub Services console
  • Creating the Service Client Token in Workspace ONE Access for REST API authorization
  • Using the Service Client Token to authorize and automate notification REST APIs to fully manage notifications

Terminology Used in This Tutorial

The following terms are used in this tutorial:

application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as Workspace ONE Access (formerly VMware Identity Manager).
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile device management
(MDM) agent
Software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
service provider (SP)
A host that offers resources, tools, and applications to users and devices.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

Additional Resources

For more information about the features and benefits of enabling Hub Services, check out the VMware Docs page for VMware Workspace ONE Hub Services.  

For documentation focused on the notifications service, check out the subpage Intelligent Hub Notifications Service.

For references on using the Workspace ONE notification REST APIs, explore the following resources:

For more details about using Workspace ONE UEM, you can find the full API reference for your UEM instance by navigating to https://{YOUR_UEM_API_ENDPOINT}/api/help.

For more details about using the Workspace ONE Access REST APIs, see https://code.vmware.com/apis/57/idm.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon. 

 

About the Author

This tutorial was written by:

  • Justin Sheets, Senior Technical Marketing Architect, End-User-Computing Technical Marketing, VMware

Feedback

Your feedback is valuable. 

To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.

Filter Tags

  • Workspace ONE
  • Intermediate
  • Operational Tutorial
  • Document
  • Workspace ONE UEM
  • Manage