Config API Version 2 Notifications

Introduction

Notifications enable users to be notified of information that may be deemed useful to them.

Notifications can be created by users with the correct permissions and viewed by users who match the criteria. When requesting to be notified, context may be supplied so that notifications can be better targeted.

List Notifications

Lists the notifications that can be accessed by the user

Request:

GET /config/v2/organisations/{ORG SPECIFIER}/notifications

URL Path Params

ORG SPECIFIER (int) - Organisation ID.

GET Params

filter (array) OPTIONAL - One or more filters.
sort (array) OPTIONAL - One or more sorting params.
group (array) OPTIONAL - One or more groups.
limit (integer) OPTIONAL - limit on the result set.
offset (integer) OPTIONAL - offset of the result set.

Filter Types

The notifications list may be filtered by any of the returned fields, except criteria.

Sort Types

The notifications list may be sorted by any of the returned fields, except criteria.

Group Types

The notifications list may be grouped by any of the returned fields, except criteria.

Response:

HTTP 200 - OK

{"notificationId":"1","title":"Notification title","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2013-01-01","endDate":"2013-02-01","orgId":"1","criteria":[[{"field":"igrp","op":"eq","value":"1"}]]}

{"notificationId":"2","title":"Notification title","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2013-02-01","endDate":"2013-02-28","orgId":"1","criteria":[]}

Request:

GET /config/v2/organisations/{ORG SPECIFIER}/notifications/{notificationId}

URL Path Params

ORG SPECIFIER (int) - Organisation ID.
notificationId (spec) - Notification ID (int).

Response:

HTTP 200 - OK

{"notificationId":"2","title":"Notification title","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2013-02-01","endDate":"2013-02-28","orgId":"1","criteria":[]}

Create a Notification

Creates a new notification

Request:

POST /config/v2/organisations/{ORG SPECIFIER}/notifications

URL Path Params

ORG SPECIFIER (int) - Organisation ID.

POST Params

title (string) - The title of the notification
synopsis (string) - The synopsis (short description) of the notification
url (url) OPTIONAL - The URL this notification points to
startDate (date) - The date to show this notification from
endDate (date) - The date to stop showing this notification
criteria (array) OPTIONAL - An array of criteria to filter this notification on

Response:

HTTP 201 - CREATED

{"notificationId":"3","title":"Notification title test","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2014-01-01","endDate":"2015-02-01","orgId":"1","criteria":[[{"field":"package","op":"eq","value":"standard"}]]}

Acceptable Criteria

There are a number of criteria that can be used to ensure that notifications will only show under certain circumstances. All criteria can be set using the standard logical operators (eq, in, gt, etc.)

The context is determined by the parameters passed when a user is requesting to be notified

userId - Only notify specific users in a set
userPrimaryOrgId - Only notify users with a specific primary organisation
igrp - Only notify users that are in a specific IGRP context
package - Only notify users in a specific package context (standard-uk, enterprise-uk, etc.)
report - Only notify users in a specific report context

Update a Notification

Updates the notification

Request:

POST /config/v2/organisations/{ORG SPECIFIER}/notifications/{notificationId}

URL Path Params

ORG SPECIFIER (int) - Organisation ID.
notificationId (spec) - Notification ID (int).

POST Params

title (string) OPTIONAL - The title of the notification
synopsis (string) OPTIONAL - The synopsis (short description) of the notification
url (url) OPTIONAL - The URL this notification points to
startDate (date) OPTIONAL - The date to show this notification from
endDate (date) OPTIONAL - The date to stop showing this notification
criteria (array) OPTIONAL - An array of criteria to filter this notification on

Response:

HTTP 204 - NO CONTENT

Request to be notified

Lists all notifications that match the context the user is in

Request:

POST /config/v2/profile/notifications

GET Params

filter (array) OPTIONAL - One or more filters.
sort (array) OPTIONAL - One or more sorting params.
limit (integer) OPTIONAL - Limit on the result set.
offset (integer) OPTIONAL - Offset of the result set.
igrp (integer) OPTIONAL - IGRP context.
package (string) OPTIONAL - Package context.
report (string) OPTIONAL - Report context.

Filter Types

The notifications list may be filtered by any of the returned fields.

Sort Types

The notifications list may be sorted by any of the returned fields.

Response:

HTTP 200 - OK

{"notificationId":"4","title":"Notification title test","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2014-01-01","endDate":"2015-02-01","state":"r"}

Request a Single Notification in a Profile

Returns a single notification

Request:

POST /config/v2/profile/notifications/{notificationId}

URL Path Params

notificationId (spec) - Notification ID (int).

Response:

HTTP 200 - OK

{"notificationId":"4","title":"Notification title test","synopsis":"Synopsis of the notification","url":"http:\/\/www.example.org","startDate":"2014-01-01","endDate":"2015-02-01","state":"r"}

Update a Notification in a Profile

Updates a single notification

Request:

POST /config/v2/profile/notifications/{notificationId}

URL Path Params

notificationId (spec) - Notification ID (int).

POST Params

state (string) - Single character notification state (either (r)ead, (i)gnored, or (s)noozed)

Response:

HTTP 204 - No Content

Fields

Management

notificationId (int) - ID to use for notification
orgId (int) - The organisation that this notification belongs to (and therefore filters down from)
title (string) - The title of the notifictaion
synopsis (string) - The short description of what the article is about
url (string) - The URL that contains the full article
startDate (date) - The date the notification is shown from
endDate (date) - The last day the notification is shown
criteria (array) - An array of arrays containing criteria to filter this notification on

User Profile Notification

notificationId (int) - ID to use for notificationbelongs to (and therefore filters down from)
title (string) - The title of the notifictaion
synopsis (string) - The short description of what the article is about
url (string) - The URL that contains the full article
startDate (date) - The date the notification is shown from
endDate (date) - The last day the notification is shown
state (string) - The state of the notification i.e. (u)nread, (r)ead, (i)gnored, (s)noozed