Page Tree:

Child pages
  • Notification Service Contract Description v0.8 - BDOC

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin




Wiki Markup





Table of Contents

Brief description


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.

Overview and Definitions

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:

  1. Dissemination of broadcast messages. This functionality is invokable through the service's RESTful API.
  2. Dissemination of messages on a topic to registered subscribers. This functionality is invoked through the service's SOA API, a Java interface.

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:

  1. Create a new topic, providing a topic name and an expiration date
  2. Subscribe one or more notification consumers to the topic and one or more situations for which the consumer is to receive notifications (situations may be any strings the client service chooses; examples might include "start", "complete", "error", etc.)
  3. Initiate message dissemination prior to the topic expiration date, one or more times, by creating a new situation for the topic

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.


  • Only e-mail notifications are currently supported.
  • The Notification Service does not guarantee delivery of messages
  • Services are expected to initiate message dissemination (create situations) only for topics they have created, or for which the creating service has passed a topic identifier.

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.


Known Issues

  1. There is no method exposed to DELETE a notification consumer from a topic / situation. This functionality may be added in a future release of the Notification Service, if/as required.


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.

Base URLs

Excerpt Include
Web Service API Base URLs - CURRENT - BDOC
Web Service API Base URLs - CURRENT - BDOC



A client sends a message to one or more Bamboo Person, Group, and/or e-mail addresses by creating a Notification.

Create a Notification

Calling Method and Arguments

Invoked as an HTTP POST method. Send an HTTP request of the form:

Code Block
POST /bsp/notifications HTTP/1.1

At a minimum, the Broadcast XML document must contain:

  • The Bamboo Person Identifier of the person sending the broadcast in the publisherId element
  • A text string in the message element
  • At least one notification consumer | email in their respective elements




An instance of a Broadcast XML document

The Broadcast XML document should be of the form:

Code Block
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    xmlns:xsi="" >
  <bsp:topicName>Hello from the 16th Century</bsp:topicName>
  <bsp:message>Can you believe the technology nowadays?</bsp:message>


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:

Code Block
Return-Path: <>
Received: [...]
Received: from (localhost.localdomain [])
    by (8.14.4/8.14.4) with ESMTP id
    q6JKjdui020227 for <>;
    Thu, 19 Jul 2012 16:45:45 -0400
Date: Thu, 19 Jul 2012 16:45:39 -0400
Message-ID: <>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
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)


Returned When


Bad Request

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.

Create a new Topic

Code Block
 * 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);

Subscribe a Notification Consumer to a Topic (passing identifier for consumer)

Code Block
 * 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);

Subscribe a Notification Consumer to a Topic (passing e-mail address for consumer)

Code Block
 * 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);

Create a new Situation for a Topic

Code Block
 * 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);