Navigation:
Documentation
Archive



Page Tree:

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

Versions Compared

Key

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

Contract:

 

 

Wiki Markup
{multi-excerpt:name=serviceName}Notification{multi-excerpt}

 

 

Service

 

Table of Contents
maxLevel3
minLevel1

Brief description

Version

This page describes the Notification service API, version 0.8

Note

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.

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 page of Project Bamboo's development wiki.

References

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

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

Schema

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:

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

Parameter

Meaning

HTTP Body

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"?>
<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:

Code Block
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:

Error (Status Code)

Meaning

Returned When

400

Bad Request

If the broadcast XML content is invalid or missing

401

Unauthorized

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

500

Internal Server Error

A service error prevented the resource from being returned

SOA Layer API

Notification Service API for publish/subscribe patterned notifications.

Note

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