Oracle User Messaging Service: Implementing custom messaging channels

Oracle User Messaging Service or UMS enables two-way communication between applications and users. There is support for a variety of messaging channels like email, IM, SMS and voice. Another option is to deliver messages to a user’s work list.

With UMS messaging preferences users can define how and when they want to receive message notifications. They can define filter criteria to only receive messages they are interested in. Applications can send messages to a user respecting their preferences or send messages over a specific channel.

In addition to the default channels, organisations can define custom channels using the Messaging Extension Driver. Messages for such channels are then delivered to a web service listener endpoint. This web service implements the actual delivery of the notification for that specific channel.

In this blog I’ll show the steps needed to send messages through a custom channel: 1) Implementing the Message Notify Service interface 2) Configuring the Messaging Extension Driver 3) Adding the channel to your user's message channels 4) Sending messages

Implementing the Message Notify Service interface

To be able to use the web service in the Messaging Extension Driver of UMS it should implement the Messaging Notify Service WSDL. The content of this WSDL is listed in the Admin guide here.

To quickly implement the service Message Notify Service interface I created a SOA composite that puts the contents of the notification message in a file using the File Adapter as illustrated above.

Configuring the Message Extension Driver

By default an instance of the usermessagingdriver-extension application is deployed but not targeted to any servers. To enable the driver, use the Administration Console to target it to the servers where UMS is running.

To configure the driver navigate to the usermessagingserver home page in the Enterprise Manager. Click User Messaging Service > Driver Properties. Select and Edit the driver usermessagingdriver-extension.

Under Driver-Specific Configuration, add a new extension endpoint configuration group and specify the correct properties:

• Group: CUSTOM
• Endpoint URL: http://localhost:8001/soa-infra/services/default/MessageNotifyService/MessageNotifyService
• Protocol: CUSTOM

Click OK to save the configuration.

Adding the channel to your user's message channels

To be able to receive messages over the custom channel, it must be added to your user’s messaging channels using the UMS preferences UI.

Login at http://localhost:8001/sdpmessaging/userprefs-ui with your user credentials and create a new messaging channel with the following properties:

• Name: My custom channel
• Type: CUSTOM
• Address: nico
• Set a default channel: true

The address is your unique user address for the custom channel similar to your email address. By setting the default property the channel will also be used to deliver messages that were sent to you based on user preferences.

Notice the warning at the bottom of the popup. The Notification Service used by the BPEL User Notification activity and Human Workflow is based on UMS. Unfortunately this service only supports the default channels where the user's channel address like email or phone number is fixed to the information stored in the identity management system.

Sending messages

To send messages with support for all channels UMS we have to use UMS directly using one of the  multiple UMS APIs. These include an EJB API, a plain Java API and a Web Service API . In this example we will use the Web Service API as documented here.

In JDeveloper create a new Java project and add the following libraries:

• Web Service Data Control
• BC4J Security
•  JAX-RPC Client

and add the following JAR files:

• sdpmessagingclient.jar
•  sdpmessagingcommon.jar
•  Oracle.http_client_11.1.1.jar
• Oracle.logging-utils_11.1.1.jar

Create a new instance of the messaging client using the following code snippet:

HashMap<String, Object> config = new HashMap<String, Object>();

 

config.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,"http://localhost:8001/ucs/messaging/webservice");      

config.put(ClientConstants.POLICIES, new String[]{});

config.put(SecurityConstants.Config.CLIENT_CREDS_LOCATION,

  SecurityConstants.Config.CLIENT_CREDS_LOC_SUBJECT);

config.put(MessagingConstants.APPLICATION_NAME,"usermessagingsample-ws");

MessagingClient mClient = new MessagingClient(config); 

And send a message to a user using the custom channel:
       

Message message = MessagingFactory.createTextMessage("You received a message");

message.setSubject("Message over custom channel");

message.getRecipients().add(MessagingFactory.createAddress("CUSTOM:nico"));

mClient.send(message, null,null);

That's it! There should be a new instance of your Message Notify Service composite delivering the message to a file on your server.

To send a message to a user based on his preferences set the address as following:

message.getRecipients().add(MessagingFactory.createAddress("USER:nico"));

Now not only the custom channel is used to deliver the message but also the other channels marked as default like the email channel for example.

Resources

• Administrator's Guide for Oracle SOA Suite and Oracle Business Process- Configuring Oracle User Messaging Service
• Sending and Receiving Messages using the User Messaging Service Web Service API