On-Screen Notifications

UX1 Panel allows applications to attract attention of customer users to some events. For this purpose, an application can send various notifications through the Notification Manager. Notifications can be addressed to an account or to a user (typically, to a service user):

• If a notification is addressed to an account APS ID, all account staff members will receive it.

• If a notification is addressed to a service user APS ID, all account staff members and this service user will receive it.

The user panel has special buttons that a user can click to show or hide notifications.

Notification Types

There are two types of notifications that a user can receive:

• Activity is a notification attracting attention to a process that can be ready (completed) or in progress.

  

• Warning is a notification that attracts attention to existing or upcoming issues. The former issues are treated as problems and the latter as warnings.

  

Notification Manager

In the platform, there is a system APS service that processes notifications through its On-screen Notification Manager resource. The structure of the On-screen Notification Manager APS type looks as follows.

{
   "name": "OnScreenNotificationManager",
   "id": "http://www.parallels.com/pa/pa-core-services/notification-manager/1.0",
   "apsVersion": "2.0",
   "implements": [
      "http://aps-standard.org/types/core/resource/1.0"
   ],
   "access": {
      "global": true
   },
   "operations": {
      "sendNotification": {
         "path": "/notifications",
         "verb": "POST",
         ...
      },
      "editNotification": {
         "path": "/notifications/{notificationId}",
         "verb": "PUT",
         ...
      },
      "deleteNotification": {
         "path": "/notifications/{notificationId}",
         "verb": "DELETE",
         ...
      },
      "getNotifications": {
         "path": "/notifications",
         "verb": "GET",
         ...
      },
      "getLastNotificationMessagesByContext": {
         "path": "/notifications/lastMessagesByContext",
         "verb": "GET",
         ...
      }
      "activityLog": {
         "path": "/notifications/activitylog",
         "verb": "GET",
         ...
      },
      "getDisplayMessages": {
         "path": "/notifications/displayMessages",
         "verb": "GET",
         ...
      },
      "getNotificationChannel": {
         "path": "/notifications/channel",
         "verb": "GET",
         ...
      }
   },
   "structures": {
      "LocalizedMessage": {
         ...
      },
      "Message": {
         ...
      },
      "DisplayMessages": {
         ...
      },
      "Channel": {
         ...
      }
   }
}

This type declares the following.

• Notification manager is a global resource, that is available to any authenticated user.

• Structures:

  • Message is sent in the body of notification requests.

  • LocalizedMessage declares a structure used inside the Message structure to localize the message text.

  • DisplayMessages presents all notifications in 3 sets: all warnings, activities in progress, and other activities.

  • Channel is used by the system to identify the notification channel established between the Notification Manager and a user. For example, the system uses the channel ID of a user to retrieve all warning notifications, when the user logs into the user panel. This document does not provide any more details about the Channel structure.

  For details, refer to the full list of the Message properties.

• Custom operations:

  • sendNotification creates a notification.

  • editNotification updates a notification.

  • deleteNotification removes a notification.

  • getNotifications returns a list of notifications.

  • getLastNotificationMessagesByContext returns the latest messages of the notifications filtered by the specified context.

  • activityLog returns the list of notifications stored in the Action Log.

  • getDisplayMessages returns the DisplayMessages object containing 3 groups of notifications:

    warnings, activities in progress, and 10 other latest activities.

  • getNotificationChannel gets the channel ID for a certain user (used by the system).

Note

Notifications are stored not in the APS controller, but rather in the platform database. That is why they are available only through the custom operations listed above.

An application can call a custom operation through a connection with the APS controller. In APS PHP runtime, use the following method returning the representation of the APS controller proxy resource:

$apsc = \APS\Request::getController();

The examples of code on the application backend side are based on using the APS PHP runtime library.

Sequence of Operations

When processing notifications in an application, typically a number of steps are needed in the following order.

1. Prepare a connection with the notification manager and define interface elements. Get an instance of the notification manager for this:

   $notificationManager = \APS\NotificationManager::getInstance();
   

2. Prepare notification properties to be sent, for example, in the $notification object.

   Notification REST request must contain the Message structure in its body.

3. Send the needed notification request to the Notification Manager as described in the following sections.

   $notificationManager->sendNotification($notification);
   

Notification Message

A message sent in the body of a notification REST request defines the properties of the notification that must be created or updated by the Notification Manager.

• Addressee is defined by the accountId (the notification will be available for all account staff members) or by the userId property (the notification will be available for all account staff members and for the addressed user).

• The type and status of a notification are enumerated:

  • The activity type allows assigning the inProgress (default value), ready, or error status.

  • The warning type allows assigning the existing or upcoming status.

• A notification can contain the following objects whose structure is defined by LocalizedMessage:

  • The message object defines a text typed in the header of the notification tile in the user panel.

  • The details object defines a body text when a notifications is displayed in the list of notifications.

  • The fullDetails object defines the notification details when the notification is opened for review.

• It is possible to define the main and additional links in a notification tile:

  • link defines the main link. The link is optional, but recommended. The notification tile will forward users to the specified link when they click on the tile body.

  • linkMore and linkMoreText define respectively the additional link and the text of the link displayed. This pair is optional. This is also known as an action link.

Note

If no links are provided, then users are forwarded to the notification details screen that displays the full details as explained in the Action Log section.

When a notification is generated, it appears in the following locations.

• In the current screen as a temporary pop-up tile:

  

  Up to 5 pup-ups can be displayed concurrently. If there are more concurrent notifications, the others are waiting in a queue.

• On the Home dashboard:

  

  The Home dashboard starts collecting notifications by types if the total number of the notifications exceeds 3 as the above screenshot demonstrates.

• On the warning sidebar in one of two separate lists of warning notifications, problems and warnings:

  

• On the activity sidebar in one of two lists of activity notifications, those that are in progress and those that are completed:

  

An example of a notification message is presented in the demo project.

Action Log

Activity notifications are stored in the account Action Log.

• The details messages are shown in the list of notifications:

  

• The fullDetails messages are displayed in the pop-up that appears when you click on a notification:

  

An application can request for the log by calling the acivityLog method.

Create Notification

The sendNotification operation of the Notification Manager creates a notification object with the properties defined in the request body in accordance with the Message structure.

"sendNotification": {
   "path": "/notifications",
   "verb": "POST",
   "response": {
     "type": "Message"
   },
   "errorResponse": {
     "type": "object"
   },
   "parameters": {
     "message": {
       "kind": "body",
       "type": "Message"
     }
   }
}

Once the APS ID of the Notification Manager resource is available and the notification message is prepared, an application can send a request for creating a notification, for example:

$notificationResponse = $notificationManager->sendNotification($notification);

In the above code, the $notificationResponse will contain the full representation of the new notification. An application needs to save the notification ID if it is going to modify or remove the notification later. As a solution, it is possible to add one more property to the respective resource schema. Then, a method of the service can save the notification ID as follows:

$this->notificationId = $notificationResponse->id;

Update Notification

The Notification Manager allows updating notifications through its editNotification operation:

"editNotification": {
   "path": "/notifications/{notificationId}",
   "verb": "PUT",
   "response": {
     "type": "Message"
   },
   "errorResponse": {
     "type": "object"
   },
   "parameters": {
     "notificationId": {
       "kind": "path",
       "type": "string"
     },
     "message": {
       "kind": "body",
       "type": "Message"
     }
   }
}

If an application stores notification IDs, it is able to update them. For this purpose, it prepares all properties that must be updated as a Message structure and then sends it as the body in the request for the custom editNotification operation. In the following example, an application uses the notification ID available as a property of the respective resource - $this->notificationId.

if (isset($this->notificationId)) {
     $notificationResponce = $notificationManager->editNotification(
         $this->notificationId,
         $notification
);}

Remove Notification

The custom deleteNotification operation allows applications to remove notifications:

"deleteNotification": {
   "path": "/notifications/{notificationId}",
   "verb": "DELETE",
   "response": {
     "type": "string"
   },
   "errorResponse": {
     "type": "object"
   },
   "parameters": {
     "notificationId": {
       "kind": "path",
       "type": "string"
     }
   }
}

To remove a notification, an application needs to know the notification ID. Then, it can call the operation as in the following example:

$notificationManager->deleteNotification($this->notificationId);

Internationalization

The Internationalization in Notifications document explains in details how notifications can support multiple languages.

Example

Refer to the demo project that contains step-by-step development process of creating and testing an integration package illustrating the use of notifications.

← Service in User Profile

Integration with DNS →