Server Message API
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.
WebUIInitializer
API.ServerMessageWebUIInitializer
extension has been added to facilitate this.
The item model being used to host server message is the ChangeEvent
item model defined in
/com.ibm.team.repository.common/models/repository.ecore
.
Column | Type | Description |
---|---|---|
eventState | UUID | Not used. |
eventContext | IContext | IContext. |
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. |
eventCategory | EString | |
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.
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.
Retrieves all server messages in the repository.
[
{
Name | Type | Default | Example | Description |
---|---|---|---|---|
includeArchived | ?activeOnly | Show only currently-active messages (i.e. messages currently being displayed). | ||
maxCount | 10 |
?maxCount=5 | Limit the number of messages returned. | |
subType | String |
?subType=foo | Show only messages with the specified sub-type |
Status | Comment |
---|---|
200 OK | If the messages were successfully retrieved. |
Returns the currently-active messages in the repository.
This service is used by the ServerMessageWebUIInitializer
class to propagate messages to
applications and clustered nodes.
{
Status | Comment |
---|---|
200 OK | If the messages were successfully retrieved. |
304 Not Modified | If the If-Modified-Since request header value is after the createTime value. |
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.
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.
Retrieves a single server message by it's itemId
identifier.
Status | Comment |
---|---|
200 OK | If the message was successfully retrieved. |
404 Not Found | If the message with the specified ID was not found. |
Creates a new server message.
{
Status | Comment |
---|---|
302 Found | Redirects to the URL of the new server message by setting the Location HTTP response header. |
Messages with startDate
values will never activate unless modified.
Messages with endDate
values will never deactivate once activated unless modified or deleted.
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.
Overwrites an existing message.
Same syntax as POST /jazz/serverMessages
Status | Comment |
---|---|
200 OK | Returns the contents of the updated message. |
404 Not Found | Server message with specified ID not found. |
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}
Deletes all server messages.
Status | Comment |
---|---|
200 OK | If all messages were successfully deleted. |
Deletes a single message.
Status | Comment |
---|---|
200 OK | If the message was successfully deleted. |
404 Not Found | If the message with the specified ID was not found. |
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
:
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:
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.