OnScreenNotificationManager¶

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:

Schema
Custom Operations
Structures
Limitations
Concepts and Example

Schema ¶

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.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
sendNotification	POST	/notifications	If successful, this method returns a Message object in the response body.	Send the specified notification message.
editNotification	PUT	/notifications/{notificationId}	If successful, this method returns a Message object in the response body.	Update the specified notification.
deleteNotification	DELETE	/notifications/{notificationId}	If successful, this method returns the deleted notification in the response body.	Delete the specified notification.
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.
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.
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.
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.
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.

sendNotification¶

HTTP Request

POST /aps/2/services/notification-manager/notifications

Description

Send the specified notification message.

Parameters

PARAMETER	TYPE	DESCRIPTION
message	Message	Notification Message object

Returns

If successful, this method returns a Message object in the response body.

editNotification¶

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	Message	Notification Message object

Returns

If successful, this method returns a Message object in the response body.

deleteNotification¶

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.

getNotifications¶

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.

getLastNotificationMessagesByContext¶

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.

activityLog¶

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.

getDisplayMessages¶

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.

getNotificationChannel¶

HTTP Request

GET /aps/2/services/notification-manager/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.

Structures ¶

LocalizedMessage¶

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	DESCRIPTION
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).
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”}}}}.

Message¶

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 `sendNotification` operation and then used by the other operations.
type	Enum	Not Required	activity	The NotificationMessageType type, either `warning` or `activity`.
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`.
message	LocalizedMessage	Required		The LocalizedMessage structure.
localizedMessage	String	Not Required Read Only		Notification title.
details	LocalizedMessage	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	LocalizedMessage	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` on the bottom of the notification tile.
linkMoreText	LocalizedMessage	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, `linkMore`.
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, u201c2015-03-20T17:47:55Zu201d.
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 `context`.
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 `initiatorId` property.
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.

DisplayMessages¶

The Display Messages structure contains 3 groups of notificatios differentiated by types: warning, in progress activity, and other.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
warnings	Array of Message	Not Required	A list of Message objects of the `warning` type.
inProgressActivities	Array of Message	Not Required	A list of Message objects of the `InProgress activities` type.
otherActivities	Array of Message	Not Required	A list of Message objects of the `Other activities` type.

Channel¶

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.

Limitations ¶

Regardless of whom the notification is addressed to (an account or a user), all account staff members will receive it. Therefore, you must specify a user APS ID when sending a notification to a service user, even though all staff members will receive this notification.

Concepts and Example ¶

Get more explanations in the Notification Management concepts and follow the Notification Management demo project to get some experience in the APS type implementation.

← Notification Management

PCPNotificationManager →

CloudBlue Commerce API

Previous topic

Next topic

OnScreenNotificationManager¶

Schema ¶

Custom Operations ¶

sendNotification¶

editNotification¶

deleteNotification¶

getNotifications¶

getLastNotificationMessagesByContext¶

activityLog¶

getDisplayMessages¶

getNotificationChannel¶

Structures ¶

LocalizedMessage¶

Message¶

DisplayMessages¶

Channel¶

Limitations ¶

Concepts and Example ¶

CloudBlue Commerce API

Previous topic

Next topic

OnScreenNotificationManager¶

Schema¶

Custom Operations¶

sendNotification¶

editNotification¶

deleteNotification¶

getNotifications¶

getLastNotificationMessagesByContext¶

activityLog¶

getDisplayMessages¶

getNotificationChannel¶

Structures¶

LocalizedMessage¶

Message¶

DisplayMessages¶

Channel¶

Limitations¶

Concepts and Example¶

Schema ¶

Custom Operations ¶

Structures ¶

Limitations ¶

Concepts and Example ¶