Brief description

Version

This page describes the Notification service API, version 0.9

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 fuller description can be found on the Notification Service Description and Assumptions - v0.9-alpha page of this wiki (a child to this page).

Assumptions

• 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 - v0.9-alpha page of this wiki (a child to this page).

References

• Publish-Subscribe Wikipedia entry
• Publish-Subscribe Enterprise Integration pattern
• Codebase: ${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/utility-services/notification-service/

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.

ROA Layer API

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

Client Responsibilities in Requests to Secured BSP Web Services

(1) A client must be configured as a Trusted Application if requests are to be treated other than as Anonymous

A client application – whether a web app or a simple testing client such as Firefox Poster or curl – may make requests anonymously or as a "Trusted Application." Only a Trusted Application may assert the identity of a user on behalf of whom the request is made, and scoped roles to be assigned to that user; Bamboo Services trust such clients to assert the identity and assigned-roles only of users who have authenticated in the current session of application activity. (A special-case type of client application, termed Innovation Licensed applications, are trusted to assert the identity of and roles assigned to a fixed set of special-case users without those users having to authenticate in the current session.)

Configuration of client applications are described in detail in this wiki page: Configure Apache Web Server for Client Auth. It is assumed in #2, below, that this configuration has been performed.

(2) A Trusted client is expected to pass HTTP Request Headers to identify itself and an authenticated user

A client application that is Trusted in the security context of the Bamboo Trust Federation (cf. Identity and Access Management - Authentication and Authorization) must augment each request to a service hosted by a secured instance of the Bamboo Services Platform (BSP) with a set of HTTP headers, as follows:

• X-Bamboo-AppID: A UUID that identifies the client research environment, application, tool, or service; this UUID is issued as part of the process of registering a trusted client in the Bamboo Trust Federation as described in overview on the page Identity and Access Management - Authentication and Authorization; and in detail with respect to physical establishment of trust on the page Configure Apache Web Server for Client Auth. The value of this header is linked to the X.509 certificate by which the application establishes an SSL connection to the BSP host in the registration process, and a match between this Application ID and the linked X.509 certificate is checked by the BSP on receipt of every request.

• X-Bamboo-BPID: A UUID that identifies the logged-in user on whose behalf the request is being sent; this value, a Bamboo Person Identifier, or BPId, is obtained via a call to the Person Service that occurs in time between user login and any other service request. See the Read a BambooPersonId method of the Person Service API for details. [^†]
• X-Bamboo-Roles: A pipe-delimited (|) set of scoped roles asserted by the trusted client to belong to the logged-in user, of the form role@domain, which are to be evaluated as factors in the determination of whether the request satisfies policies (access restrictions) that apply to the requested resource. If a user is authenticated, the client is expected to include the role undefined@domain where domain identifies the organization that authenticated the user (example: undefined@google.com is a client app's assertion that the user authenticated to Google). This header is otherwise optional (depending on policies governing the requested resource that may require one or more scoped roles for access to be permitted). Example of multiple roles asserted in this header: roleA@domainOne.xxx|roleB@domainTwo [^‡]

[^†] The value of X-Bamboo-BPID is set to the identifier for the application itself (X-Bamboo-AppID) when a client application calls the Person Service to create a new Bamboo Person Identifier; or to retrieve the BPId for a user based on the identifier of the IdP with which she has logged in and an SHA-256 hash of that IdP's user identifier for the logged-in person.

[^‡] Policies and policy evaluation are described on the page Authorization and Policy. Also see Conventions for representing Identity Providers in the Bamboo Trust Federation.

Schema

• ${REPOSITORY_ROOT}/platform-services/bsp/trunk/bsp/utility-services/notification-service/domain/src/main/resources/Notification.xsd

Notification

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:

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

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>collab-admin@lists.projectbamboo.org</bsp:notificationEmail>
 </bsp:notificationEmails>
</bsp:broadcast>

Response

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: <collab-admin-bounces@lists.projectbamboo.org>
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 <collab-admin@lists.projectbamboo.org>;
    Thu, 19 Jul 2012 16:45:45 -0400
Date: Thu, 19 Jul 2012 16:45:39 -0400
From: notification-service@projectbamboo.org
To: collab-admin@lists.projectbamboo.org
Message-ID: <1977225133.4.1342730739886.JavaMail.smx@bsp-qa.projectbamboo.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
[...]
Sender: collab-admin-bounces@lists.projectbamboo.org
Errors-To: collab-admin-bounces@lists.projectbamboo.org
 
Can you believe the technology nowadays?

Exceptions

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:

SOA Layer API

Notification Service API for publish/subscribe patterned notifications.

Also see generated Javadoc for this service. Packages are org.projectbamboo.bsp.services.utility.notification.*.

Create a new Topic

/**
 * 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)

/**
 * 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)

/**
 * 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

/**
 * 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);