Implementing a new message type

In order to implement a new message type, regardless of whether the message will be persisted or generated dynamically, the following must be done:

Common Tasks

Implementing a dynamic message

In order to implement a dynamic style message, an event listener needs to be implemented, to listen for the CitzenMessagesEvent.userRequestsMessages event. This event argument contains a reference to the Participant and a list, to which the listener will add curam.participantmessages.impl.ParticipantMessage java objects. For further details please consult the JavaDoc API for CitzenMessagesEvent. This can be found in <CURAM_DIR>/EJBServer/components/core/doc

Developers should also refer to the JavaDoc API for curam.participantmessages.impl.ParticipantMessage and curam.participantmessages.impl.ParticipantMessages for a full explanation.

The message text is stored in a properties file in the resource store. A dynamic listener will retrieve the relevant properties from the resource store, and create the ParticipantMessage object accordingly *. The message text for a given message can include placeholders. Values for placeholders are added to ParticipantMessage objects as parameters. The CitizenMessagesController will resolve these placeholders, replacing them with the real values related to the participant in question that have been added as parameters to the message object.

Take for example this entry from the CitizenMessageMyPayment.properties file:

Message.First.Payment=
  Your next payment is due on {Payment.Due.Date}

The actual payment due date of the payment in question will be added to the ParticipantMessage object as a parameter (see example code below). The CitizenMessagesController then resolves the placeholders, populating the text with real values, and then turns the message into XML that is rendered on the citizen account homepage (there is also a public CitizenMessageController method that will return all messages for a citizen as a list, please see the javadoc)

From curam.participantmessages.impl.ParticipantMessage API:

/**
 * Adds a parameter to the map. The paramReference
 * should be present in the message title or body so
 * it can be replaced by the paramValue before the message
 * is displayed.
 * 
 * @param paramReference
 * a string place holder that is present in either the 
 * message title or body. Used to indicate where the value 
 * parameter should be positioned in a message.
 
 * @param paramValue
 * the value to be substituted in place of the place holder
 */
 public void addParameter(final String paramReference, 
   final String paramValue) {
   
   parameters.put(paramReference, paramValue);
 }

The call to the method would look like this:

participantMessage.addParameter("Payment.Due.Date", "1/1/2011");

Messages can also include links. Similarly to placeholders, links are resolved at runtime. Links can use placeholder values as the text to be displayed for that link. A link is defined in a properties file as such:

Click {link:here:paymentDetails} to view the payment details.

In this example, "here" is the text to display, and "paymentDetails" refers to the name of the link that is to be inserted at that point in the text. Please see the Advisor Developer's Guide for more information. In order for a dynamic listener to populate this link with a target, it would create a curam.participantmessages.impl.ParticipantMessageLink object, specifying a target and a name for the link. The code would look like this:

ParicipantMessageLink participantMessageLink = 
     new ParticipantMessageLink(false, 
       "CitizenAccount_listPayments", "paymentDetails");
          
   participantMessage.addLink(participantMessageLink);

Before composing the message, the dynamic listener must check to ensure that the message type in question is currently enabled. The curam.participantmessages.configuration.impl.ParticipantMessageConfiguration record for that message type should be read, and the isEnabled method used to determine if this message type is enabled. If not, no further processing should occur.

* It is recommended to separate the code that listens for the event and the code that composes a specific message, in order to adhere to the philosophy of "doing one thing and doing it well".

Implementing a persisted message.

In order to have a persisted message displayed to the citizen, it must be written to the database via the curam.citizenmessages.persistence.impl.ParticipantMessage API. Message arguments are handled by persisting a curam.advisor.impl.Parameter record and associating it with the ParticipantMessage record, and links by the curam.advisor.impl.Link API. Parameter names should map to placeholders contained within the message text. Link names should relate to the names of links specified in the message text. Please refer to the javadoc of curam.citizenmessages.persistence.impl.ParticipantMessage, curam.advisor.impl.Parameter and curam.advisor.impl.Link for more information.

An expiry date time must be specified for each ParticipantMessage. After this date time, the message will no longer be displayed.

Messages can be removed from the database. If a message needs to be replaced with a with a modified version, or removed for another reason, this can be done via the curam.citizenmessages.persistence.impl.ParticipantMessage API.

Each message has a related ID and type. This is used to track the record that the message is related to. For example, meeting messages will store the Activity ID and a type of "Meeting". Messages can be read by participant, related ID and type via the ParticipantMessageDAO.

Before persisting the message, the dynamic listener must check to ensure that the message type in question is currently enabled. The curam.participantmessages.configuration.impl.ParticipantMessageConfiguration record for that message type should be read, and the isEnabled method used to determine if this message type is enabled. If not, no further processing should occur.

Parent topic: My Messages