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"
}
}
}
}
}
The APS type is used to create a singleton APS resource exposing its operations for API calls. The call syntax depends on the operation. For example, a call of an operation that accepts input parameters both in the URL string and in the body looks as follows:
POST /aps/2/services/notification-manager/<operation-path>?<query-params>
{/*<body params>*/}
In the above call, the verb can be either GET, PUT, POST, or DELETE as specified in the definition of the operation.
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
POST |
/notifications |
If successful, this method returns a Message object in the response body. |
Send the specified notification message. |
|
PUT |
/notifications/{notificationId} |
If successful, this method returns a Message object in the response body. |
Update the specified notification. |
|
DELETE |
/notifications/{notificationId} |
If successful, this method returns the deleted notification in the response body. |
Delete the specified notification. |
|
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. |
|
GET |
/notifications/lastMessagesByContext |
If successful, this method returns a list of the Message objects in the response body. |
Get the last messages by context. |
|
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. |
|
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. |
|
GET |
/notifications/channel |
If successful, this method returns the Channel object (channel ID) in the response body. |
Get the notification channel for a user. |
HTTP Request
POST /aps/2/services/notification-manager/notifications
Description
Send the specified notification message.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
message |
Notification Message object |
Returns
If successful, this method returns a Message object in the response body.
HTTP Request
PUT /aps/2/services/notification-manager/notifications/{notificationId}
Description
Update the specified notification.
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
notificationId |
String |
APS ID of the notification |
message |
Notification Message object |
Returns
If successful, this method returns a Message object in the response body.
HTTP Request
DELETE /aps/2/services/notification-manager/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
GET /aps/2/services/notification-manager/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 |
---|---|---|
channel |
String |
Returns
If successful, this method returns a list of Message objects in the response body.
HTTP Request
GET /aps/2/services/notification-manager/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/services/notification-manager/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
GET /aps/2/services/notification-manager/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.
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 |
---|---|---|---|---|
message |
String |
Not Required |
The message body, containing a text and, optionally, key words to substitute by actual values (using the |
|
keys |
Object |
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”}}. |
|
multilangKeys |
Object |
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 |
---|---|---|---|---|
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 |
|
type |
Enum |
Not Required |
activity |
The NotificationMessageType type, either
warning or activity .Notification type:
activity - the notification attracts attention to a process.warning - the notification informs about an existing or upcoming issue.announcement - the announcement that can be sent from the Provider Control Panel. APS applications cannot use it. |
status |
Enum |
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 .Status for the
activity notifications:inProgress - the action is not completed yet.ready - the action completed successfully.error - the action failed.Status for the
warning notifications:upcoming - warning about an issue that can happen later.existing - there is already an issue; you may consider it as a “critical” event. |
message |
Required |
The LocalizedMessage structure. |
||
localizedMessage |
String |
Not Required Read Only |
Notification title. |
|
details |
Not Required |
The LocalizedMessage short description displayed by CCP v2 in the list of notificaions. |
||
localizedDetails |
String |
Not Required Read Only |
Localized short description. |
|
fullDetails |
Not Required |
Full LocalizedMessage description displayed by CCP v2 when the notification is opened on the screen. |
||
localizedFullDetails |
String |
Not Required Read Only |
Localized full description. |
|
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 |
Not Required |
The LocalizedMessage text of the more link displayed on the notification tile. |
||
localizedLinkMoreText |
String |
Not Required Read Only |
Localized label presenting the additional link, |
|
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. |
|
updated |
Boolean |
Not Required Read Only |
Indicates if the notification was updated at least once. |
|
resolved |
Boolean |
Not Required Read Only |
Shows if the notification was resolved. |
|
created |
String |
Not Required Read Only |
Date and time of the notification creation, for example, “2015-03-20T17:47:55Z”. |
|
modified |
String |
Not Required Read Only |
Date and time of the latest notification update. |
|
accountId |
String |
Not Required |
APS ID of the account that the notification request is addressed to. All users of the account are notified. |
|
userId |
String |
Not Required |
APS ID of the user whom the notification is addressed. |
|
context |
String |
Not Required |
Optional attribute that allows you to gather notifications in a context group and then search or filter notifications by |
|
initiatorId |
String |
Not Required |
APS ID of the user that initiated the activity. Optional property. |
|
initiator |
String |
Not Required |
The read-only name of the user that initiated the activity. The system determines it automatically by the |
|
service |
String |
Required |
The name of the service that initiated the activity; filled in by the application service. |
|
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. |
|
ipAddress |
String |
Not Required |
IP Address. |
The Display Messages structure contains 3 groups of notificatios differentiated by types: warning, in progress activity, and other.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
warnings |
Array of Message |
Not Required |
A list of Message objects of the |
|
inProgressActivities |
Array of Message |
Not Required |
A list of Message objects of the |
|
otherActivities |
Array of Message |
Not Required |
A list of Message objects of the |
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. |
Get more explanations in the Notification Management concepts and follow the Notification Management demo project to get some experience in the APS type implementation.