Table of Contents

• Notification Endpoints
  • Obtaining Notifications
  • Obtaining Notification Counts
  • Obtaining Unseen Notifications
  • Obtaining the Ten Most Recent Notifications
  • Marking Notifications as Seen
  • Marking All Notifications as Seen
  • Marking Notifications as Deleted
  • Marking All Notifications as Deleted
  • Sending an Arbitrary Notification
  • Endpoints for System Messages (a.k.a. System Notifications)

Notification Endpoints

Obtaining Notifications

Secured Endpoint: GET /secured/notifications/messages

This endpoint is primarily a passthrough endpoint to the notification agent’s /messages endpoint, but it does make calls into the apps service in order to add the app description to job status update notifications.

Notifications in the DE are used to inform users when some event (for example a job status change or the completion of a file upload) has occurred. This service provides a way for the DE to retrieve notifications that the user may or may not have seen before. This service accepts five different query-string parameters:

The response body for this service is in the following format:

{
    "messages": [
        {
            "deleted": "deleted-flag",
            "message": {
                "id": "message-id",
                "text": "message-text",
                "timestamp": "milliseconds-since-epoch",
            }
            "outputDir": "output-directory-path",
            "outputManifest": "list-of-output-files",
            "payload": {}
            "seen": "seen-flag",
            "type": "notification-type-code",
            "user": "username"
        },
    ],
    "total": "message-count"
}

The payload object in each message is a JSON object with a format that is specific to the notification type, and its format will vary. There are currently three types of notifications that we support: data, analysis and tool. The data and analysis notification types have the same payload format:

{
    "action": "action-code",
    "analysis-details": "analysis-description",
    "analysis_id": "analysis-id",
    "analyis_name": "analysis-name",
    "description": "job-description",
    "enddate": "end-date-in-milliseconds-since-epoch",
    "id": "job-id",
    "name": "job-name",
    "resultfolderid": "result-folder-path",
    "startdate": "start-date-in-milliseconds-since-epoch",
    "status": "job-status-code",
    "user": "username"
}

The payload format for the tool notification type is a little simpler:

{
    "email_address": "email-address",
    "toolname": "tool-name",
    "tooldirectory": "tool-directory",
    "tooldescription": "tool-description",
    "toolattribution": "tool-attribution",
    "toolversion": "tool-version"
}

Here’s an example:

$ curl -sH "$AUTH_HEADER" "http://by-tor:8888/secured/notifications/messages?limit=1&offset=0" | python -mjson.tool
{
    "messages": [
        {
            "deleted": false,
            "message": {
                "id": "C15763CF-A5C9-48F5-BE4F-9FB3CB1897EB",
                "text": "URL Import of somefile.txt from http://snow-dog.iplantcollaborative.org/somefile.txt completed",
                "timestamp": 1331068427000
            },
            "outputDir": "/iplant/home/nobody",
            "outputManifest": [],
            "payload": {
                "action": "job_status_change",
                "analysis-details": "",
                "analysis_id": "",
                "analysis_name": "",
                "description": "URL Import of somefile.txt from http://snow-dog.iplantcollaborative.org/somefile.txt",
                "enddate": 1331068427000,
                "id": "40115C19-AFBC-4CAE-9738-324DD8B18FDC",
                "name": "URL Import of somefile.txt from http://snow-dog.iplantcollaborative.org/somefile.txt",
                "resultfolderid": "/iplant/home/nobody",
                "startdate": "1331068414712",
                "status": "Completed",
                "user": "nobody"
            },
            "seen": true,
            "type": "data",
            "user": "nobody"
        }
    ],
    "total": "37"
}

Obtaining Notification Counts

Secured Endpoint: GET /secured/notifications/count-messages

This endpoint is a passthrough to the notification agent endpoint, /count-messages. Please see the notification agent documentation for more details.

This service takes a subset of the query-string parameters as the /messages service, and returns the number of messages that match the criteria specified in the query-string parameters. Here’s the list of supported query-string parameters:

The response body consists of a JSON object containing four fields: user-total, contains the number of user messages that have not been marked as deleted and match the criteria specified in the query string, system-total contains the number of system messages that are active and have not been dismissed by the user, system-total-new contains the number of system messages that have not been marked as received by the user, and system-total-unseen contains the number of system messages that have not been marked as seen by the user.

{
    "user-total":          count,
    "system-total":        count,
    "system-total-new":    count,
    "system-total-unseen": count
}

Here are some examples:

$ curl -sH "$AUTH_HEADER" "http://by-tor:8888/secured/notifications/count-messages" | python -mjson.tool
{
    "user-total":          409,
    "system-total":         10,
    "system-total-new":      0,
    "system-total-unseen":   1
}

In this example, all messages that are available for the user that have not been marked as deleted are counted.

$ curl -sH "$AUTH_HEADER" "http://by-tor:8888/secured/notifications/count-messages?filter=data" | python -mjson.tool
{
    "user-total":          91,
    "system-total":        10,
    "system-total-new":     0,
    "system-total-unseen":  1
}

In this example only the data notifications that have not been marked as deleted are counted.

Obtaining Unseen Notifications

Secured Endpoint: GET /secured/notifications/unseen-messages

This endpoint is primarily a passthrough endpoint to the notification agent’s /unseen-messages endpoint, but it does make calls into the apps service in order to add the app description to job status update notifications.

This service is used to obtain notifications that the user hasn’t seen yet. This service takes no query-string parameters. Here’s an example:

$ curl -sH "$AUTH_HEADER" "http://by-tor:8888/secured/notifications/unseen-messages" | python -mjson.tool
{
    "messages": []
}

Obtaining the Ten Most Recent Notifications

Secured Endpoint: GET /secured/notifications/last-ten-messages

This endpoint is primarily a passthrough endpoint to the notification agent’s /last-ten-messages endpoint, but it does make calls into the apps service in order to add the app description to job status update notifications.

This endpoint returns the ten most recent messages for the authenticated user in ascending order by message timestamp. Obtaining the ten most recent messages in ascending order is difficult using other endpoints.

Examples are omitted for this endpoint because the response body is identical to that of the other endpoints used to obtain notifications.

Marking Notifications as Seen

Secured Endpoint: POST /secured/notifications/seen

This endpoint is a passthrough to the notification agent’s /seen endpoint. Please see the notification agent documentation for more details.

Once a user has seen a notification, the notification should be marked as seen to prevent it from being returned by the /notifications/unseen-messages endpoint. This service provides a way to mark notifications as seen. The request body for this service is in the following format:

{
    "uuids": [
        "uuid-1",
        "uuid-2",
        "uuid-n"
    ]
}

The response body for this service is a simple JSON object that indicates whether or not the service call succeeded and contains the number of messages that are still marked as unseen. Here’s an example:

$ curl -sH "$AUTH_HEADER" -d '
{
    "uuids": [
        "C15763CF-A5C9-48F5-BE4F-9FB3CB1897EB"
    ]
}
' "http://by-tor:8888/secured/notifications/seen" | python -mjson.tool
{
    "count": 0
}

Note that the UUIDs provided in the request body must be obtained from the message -> id element of the notification the user wishes to mark as seen.

Marking All Notifications as Seen

Secured Endpoint: POST /secured/notifications/mark-all-seen

This endpoint is a passthrough to the notification agent’s /mark-all-seen endpoint. Please see the notification agent documentation for more information about the format of the request body.

This endpoint will add or overwrite the “user” field in the request body forwarded to the NotificationAgent with the username of the authenticated user making the request.

The response body for this service is a simple JSON object that indicates whether or not the service call succeeded and contains the number of messages that are still marked as unseen. Here’s an example:

$ curl -sH "$AUTH_HEADER" -d '{}' "http://by-tor:8888/secured/notifications/mark-all-seen" | python -mjson.tool
{
    "count": 0
}

Marking Notifications as Deleted

Secured Endpoint: POST /secured/notifications/delete

This endpoint is a passthrough to the notification agent’s /delete endpoint. Please see the notification agent documentation for more details.

Users may wish to dismiss notifications that they’ve already seen. This service marks one or more notifications as deleted so that neither the /notfications/messages endpoint nor the /notifications/unseen-messages endpoint will return them. The request body for this service is in the following format:

{
    "uuids": [
        "uuid-1",
        "uuid-2",
        "uuid-n"
    ]
}

The response body for this service is a simple JSON object that indicates whether or not the service call succeeded. Here’s an example:

$ curl -sH "$AUTH_HEADER" -d '
{
    "uuids": [
        "C15763CF-A5C9-48F5-BE4F-9FB3CB1897EB"
    ]
}
' "http://by-tor:8888/secured/notifications/delete"

Note that the UUIDs provided in the request body must be obtained from the message -> id element of the notification the user wishes to delete.

Marking All Notifications as Deleted

Secured Endpoint: DELETE /secured/notifications/delete-all

This endpoint is a passthrough to the notification agent’s /delete-all endpoint. Please see the notification agent documentation for more details.

This endpoint will add or replace the “user” parameter in the request forwarded to the NotificationAgent with the username of the authenticated user making the request.

The response body for this service is a simple JSON object that indicates whether or not the service call succeeded and contains the number of messages that are still marked as unseen. Here’s an example:

$ curl -X DELETE -sH "$AUTH_HEADER" "http://by-tor:8888/secured/notifications/delete-all" | python -mjson.tool
{
    "count": 0
}

Sending an Arbitrary Notification

Unsecured Endpoint: POST /send-notification.

This endpoint is a passthrough to the notification agent’s /notification endpoint. Please see the notification agent documentation for more details.

Endpoints for System Messages (a.k.a. System Notifications)

The endpoints for the system messages are straight pass throughs to the corresponding calls in the Notification Agent. The only difference is that the endpoints in Terrain are prefixed with /secured/notifications or /admin/notifications and that endpoints that require the user query string parameter instead take the authentication header.