|Table of Contents|
This page describes the Notification service API, version 0.8
To discover the version and other metadata about deployed service code that fulfills this API, please utilize the Service Catalog Service - BDOC.
The Notification service executes requests to notify individuals and groups in accordance with access permissions and user-expressed communication preferences. The service has two types of usage:
Notifications are disseminated in all cases as e-mail messages. (Additional messaging modalities may be added to the Notification Service in the future, if and as required.)
Broadcast messages are sent when an authorized client directs a POST request to the service endpoint, as documented below. An XML document in the body of the post determines the content of the message and its recipient(s).
Topical messages are initiated by other services as clients to the Notification Service. The Notification Service disseminates messages (Notifications) to registered subscribers (Notification Consumers). Notifications are aggregated in Topics. A Topic has a lifetime, set on its creation by setting of an expiry date. A Topic may have a lifecycle that includes multiple messages of different types; a message type is described in this API as a Situation.
The general process is as follows:
This process is invoked via the Notification Service's SOA interface.
A full description can be found on the Notification Service Description and Assumptions page of Project Bamboo's development wiki.
For a fuller and more formal set of assumptions about this service, visit the Notification Service Description and Assumptions page of Project Bamboo's development wiki.
The RESTful service method exposed for the Notification Service permits a RESTful client to Create a Notification, i.e., to send a message to a specified set of Bamboo Persons and/or supplied e-mail addresess.
A client sends a message to one or more Bamboo Person, Group, and/or e-mail addresses by creating a Notification.
Invoked as an HTTP POST method. Send an HTTP request of the form:
POST /bsp/notifications HTTP/1.1
At a minimum, the Broadcast XML document must contain:
An instance of a Broadcast XML document
The Broadcast XML document should be of the form:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <bsp:broadcast xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:bsp="http://projectbamboo.org/bsp/Notification" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > <bsp:notification> <bsp:publisherId>urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b</bsp:publisherId> <bsp:topicName>Hello from the 16th Century</bsp:topicName> <bsp:message>Can you believe the technology nowadays?</bsp:message> </bsp:notification> <bsp:notificationConsumers> <bsp:notificationConsumer>urn:uuid:5230724c-1e47-49c1-b947-a965dbeeef5b</bsp:notificationConsumer> </bsp:notificationConsumers> <bsp:notificationEmails> <bsp:notificationEmail>firstname.lastname@example.org</bsp:notificationEmail> </bsp:notificationEmails> </bsp:broadcast>
On success, a response with a "200 OK" HTTP status code will be returned. The above Broadcast XML document generates the following e-mail message:
Return-Path: <email@example.com> Received: [...] Received: from bsp-qa.projectbamboo.org (localhost.localdomain [127.0.0.1]) by bsp-qa.projectbamboo.org (8.14.4/8.14.4) with ESMTP id q6JKjdui020227 for <firstname.lastname@example.org>; Thu, 19 Jul 2012 16:45:45 -0400 Date: Thu, 19 Jul 2012 16:45:39 -0400 From: email@example.com To: firstname.lastname@example.org Message-ID: <1977225133.4.1342730739886.JavaMail.email@example.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit [...] Sender: firstname.lastname@example.org Errors-To: email@example.com Can you believe the technology nowadays?
If an error occurred, some non-2xx code will be returned. Check the HTTP Status Code that is returned in the response's HTTP headers for the specific error. The following errors may be returned in response to the POST request:
Error (Status Code)
If the broadcast XML content is invalid or missing
The requestor is not authorized to publish notifications because the client submitting the request either has not provided authentication credentials, or authentication failed, or authorization has been refused for those credentials
Internal Server Error
A service error prevented the resource from being returned
Notification Service API for publish/subscribe patterned notifications.
Javadoc will be linked once it is generated and published. In the meantime, the API is provided in the form of Javadoc annotations.
/** * Creates a new <code>Topic</code>. * * @param publisherId - identifier of the Publisher * @param topic - name of the Topic * @param expiry - date on which the Topic will expire * @return identifier of the Topic * @throws <code>IllegalStateException</code> if the Topic does not exist */ UUID registerTopic(URI publisherId, String topic, Date expiry);
/** * Subscribes a Notification Consumer to a Topic. * * @param topicId - identifier of the Topic to which to subscribe * @param notificationConsumer - Notification Consumer subscribing to the Topic * @param situation - value which will trigger the notification * @throws <code>IllegalStateException</code> if the Topic does not exist */ void subscriptionRequest(UUID topicId, NotificationConsumer notificationConsumer, String situation);
/** * Subscribes a Notification Consumer to a Topic using the * provided <code>NotificationChannel</code>. * * @param topicId - identifier of the Topic to which to subscribe * @param emailAddress - <code>NotificationChannel</code> to use when subscribing to the Topic * @param situation - value which will trigger the notification * @throws <code>IllegalStateException</code> if the Topic does not exist */ void subscriptionRequest(UUID topicId, String emailAddress, String situation);
/** * Creates a new Situation for a Topic. * * @param topicId - identifier of the Topic * @param situation - value which triggers notifications; "ALL" will match any situation * @param message - content which will be disseminated as part of a Notification * @throws <code>IllegalStateException</code> if the Topic does not exist */ void publishSituation(UUID topicId, String situation, String message);