This type defines the platform built-in Notification Manager that exposes common operations on notifications for CCP v2. Get more explanations in the Notification Management concepts. Get more experience following the Notification Management demo project.
In this document:
The considered APS type (download)
extends the Resource APS type(s) and 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",
"response": {
"type": "Message"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"message": {
"kind": "body",
"type": "Message"
}
}
},
"editNotification": {
"path": "/notifications/{notificationId}",
"verb": "PUT",
"response": {
"type": "Message"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"notificationId": {
"kind": "path",
"type": "string"
},
"message": {
"kind": "body",
"type": "Message"
}
}
},
"deleteNotification": {
"path": "/notifications/{notificationId}",
"verb": "DELETE",
"response": {
"type": "string"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"notificationId": {
"kind": "path",
"type": "string"
}
}
},
"getNotifications": {
"path": "/notifications",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "Message"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"channel": {
"kind": "query",
"type": "string"
}
}
},
"getLastNotificationMessagesByContext": {
"path": "/notifications/lastMessagesByContext",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "Message"
}
},
"errorResponse": {
"type": "object"
},
"parameters": {
"context": {
"kind": "query",
"type": "string"
}
}
},
"activityLog": {
"path": "/notifications/activitylog",
"verb": "GET",
"response": {
"type": "array",
"items": {
"type": "Message"
}
},
"errorResponse": {
"type": "object"
}
},
"getDisplayMessages": {
"path": "/notifications/displayMessages",
"verb": "GET",
"response": {
"type": "DisplayMessages"
},
"errorResponse": {
"type": "object"
}
},
"getNotificationChannel": {
"path": "/notifications/channel",
"verb": "GET",
"response": {
"type": "Channel"
},
"errorResponse": {
"type": "object"
}
}
},
"structures": {
"LocalizedMessage": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"keys": {
"type": "object"
},
"multilangKeys": {
"type": "object"
}
}
},
"Message": {
"type": "object",
"properties": {
"id": {
"type": "string",
"readonly": true
},
"type": {
"type": "string",
"default": "activity",
"enum": [
"activity",
"warning",
"announcement"
]
},
"status": {
"type": "string",
"default": "inProgress",
"enum": [
"inProgress",
"ready",
"error",
"existing",
"upcoming",
"notification"
]
},
"message": {
"type": "LocalizedMessage",
"required": true
},
"localizedMessage": {
"type": "string",
"readonly": true
},
"details": {
"type": "LocalizedMessage"
},
"localizedDetails": {
"type": "string",
"readonly": true
},
"fullDetails": {
"type": "LocalizedMessage"
},
"localizedFullDetails": {
"type": "string",
"readonly": true
},
"link": {
"type": "string"
},
"linkMore": {
"type": "string"
},
"linkMoreText": {
"type": "LocalizedMessage"
},
"localizedLinkMoreText": {
"type": "string",
"readonly": true
},
"packageId": {
"type": "string",
"required": true
},
"updated": {
"type": "boolean",
"readonly": true
},
"resolved": {
"type": "boolean",
"readonly": true
},
"created": {
"type": "string",
"readonly": true,
"format": "date-time"
},
"modified": {
"type": "string",
"readonly": true,
"format": "date-time"
},
"accountId": {
"type": "string"
},
"userId": {
"type": "string"
},
"context": {
"type": "string"
},
"initiatorId": {
"type": "string"
},
"initiator": {
"type": "string"
},
"service": {
"type": "string",
"required": true
},
"parentId": {
"type": "string"
},
"ipAddress": {
"type": "string"
}
}
},
"DisplayMessages": {
"type": "object",
"properties": {
"warnings": {
"type": "array",
"items": {
"type": "Message"
}
},
"inProgressActivities": {
"type": "array",
"items": {
"type": "Message"
}
},
"otherActivities": {
"type": "array",
"items": {
"type": "Message"
}
}
}
},
"Channel": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
}
}
}
}
| OPERATION | VERB | PATH | RETURNS | Description |
|---|---|---|---|---|
| activityLog | GET | /notifications/activitylog | If successful, this method returns a list of Message objects in the response body. | Get a list of notifications stored in the Action Log. The latter is available in CCP v2. |
| deleteNotification | DELETE | /notifications/{notificationId} | If successful, this method returns the deleted notification in the response body. | Delete the specified notification. |
| editNotification | PUT | /notifications/{notificationId} | If successful, this method returns a Message object in the response body. | Update the specified notification. |
| getDisplayMessages | GET | /notifications/displayMessages | If successful, this method returns a list of DisplayMessages objects in the response body. | Get the notifications groupped into the “Warnings”, “Activities in progress”, and “10 other latest notifications” sets. |
| getLastNotificationMessagesByContext | GET | /notifications/lastMessagesByContext | If successful, this method returns a list of the Message objects in the response body. | Get the last messages by context. |
| getNotificationChannel | GET | /notifications/channel | If successful, this method returns the Channel object (channel ID) in the response body. | Get the notification channel for a user. |
| getNotifications | GET | /notifications | If successful, this method returns a list of Message objects in the response body. | Get notifications from the specified channel. Use by the system to find out all notifications for a logged in user. |
| sendNotification | POST | /notifications | If successful, this method returns a Message object in the response body. | Send the specified notification message. |
HTTP Request
GET /aps/2/resources/{aps-id}/notifications/activitylog
Description
Get a list of notifications stored in the Action Log. The latter is available in CCP v2.
Returns
If successful, this method returns a list of Message objects in the response body.
HTTP Request
DELETE /aps/2/resources/{aps-id}/notifications/{notificationId}
Description
Delete the specified notification.
Parameters
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| notificationId | String | APS ID of the notification. |
Returns
If successful, this method returns the deleted notification in the response body.
HTTP Request
PUT /aps/2/resources/{aps-id}/notifications/{notificationId}
Description
Update the specified notification.
Parameters
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| message | Message | Notification Message object |
| notificationId | String | APS ID of the notification |
Returns
If successful, this method returns a Message object in the response body.
HTTP Request
GET /aps/2/resources/{aps-id}/notifications/displayMessages
Description
Get the notifications groupped into the “Warnings”, “Activities in progress”, and “10 other latest notifications” sets.
Returns
If successful, this method returns a list of DisplayMessages objects in the response body.
HTTP Request
GET /aps/2/resources/{aps-id}/notifications/lastMessagesByContext
Description
Get the last messages by context.
Parameters
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| context | String | String to filter messages by context; it is similar to the SQL LIKE operator, though it uses the “*” wildcard instead of “%” |
Returns
If successful, this method returns a list of the Message objects in the response body.
HTTP Request
GET /aps/2/resources/{aps-id}/notifications/channel
Description
Get the notification channel for a user.
Returns
If successful, this method returns the Channel object (channel ID) in the response body.
HTTP Request
GET /aps/2/resources/{aps-id}/notifications
Description
Get notifications from the specified channel. Use by the system to find out all notifications for a logged in user.
Parameters
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| channelId | String | Channel ID |
Returns
If successful, this method returns a list of Message objects in the response body.
The Channel structure contains only channel ID and is used by the system. When a user logs into a control panel, the system requests the notification channel for the user by calling the channel operation, and then using the channel ID reads the warning notifications addressed to the user or to the whole account.
| NAME | TYPE | ATTRIBUTES | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| id | String | Not Required | Chanel Identifier. |
The Display Messages structure contains 3 groups of notificatios differentiated by types: warning, in progress activity, and other.
| NAME | TYPE | ATTRIBUTES | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| inProgressActivities | Message array | Not Required | A list of
Message objects of the InProgress
activities type. |
|
| otherActivities | Message array | Not Required | A list of
Message objects of the Other
activities type. |
|
| warnings | Message array | Not Required | A list of
Message objects of the warning
type. |
This is an auxiliary structure used inside the Message structure to present a text that can be
translated into various languages as described in the Internationalization and Localization concepts.
| NAME | TYPE | ATTRIBUTES | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| keys | key-value pairs of String | Not Required | A list of the key and string pairs. Inside a localized message, it looks as in the following example: {“message”:{“message”:”The server __serverName__ is started”, “keys”:{“serverName”:”VPS-101”}}. | |
| message | String | Not Required | The message body, containing a text and, optionally, key words to substitute by actual values
(using the keys structure) and when necessary to translate to languages other than English
(using the multilangKeys structure). |
|
| multilangKeys | multilang structure | Not Required | A structure that translates each key to various languages. So, a key is mapped to a list of language code and translated string pairs. Inside a localized message, it looks as in the following example: {“message”:{“message”:”__newApp__ - http://app.aps.test”, “multilangKeys”:{“newApp”:{“en”:”A new application is available at this URL”, “de”: “Neue Anwendung ist bei dieser URL verfügbar”}}}}. |
The main structure used in various custom operations, such as sendNotification and
editNotification, to specify the input and output content.
| NAME | TYPE | ATTRIBUTES | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| accountId | String | Not Required | APS ID of the account that the notification request is addressed to. All users of the account are notified. | |
| context | String | Not Required | Optional attribute that allows you to gather notifications in a context group and then search or
filter notifications by context. |
|
| created | Date | Not Required Read Only | Date and time of the notification creation, for example, “2015-03-20T17:47:55Z”. | |
| details | LocalizedMessage | Not Required | The LocalizedMessage short description displayed by CCP v2 in the list of notificaions. | |
| fullDetails | LocalizedMessage | Not Required | Full LocalizedMessage description displayed by CCP v2 when the notification is opened on the screen. | |
| id | String | Not Required Read Only | APS ID of the notification. The system generates it automatically when it receives a notification.
So, the APS ID is returned by the sendNotification operation and then used by the other
operations. |
|
| initiator | String | Not Required | The read-only name of the user that initiated the activity. The system determines it automatically
by the initiatorId property. |
|
| initiatorId | String | Not Required | APS ID of the user that initiated the activity. Optional property. | |
| ipAddress | String | Not Required | IP Address. | |
| link | String | Not Required | Direct link to an object, for example, “/v/aps/samples/async1pn/servers”. | |
| linkMore | String | Not Required | Additional link with a label defined by linkMoreText on the bottom of the notification tile. |
|
| linkMoreText | LocalizedMessage | Not Required | The LocalizedMessage text of the more link displayed on the notification tile. | |
| localizedDetails | String | Not Required Read Only | Localized short description. | |
| localizedFullDetails | String | Not Required Read Only | Localized full description. | |
| localizedLinkMoreText | String | Not Required Read Only | Localized label presenting the additional link, linkMore. |
|
| localizedMessage | String | Not Required Read Only | Notification title. | |
| message | LocalizedMessage | Required | The LocalizedMessage structure. | |
| modified | Date | Not Required Read Only | Date and time of the latest notification update. | |
| packageId | String | Required | ID of the package that is the source of the current service sending the request; can be used to retrieve static resources like icons and i18n. | |
| parentId | String | Not Required | An application can specify the ID of a notification considered as the parent message. The child notifications do not pop up on the screen. | |
| resolved | Boolean | Not Required Read Only | Shows if the notification was resolved. | |
| service | String | Required | The name of the service that initiated the activity; filled in by the application service. | |
| status | Not Required | inProgress | The
NotificationMessageStatus status. An activity notification status can be
either inProgress, ready, or error. A warning notification status can be either
upcomming, or existing. |
|
| type | Not Required | activity | The NotificationMessageType type, either warning or activity. |
|
| updated | Boolean | Not Required Read Only | Indicates if the notification was updated at least once. | |
| userId | String | Not Required | APS ID of the user whom the notification is addressed. |
Since the considered APS type contains custom operations, refer to Custom Operations for the general explanation of their structure and examples of operation calls.