Automating Notifications: Workspace ONE Operational Tutorial

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

Click Get Started.

Hub Services is co-located with Workspace ONE Access, so you must provide your Workspace ONE Access tenant details to activate 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.

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.

1. Click Notifications.
2. Click Get Started.

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.

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.

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.

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.

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.

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, deactivate this.
5. Optional - If additional actions are required, you can use the Add Action button.

Tip: You can check your preview at the top.

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.

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

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.

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

1. Click the drop-down arrow by the Catalog tab.
2. Click Settings.

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

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.

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. If not already installed, download and install Postman for free at https://www.postman.com.
2. Launch the Postman app.

Click Import.

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).

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.

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

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.

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.

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.

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:

Body:

Format: x-www-form-urlencoded

Successful Response:

Status Code: 200 OK

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.

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.

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:

Body:

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

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.

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:

To send a High-Priority Notification:

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:

Body:

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

Successful Response:

Status Code 200 OK

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.

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:

Body:

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.  

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:

Body:

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

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.

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.

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:

Body:

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

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.

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:

Body:

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

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.

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:

Body:

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

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).

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.

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:

Successful Response:

Status Code 200 OK

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.

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.

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:

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.

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.