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.
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.
- Group: CUSTOM
- Endpoint URL: http://localhost:8001/soa-infra/services/default/MessageNotifyService/MessageNotifyService
- Protocol: CUSTOM
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.
- 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
- 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:
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.
