Server Message API

Table of Contents
  1. Description

  2. Internal Design

    1. Item Model

    2. ServerMessageRestService

      1. GET /jazz/serverMessages

      2. GET /jazz/serverMessages/active

      3. GET /jazz/serverMessages/{UUID}

      4. POST /jazz/serverMessages

      5. PUT /jazz/serverMessages/{UUID}

      6. DELETE /jazz/serverMessages

      7. DELETE /jazz/serverMessages/{UUID}

      8. CANCEL /jazz/serverMessages/{UUID}

    3. ServerMessageWebUIInitializer

1 - Description

The Server Message API, introduced in v4.0.3, provides a way to broadcast system-wide messages to the web UI of all users of all applications.

Examples include:

When active, server messages show up in the title bar in the web user interfaces of the Jazz Team Server web application and registered applications.

Notes:

2 - Internal Design

2.1 - Item Model

The item model being used to host server message is the ChangeEvent item model defined in /com.ibm.team.repository.common/models/repository.ecore.

ColumnTypeDescription
eventState UUID Not used.
eventContext IContext IContext.PUBLIC
eventOwnerNS EString Not used.
eventTime Timestamp Start time for event (when it starts being rendered in the UI).
eventAuthor Contributor The person who created the message.
eventPriority String The severity level of the message (i.e. "INFO", "WARNING", "SEVERE").
eventCategory EString "ServerMessage"
eventTitle EString (SMALL) Not used.
eventDescription EString (LARGE) Message contents. Can be HTML.
eventPriority EString Not used.
eventContributors Contributor[] Not used.
eventProcessArea Auditable Not used.
eventExpiration Timestamp Expiration time for event (when it ends being rendered in the UI).
item IItem Not used.

Note that since we're piggy-backing on the change-event model, we don't have to implement a separate process for cleaning up expired messages from the repository.

2.2 - ServerMessageRestService

The server message service is defined by the IServerMessageRestService interface.
It is accessible at the following URL:

/jts/serverMessages

The service is a {@link com.ibm.team.repository.service.JazzRestResource} REST service.

When visiting the resource with a browser, you are presented with existing messages in HTML format:

The REST service also produces JSON and XML. For testing convenience, the &accept=x and &plainText=true parameters can be used to test these out in a browser.

JSON...

XML...

Simplified XML...

The options link from the HTML view brings up an OPTIONS page that can be used as a quick cheatsheet on the various HTTP methods available on the service.

2.2.1 - GET /jazz/serverMessages

Retrieves all server messages in the repository.

Response (in JSON)

[ { "uri": URI // The URI of the message "itemId": UUID, // The item UUID of the message "level": String, // The severity level of the message "contributorId": String, // The UUID of the author of the message "contributorUserId": String, // The shortname of the author of the message "description": String, // The message text "subType": String, // The message subtype "startDate": String, // The message start time (in ISO8601 datetime format, GMT) "endDate": String // The message end time(in ISO8601 datetime format, GMT) } ]

Optional query parameters
NameTypeDefaultExampleDescription
includeArchived ?activeOnly Show only currently-active messages (i.e. messages currently being displayed).
maxCount int 10 ?maxCount=5 Limit the number of messages returned.
subType String null ?subType=foo Show only messages with the specified sub-type
Possible response status
StatusComment
200 OK If the messages were successfully retrieved.

2.2.2 - GET /jazz/serverMessages/active

Returns the currently-active messages in the repository.

This service is used by the ServerMessageWebUIInitializer class to propagate messages to applications and clustered nodes.

Response (in JSON)

{ "createTime": // The timestamp of when this message cache was created (in ISO8601 datetime format, GMT) "expireTime": // The timestamp when this cache expires (in ISO8601 datetime format, GMT) "items":[ { "uri": URI // The URI of the message "itemId": UUID, // The item UUID of the message "level": String, // The severity level of the message "contributorId": String, // The UUID of the author of the message "contributorUserId": String, // The shortname of the author of the message "description": String, // The message text "subType": String, // The message subtype "startDate": String, // The message start time (in ISO8601 datetime format, GMT) "endDate": String // The message end time(in ISO8601 datetime format, GMT) "active": Boolean // Whether this message is currently active } ] }

Example response
Possible response status
StatusComment
200 OK If the messages were successfully retrieved.
304 Not Modified If the If-Modified-Since request header value is after the createTime value.
Notes

The expireTime setting is the time when this list of active messages will change if no other external message changes are made. This takes into account the endDate values of all messages currently on the list in addition to the startDate values of all future messages.

N-1 Compatibility

Pre-v4.0.3 applications connected to JTS v4.0.3+ get a backwards-compatible version of the active messages containing dates as UTC long values. This can be simulated in a browser by adding ?X-com-ibm-team-configuration-versions=com.ibm.team.jazz.foundation=4.0.2 to the URL.

2.2.3 - GET /jazz/serverMessages/{UUID}

Retrieves a single server message by it's itemId identifier.

Example response
Possible response status
StatusComment
200 OK If the message was successfully retrieved.
404 Not Found If the message with the specified ID was not found.

2.2.4 - POST /jazz/serverMessages

Creates a new server message.

Request body content (in JSON)

{ "level": String, // The severity level of the message ("INFO", "WARNING", "SEVERE") "description": String, // The message text "subType": String, // An optional subcategory string "startDate": String, // The message start time (in ISO8601 datetime format). Can be null. "endDate": String // The message end time (in ISO8601 datetime format). Can be null. }

Possible response status
StatusComment
302 Found Redirects to the URL of the new server message by setting the Location HTTP response header.
Notes

Messages with null startDate values will never activate unless modified.

Messages with null endDate values will never deactivate once activated unless modified or deleted.

Example

You can simulate a POST in a browser using the following URL:

https://localhost:9443/jazz/serverMessages?method=POST&content={description:'My%20message',level:'INFO',startDate:'2013-01-01T12:34:56Z',endDate:'2014-01-01T12:34:56Z'}

The automatic redirection takes you to the new message.

2.2.5 - PUT /jazz/serverMessages/{UUID}

Overwrites an existing message.

Same syntax as POST /jazz/serverMessages

Possible response status
StatusComment
200 OK Returns the contents of the updated message.
404 Not Found Server message with specified ID not found.
Example

You can simulate a PUT in a browser using a URL similar to the following:

https://localhost:9443/jazz/serverMessages/_ahiWYKEuEeKeT6VkzvMbHA?method=PUT&content={description:'My updated message',level:'INFO',startDate:'2013-01-01T12:34:56Z',endDate:null}

2.2.6 - DELETE /jazz/serverMessages

Deletes all server messages.

Possible response status
StatusComment
200 OK If all messages were successfully deleted.

2.2.7 - DELETE /jazz/serverMessages/{UUID}

Deletes a single message.

Possible response status
StatusComment
200 OK If the message was successfully deleted.
404 Not Found If the message with the specified ID was not found.

2.2.8 - CANCEL /jazz/serverMessages/{UUID}

Cancels a currently-active message by setting the endDate to the current time.

Since CANCEL is not a standard HTTP method, it can be invoked as an overloaded GET:

2.3 - ServerMessageWebUIInitializer

Server messages are exposed to the web UI through the existing WebUIInitializer API which is used to send page initialization data on every page request through an AJAX call to the following service...
/jazz/service/com.ibm.team.repository.service.internal.webuiInitializer.IWebUIInitializerRestService/initializationData.

The following is an example of the JSON object contributed by the ServerMessageWebUIInitializer class:

"com.ibm.team.repository.service.compatibility.util.serverMessages": { "identifier": "itemId", "items": [ { "contributorId": "_zP_coJleEd-joaYjvz6g2w", "contributorUserId": "ADMIN", "description": "active message", "level": "INFO", "endDate": 1577854800000, "itemId": "_qpVhgANbEeKo8sN9ZyksVA", "startDate": 1262322000000 } ], "label": "description" },

The ServerMessageWebUIInitializer service runs on both the JTS and on 0.6-style applications.
When running on the JTS, it pulls server messages directly from ServerMessageRestService.
When running on 0.6-style applications, it maintains a cache with a 60-second timeout. Therefore, on applications, server messages may not appear for up to 60 seconds after they start appearing on the JTS admin web UI.