11 Configuring Oracle User Messaging Service

This chapter describes how to configure Oracle User Messaging Service (UMS).

This chapter includes the following topics:

• Section 11.1, "User Messaging Service Overview"

• Section 11.2, "Introduction to Oracle User Messaging Service Configuration"

• Section 11.3, "Accessing User Messaging Service Configuration Pages"

• Section 11.4, "Configuring User Messaging Service Drivers"

• Section 11.5, "Securing User Messaging Service"

11.1 User Messaging Service Overview

Oracle User Messaging Service enables two-way communication between users and deployed applications. Key features include:

• Support for a variety of messaging channels—Messages can be sent and received through Email, IM (XMPP), SMS (SMPP), and Voice. Messages can also be delivered to a user's SOA/WebCenter Worklist.

• Two-way Messaging—In addition to sending messages from applications to users (referred to as outbound messaging), users can initiate messaging interactions (inbound messaging). For example, a user can send an email or text message to a specified address; the message is routed to the appropriate application which can then respond to the user or invoke another process according to its business logic.

• User Messaging Preferences—End users can use a web interface to define preferences for how and when they receive messaging notifications. Applications immediately become more flexible; rather than deciding whether to send to a user's email address or instant messaging client, the application can simply send the message to the user, and let UMS route the message according to the user's preferences.

• Robust Message Delivery—UMS keeps track of delivery status information provided by messaging gateways, and makes this information available to applications so that they can respond to a failed delivery. Or, applications can specify one or more failover addresses for a message in case delivery to the initial address fails. Using the failover capability of UMS frees application developers from having to implement complicated retry logic.

• Pervasive integration within Fusion Middleware: UMS is integrated with other Fusion Middleware components providing a single consolidated bi-directional user messaging service.

  • Integration with Oracle BPEL—Oracle JDeveloper includes pre-built BPEL activities that enable messaging operations. Developers can add messaging capability to a SOA composite application by dragging and dropping the desired activity into any workflow.

  • Integration with Oracle Human Workflow—UMS enables the Human Workflow engine to send actionable messages to and receive replies from users over email.

  • Integration with Oracle BAM—Oracle BAM uses UMS to send email alerts in response to monitoring events.

  • Integration with Oracle WebCenter—UMS APIs are available to developers building applications for Oracle WebCenter Spaces. The API is a realization of Parlay X Web Services for Multimedia Messaging, version 2.1, a standard web service interface for rich messaging.

11.1.1 Components

There are three types of components that make up Oracle User Messaging Service. These components are standard Java EE applications, making it easy to deploy and manage them using the standard tools provided with Oracle WebLogic Server.

• UMS Server: The UMS Server orchestrates message flows between applications and users. The server routes outbound messages from a client application to the appropriate driver, and routes inbound messages to the correct client application. The server also maintains a repository of previously sent messages in a persistent store, and correlates delivery status information with previously sent messages.

• UMS Drivers: UMS Drivers connect UMS to the messaging gateways, adapting content to the various protocols supported by UMS. Drivers can be deployed or undeployed independently of one another depending on what messaging channels are available in a given installation.

• UMS Client applications: UMS client applications implement the business logic of sending and receiving messages. A UMS client application might be a SOA application that sends messages as one step of a BPEL workflow, or a WebCenter Spaces application that can send messages from a web interface.

In addition to the components that make up UMS itself, the other key entities in a messaging environment are the external gateways required for each messaging channel. These gateways are not a part of UMS or Oracle WebLogic Server. Since UMS Drivers support widely-adopted messaging protocols, UMS can be integrated with existing infrastructures such as a corporate email servers or XMPP (Jabber) servers. Alternatively, UMS can connect to outside providers of SMS or text-to-speech services that support SMPP or VoiceXML, respectively.

11.1.2 Architecture

The system architecture of Oracle User Messaging Service is shown in Figure 11-1.

For maximum flexibility, the components of UMS are separate Java EE applications. This allows them to be deployed and managed independently of one another. For example, a particular driver can be stopped and reconfigured without affecting message delivery on all other channels.

Exchanges between UMS client applications and the UMS Server occur as SOAP/HTTP web service requests for web service clients, or through Remote EJB and JMS calls for BPEL messaging activities. Exchanges between the UMS Server and UMS Drivers occur through JMS queues.

Oracle UMS server and drivers are installed alongside SOA or BAM in their respective WebLogic Server instances. A WebCenter installation will include the necessary libraries to act as a UMS client application, invoking a server deployed in a SOA instance.

Figure 11-1 UMS architecture

Description of "Figure 11-1 UMS architecture"

11.2 Introduction to Oracle User Messaging Service Configuration

Oracle User Messaging Service enables users to receive notifications sent from SOA applications that are developed and deployed to the Oracle WebLogic Server using Oracle JDeveloper.

At the application level, there is notification activity for a specific delivery channel (such as SMS or E-Mail). For example, when you build a SOA application that sends e-mail notification, you drag and drop an Email Activity component from the JDeveloper Component Palette to the appropriate location within a workflow. The application connects then sends notifications.

For more information about Oracle JDeveloper, see your JDeveloper documentation.

Figure 11-2 shows a user adding an Email Activity to the BPEL process of a SOA composite application.

Figure 11-2 Setting the Notification Activity in the BPEL Workflow

Description of "Figure 11-2 Setting the Notification Activity in the BPEL Workflow"

To enable the workflow participants to receive and forward notifications, use Oracle 11g Enterprise Manager to set the Oracle User Messaging Service environment by configuring the appropriate driver instances that reside on the same Oracle WebLogic Server on which you deploy the workflow application (Figure 11-3). Oracle User Messaging Service includes drivers that support messaging through E-Mail, IM, SMS and voice channels. For more information, see Section 11.4, "Configuring User Messaging Service Drivers".

Figure 11-3 Oracle Enterprise Manager 11g Fusion Middleware Control

Description of "Figure 11-3 Oracle Enterprise Manager 11g Fusion Middleware Control"

In order for workflow participants to actually receive the notifications, they must register the devices that they use to access messages through User Messaging Preferences (Figure 11-4).

Figure 11-4 User Messaging Preferences

Description of "Figure 11-4 User Messaging Preferences"

11.3 Accessing User Messaging Service Configuration Pages

You configure User Messaging Service through Oracle Enterprise Manager Fusion Middleware Control. For more information on Oracle Enterprise Manager, see your Oracle Enterprise Manager documentation.

11.3.1 How to Set the Storage Method

Use the Basic Configuration page to set deployment type for the Messaging Server (that is, select the storage method for run time and management data) and add (or remove) the User Messaging Preference Business Terms that are used for creating message filters.

Select Persistent (the default) to enable entries and the Messaging Store to persist when the server has been restarted. In the Transient mode (which is recommended for lightweight deployments), the Messaging Server does not maintain any data stored in the Messaging Store after a restart.

11.3.2 How to Add or Remove User Messaging Preferences Business Terms

The Basic Configuration page enables you to add or remove the business terms used to construct the message filters in User Message Preferences. For more information about building messaging filters with business terms, refer to Adding Business Terms.

11.3.2.1 Adding Business Terms

Note:

Business Terms are stored per server instance. If there are multiple instances (as in a cluster), then new business terms must be added to each instance individually.

To add a business term to User Messaging Preferences:

1. Click Add.

2. Enter a descriptive name for the business term.

3. Select a data type (string, number, or date).

4. Click Apply.

11.3.2.2 Removing Business Terms

To remove a business term from User Messaging Preferences:

1. Select the business term.

2. Click Delete.

3. Click Apply to confirm the new term.

11.4 Configuring User Messaging Service Drivers

Oracle User Messaging Service includes the following drivers.

• E-Mail Driver

• SMPP Driver

• XMPP Driver

• Worklist Driver

• Proxy Driver

Note:

For the cluster env, when you use separate messaging drivers for separate managed server nodes, all the drivers must be configured separately.

UMS Messaging Drivers are configured per instance. Configuring only one does not populate the configuration values to the drivers on the other cluster nodes.

11.4.1 How to Configure a Driver

To configure a driver:

1. Log into the Enterprise Manager Fusion Middleware Control console as an administrator.

2. Expand the Fusion Middleware folder (Figure 11-5).

   Figure 11-5 Expanding the UMS Folder

   
   Description of "Figure 11-5 Expanding the UMS Folder"
   
   

3. Navigate to the User Messaging Service Home page.

4. Click usermessagingserver(soa_server1). The Associated Drivers page appears.

   Figure 11-6 Drivers Associated with the UMS Instance

   
   Description of "Figure 11-6 Drivers Associated with the UMS Instance"
   
   

5. Select the Local tab to access the drivers collocated with the UMS server instance. These drivers may or may not be registered with the UMS server depending on whether or not they are properly configured. The ALL tab lists all drivers that are deployed in the domain and registered to all the UMS server instances.

6. Find the Email driver in the list, and then click the adjacent Configure Driver icon.

   The configuration page displays (Figure 11-7).

   Figure 11-7 The Basic Configuration Page for a Selected Driver

   
   Description of "Figure 11-7 The Basic Configuration Page for a Selected Driver"
   
   

7. If needed, expand the Driver-Specific Configuration section and configure the driver parameters. For more information, see Section 11.4.1.1, "About Driver Properties".

11.4.1.1 About Driver Properties

Oracle User Messaging Service drivers share common properties (listed in Table 11-1) that are used by the Messaging Engine when routing outbound messages. Typically, administrators set such Quality of Service (QoS) properties as driver cost (Cost) and driver speed (Speed), supported carriers (SupportedCarriers), and supported protocols (SupportedProtocols). Driver developers configure properties that typically do not require modification by the administrator, such as supported delivery types (SupportedDeliveryTypes), and supported content types (SupportedContentTypes).

Note:

Properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies.

Table 11-1 Common Driver Properties

Name	Description	Mandatory Property?
Capability	Sets the driver's capability to send or receive messages. The values are SEND, RECEIVE, and BOTH.	Yes
Cost	The cost level of the driver (from 0 - 10). 0 is least expensive; 10 is most expensive. If the value is not in this range, cost is considered to be 0.	No
DefaultSenderAddress	The default address of the sender. The driver uses these addresses when sending a message that has no sender address specified, or when the specified sender address is not in the sender addresses list and the driver does not support using the application-provided sender address.	No
SenderAddresses	The list of sender addresses that the driver supports. If provided by the driver, the Messaging Engine can use this to route a sending message to the driver by matching against the sender address of the message.	No
SendingQueuesInfo	The information for the Driver Sending Queue.	Yes
Speed	The speed level of the driver (from 0-10, with 10 being the fastest).	No
SupportedCarriers	A comma-separated list of supported carriers.	No
SupportedContent Types	The content type supported by the driver.	Yes
SupportedDelivery Types	The delivery types supported by the driver.	Yes
SupportedProtocols	A comma-separated list of supported protocols. Entering an asterisk (*) for any protocol.	No
SupportedStatusTypes	The status types supported by the driver.	No
SupportsCancel	Supports a Cancel operation on a message.	No
SupportsReplace	Supports a Replace operation on a message.	No
SupportsStatusPolling	For certain protocols, an active polling of the remote gateway must be performed to check the status of a message previously sent. This property indicates whether the driver supports such status polling. If set to true, the Messaging Engine invokes the driver connection's getStatus() operation.	No
SupportsTracking	Supports Tracking operation on a message.	No

11.4.1.2 Securing Passwords

Sensitive driver properties (namely, passwords) can be stored securely in the credential store using Oracle Enterprise Manager. Properties are marked with the flag Encoded Credential and have a custom entry form field.

To store a sensitive driver property securely:

1. Go to the driver configuration page of the selected driver.

2. In the Driver-Specific Configuration section, locate the property with the Encoded Credential flag set.

3. Select the credential type (Depending on the selected credential type, you will be prompted to enter the username and/or password.). There are three options:

   • Indirect password, create new user (default option)—specify the username and real password; the password will be stored in the credential store with the username as part of the key. The key and a fixed folder (map name) will be stored in the driver deployment's driverconfig.xml.

   • Indirect password, use existing user—choose an existing username/key in the credential store (to reference the password you stored previously).

   • User a clear text password—specify the password, and it will be stored directly in driverconfig.xml.

4. Click on Apply to save the changes.

5. Restart the driver application or the container for the changes to take effect.

You can check the password in the driver deployment directory's driverconfig.xml. For an indirect password, the format will be:

value="->mapName:keyName"    (mapName is the driver target name, and the key is <parameter_name>.<username>)

For example, here is a sample entry in driverconfig.xml for an Email Driver's OutgoingPassword property:

<Property value="-&gt;/Farm_base_domain/base_domain/server_soa/usermessagingdriver-email:OutgoingPassword.ouser" encodedCredential="true" type="java.lang.String" mandatory="no" name="OutgoingPassword" description="oracle.sdp.messaging.EmailDriverConfig.outgoingPassword"/>

11.4.1.3 Configuring the E-Mail Driver

The E-Mail Driver both sends and receives messages (that is, its Capability property is set to BOTH by default). The E-Mail Driver sends messages over SMTP and uses either IMAP and POP3 for receiving messages.

11.4.1.3.1 E-Mail Driver Interoperability

This section details interoperability features of the E-Mail Driver.

The E-Mail driver is compatible with these protocols: POP3, IMAP4, and SMTP.

E-Mail Driver features include:

• Automatic connection retry

• SMTP for message sending

• IMAP4 and POP3 for message receiving (using polling)

• Scalable, highly available

• Prevents message loss and avoids duplication

The Gateway Vendors and Versions in Table 11-2 have been verified.

Table 11-2 E-Mail Driver Gateway Vendors and Versions

Vendor	Version
Oracle Beehive	Release 1 (1.4.3)
Oracle Collaboration Suite	10g Release 1 (10.1.2)
Microsoft Exchange	2003
Dovecot (IMAP4/POP3)	0.99.11
sendmail (SMTP)	8.13.1

11.4.1.3.2 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values refer to the javadoc of DriverConfigPropertyNames.

Table 11-3 Common Email Properties

Name	Description	Mandatory	Default Value
InstanceName	Instance Name (for internal use only)	Yes	Email-Driver
Capability	Message sending and receiving capability	Yes	Both
SupportedDeliveryTypes	Supported Delivery Types	Yes	Email
SupportedContentTypes	Supported Content Types	Yes	text/plain, text/html, multipart/mixed, multipart/alternative, multipart/related
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE, USER_REPLY_ACKNOWLEDGEMENT_SUCCESS, USER_REPLY_ACKNOWLEDGEMENT_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	Supported Carriers	No	N/A
Supported Protocols	Supported Protocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.3.3 Email Custom Properties

These are properties specific to this driver and are generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Table 11-4 Custom E-Mail Properties

Name	Description	Mandatory?	Default Value
MailAccessProtocol	E-mail receiving protocol. The possible values are IMAP and POP3. Required only if e-mail receiving is supported on the driver instance	No	IMAP
RetryLimit	This value specifies the number of times to retry connecting to the incoming mail server, if the connection is lost due to some reason. The default value is -1 which means no limit to the number of tries.	No	N/A
MailDelFreq	The frequency to permanently remove deleted messages. The unit is in seconds and the default value is 300 seconds. A negative value indicates the messages should not be expunged. For the POP3 protocol, the message is expunged after it is processed.	No	600
AutoDelete	This value indicates if the driver should mark the messages deleted after they have been processed. The value can be true or false and the default value is false. For the POP3 protocol, the messages are always deleted right after they are processed.	No	True
CheckMailFreq	The frequency with which to retrieve messages from the mail server. The unit is in seconds and the default value is 5 seconds.	No	30
ReceiveFolder	The name of the folder the driver is polling messages from. The default value is INBOX.	No	INBOX
OutgoingMailServer	The name of the SMTP server. Mandatory only if e-mail sending is required	No	N/A
OutgoingMailServerPort	The port number of SMTP server. Typically 25	No	25
OutgoingMailServerTLS	Whether to use TLS encryption to communicating to SMTP server.	No	False
OutgoingDefaultFromAddr	The default FROM address (if one is not provided in the outgoing message).	No	N/A
OutgoingUsername	The username used for SMTP authentication. Required only if SMTP authentication is supported by the SMTP server.	No	N/A
OutgoingPassword	The password used for SMTP authentication. Required only if SMTP authentication is supported by the SMTP server.	No	N/A
IncomingMailServer	The host name of the incoming mail server. Required only if e-mail receiving is supported on the driver instance.	No	N/A
IncomingMailServerPort	Port number of IMAP4 (i.e. 143 or 993) or POP3 (i.e. 110 or 995) server.	No	N/A
IncomingMailServerSSL	Whether to enable SSL when connecting to IMAP4 or POP3 server.	No	False
IncomingMailIDs	The e-mail addresses corresponding to the user names. Each e-mail address is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. Required only if e-mail receiving is supported on the driver instance.	No	N/A
IncomingUserIDs	The list of user names of the mail accounts the driver instance is polling from. Each name must be separated by a comma, for example, foo,bar. Required only if e-mail receiving is supported on the driver instance	No	N/A
IncomingUserPasswords	The list of passwords corresponding to the user names. Each password is separated by a comma and must reside in the same position in the list as their corresponding user name appears on the usernames list. Required only if e-mail receiving is supported on the driver instance.	No	N/A
IncomingProcessingChunkSize	Max number of messages processed per message polling.	No	100

11.4.1.3.4 Client API MessageInfo Support

These properties are message delivery related which are specified through client API. Table 11-5 describes if the protocol or driver implementation honors such properties.

Table 11-5 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	False
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.4.1.4 Configuring the SMPP Driver

SMPP (Short Message Peer-to-Peer) is one of the most popular GSM SMS protocols. User Messaging Service includes a pre-built implementation of the SMPP protocol as a driver that is capable of both sending and receiving short messages. If the sending feature is enabled, the SMPP driver opens one TCP connection to the SMS-C (Short Message Service Center) as a transmitter for sending. If the driver's receiving feature is enabled, it opens another connection to the SMS-C as a receiver for receiving. Only two TCP connections (both initiated by the driver) are needed for all communication between the driver and the SMS-C.

Note:

The SMPP Driver implements Version 3.4 of the SMPP protocol and only supports connections to an SMS-C that supports this version.

11.4.1.4.1 SMPP Driver Interoperability

This section details interoperability features of the SMPP Driver.

The SMPP driver is compatible with these protocols: SMPP v3.4.

SMPP Driver features include:

• Automatic connection retry

• HTTP proxy for firewall traversal

• Authentication configuration

• Configurable chunk size

• Bulk Sending

• Encoding: UCS2, IA5, GSM_DEFAULT

• Priority Setting

• Configurable Window size

• Plain text content only

The Gateway Vendors in Table 11-6 have been verified.

Table 11-6 SMPP Driver Gateway Vendors

Vendor
Logica CMG
Clickatell
Verisign
OpenSMPP (simulator)

11.4.1.4.2 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values refer to the javadoc of DriverConfigPropertyNames.

Table 11-7 Common SMPP Properties

Name	Description	Mandatory	Default Value
InstanceName	Instance Name (for internal use only)	Yes	SMPP-Driver
Capability	Message sending and receiving capability	Yes	Both
SupportedDeliveryTypes	Supported Delivery Types	Yes	SMS
SupportedContentTypes	Supported Content Types	Yes	text/plain
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	Supported Carriers	No	N/A
Supported Protocols	Supported Protocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.4.3 Custom Properties

These are properties specific to this driver and are generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Table 11-8 Custom SMPP Properties

Name	Description	Mandatory?	Default Value
SmsAccountId	The Account Identifier on the SMS-C.	Yes	N/A
SmsServerHost	The name (or IP address) of the SMS-C server.	Yes	N/A
TransmitterSystemId	The account ID that is used to send out messages.	Yes	N/A
ReceiverSystemId	The account ID that is used to receive messages.	Yes	N/A
TransmitterSystemType	The type of transmitter system.	Yes	The default value is Logica.
ReceiverSystemType	The type of receiver system.	Yes	The default value is Logica.
TransmitterSystemPassword	The password of the transmitter system.	Yes	N/A
ReceiverSystemPassword	The password for the receiver system.	Yes	N/A
ServerTransmitterPort	The TCP port number of the transmitter system.	Yes	N/A
ServerReceiverPort	The TCP port number of the receiver system.	Yes	N/A
DefaultEncoding	The default encoding of the SMPP driver.	No	The default value is UCS2.
EncodingAutoDetect	If set to true (the default), the SMPP driver encodes automatically.	No	The default value is true.
LocalSendingPort	The local TCP port used by the SMPP driver to messages to the SMS-C.	No	N/A
LocalReceivingPort	The local TCP port used by the SMPP drivers to receive messages from the SMS-C.	No	N/A
LocalAddress	The host name (or IP address) of the server that hosts the SMPP driver.	No	N/A
WindowSize	The window size for SMS. This value must be a positive number.	No	The default value is 1.
EnquireInterval	The interval, in seconds, to send an enquire message to the SMS-C.	No	The default value is 30.
ThrottleDelay	The delay, in seconds, between throttles.	No	The default value is 15.
BindRetryDelay	The delay, in seconds, for a binding retry.	No	The default value is 30.
ResponseTimer	Time lapse allowed between SMPP request and response, in seconds. Default is 30.	No	30
RegisteredDeliveryMask	The delay, in seconds, for a binding retry.	No	0xFF
RangeSetNull	Set to true to set the address range field of BIND_RECEIVER to null. Set to false (the default value) to set the address range field to SmsSystemId.	No	The default value is false.
PriorityAllowed	The highest priority allowed for the SMPP driver. The range is 0 (normal) to 3 (highest).	No	The default value is 0.
BulkSending	Setting this value to true (the default) enables sending messages in bulk to the SMS-C.	No.	The default value is true.
PayloadSending	If set to true, the SMPP driver always uses the message payload properties when sending messages to the SMS-C.	No	The default value is false.
SourceTon	The Type of Number (TON) for ESME address(es) served through SMPP receiver session.	No	The default value is 0.
SourceNpi	The Numbering Plan Indicator (NPI) for ESME address(es) served through the SMPP receiver session.	No	The default value is 0.
DestinationTon	The Type of Number (TON) for destination.	No	The default value is 0.
DestinationNpi	The Numbering Plan Indicator (NPI) for destination.	No	The default value is 0.
ExtraErrorCode	A comma-separated list of error codes.	No	N/A
MaxChunks	The maximum SMS chunks for a message.	No	The default value is -1 (no maximum).
ChunkSize	The size of each SMS message chunk.	No	The default value is 160.
LongMessageSending	Supports sending long messages.	No	N/A
DatagramMessageMode	Supports Datagram Message mode.	No	N/A

11.4.1.4.4 Client API MessageInfo Support

These properties are message delivery related which are specified through client API. Table 11-9 describes if the protocol or driver implementation honors such properties.

Table 11-9 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	True
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.4.1.5 Configuring the XMPP Driver

The XMPP Driver provides unidirectional as well as bidirectional access from Oracle Fusion Middleware to end users for real-time instant messaging (IM) via XMPP (Extensible Messaging and Presence Protocol). This driver enables end users to receive alert notifications or interactively chat with applications through their IM client of choice.

11.4.1.5.1 About XMPP

XMPP is an open, XML-based protocol for Instant Messaging and Presence. XMPP-based software is deployed on thousands of servers across the Internet and is used by millions of people worldwide. XMPP consists of a client-server architecture, which resembles the ubiquitous e-mail network. XMPP servers are completely decentralized, allowing anyone to set up their own server. Messaging is achieved as in the email network, where recipients are addressed by a username and a host name (for example: username@host name). In the XMPP network, users are identified by an XMPP (Jabber) ID, which consists of a username and the host name of the particular XMPP server to which the user connects. An end user of XMPP connects to an XMPP server using an XMPP client in order to send instant messages to other XMPP users. XMPP, however, is not the only protocol network available for instant messaging. XMPP has an extensible and modular architecture. It integrates with proprietary IM networks such as Yahoo, MSN, AOL and ICQ using transport gateways that can connect to these networks. This allows XMPP users to communicate with those on other networks.

In order to use the XMPP Driver in UMS, you must have access to a Jabber/XMPP server and an XMPP account for the UMS XMPP Driver instance to login as. In addition, the XMPP Driver includes configuration parameters that enable UMS to communicate with users on Yahoo, MSN, AOL or ICQ IM networks. This requires that you additionally have accounts on these proprietary IM networks to which you are connecting from the XMPP Driver, and thus, allow end users of those particular networks to communicate with UMS.

11.4.1.5.2 XMPP Driver Interoperability

This section details interoperability features of the XMPP Driver.

The XMPP driver is compatible with these protocols: XMPP (RFC 3920, 3921).

XMPP Driver features include:

• Automatic connection retry

• HTTP proxy for firewall traversal

• Plain text content only

The Gateway Vendors and Versions in Table 11-6 have been verified.

Table 11-10 XMPP Driver Gateway Vendors and Versions

Vendor	Version
Jabberd	v1, v2
ejabberd	v2

11.4.1.5.3 Third-Party Software

The XMPP Driver uses or requires the following third-party software:

Table 11-11 Required Third-Party Software

Name	Instructions	Version(s)
JabberBeans	This driver uses the JabberBeans Java library to connect to a Jabber/XMPP Instant Messaging Server. This driver includes a licensed copy of JabberBeans (version 0.9.1).	0.9.1
XMPP Server	Optional. To download and install your own Jabber/XMPP server, pick and install a server from http://www.jabber.org.
Yahoo, MSN, AOL(AIM), and ICQ Transport Gateways	Optional. Follow the transport installation guide that comes with the Jabber/XMPP server to install and configure one or more transports to connect to proprietary IM gateways.

Note:

You do not need to install your own XMPP Server if you have access to an existing server. For a list of public servers, see http://www.jabber.org.

11.4.1.5.4 Driver Application Archive (EAR)

$ORACLE_HOME/communications/applications/sdpmessagingdriver-xmpp.ear

11.4.1.5.5 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values refer to the javadoc of DriverConfigPropertyNames.

Table 11-12 Common XMPP Properties

Name	Description	Mandatory	Default Value
InstanceName	Instance Name (for internal use only)	Yes	XMPP-IM-Driver
Capability	Message sending and receiving capability	Yes	Both
SupportedDeliveryTypes	Supported Delivery Types	Yes	IM
SupportedContentTypes	Supported Content Types	Yes	text/plain
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	Supported Carriers	No	N/A
Supported Protocols	Supported Protocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.5.6 XMPP Custom Properties

The XMPP Driver includes the custom properties shown below.

Table 11-13 Custom XMPP Properties

Name	Description	Mandatory	Default Values
IMServerHost	Jabber server host name. For multiple servers, use a comma-separated list (for example: my1.host.com, my2.host.com). If only one host name is specified, it will be used for all accounts.	Yes	N/A
IMServerPort	Corresponding comma-separated list of Jabber server ports (e.g. 5222, 5222)	Yes	5222
IMServerUsername	List of Jabber usernames to login as (these user accounts will be automatically created, if necessary, on the corresponding Jabber servers). If you have multiple servers listed above, there must be an equal number of usernames (one username per server). If you have only one server listed above, all usernames listed here will use that server (e.g. oracleagent1, oracleagent2). You may also enter a complete Jabber ID if its domain name is different from the Jabber server host name (for example: [e-mail]).	Yes	N/A
IMServerPassword	Corresponding comma-separated list of passwords for each username listed above.	Yes	N/A
YahooEnable	Enable/disable Yahoo Transport (set true to enable, and leave blank to set false to disable), for each user account specified above in a comma-separated list.	No	N/A
YahooUsername	Comma-separated list of Yahoo account IDs (requires that you already have these IDs registered on Yahoo), for each user account above (leave entries blank for accounts without Yahoo). Entering valid Yahoo account info allows Yahoo users to access applications via instant messaging.	No	N/A
YahooPassword	Corresponding comma-separated list of Yahoo account passwords.	No	N/A
MSNEnable	Enable/Disable MSN Transport (set 'true' to enable, and leave blank or set 'false' to disable), for each user account specified above in a comma-separated list.	No	N/A
MSNUsername	Comma-separated list of MSN Messenger (known as .NET passport) account IDs (requires that you already have these IDs registered as .NET passports), for each user account above (leave entries blank for accounts without MSN). Entering valid .NET account info allows MSN Messenger users to access applications via instant messaging.	No	N/A
MSNPassword	Corresponding comma-separated list of MSN Messenger account passwords.	No	N/A
AOLEnable	Enable/Disable AOL IM (AIM) Transport (set 'true' to enable, and leave blank or set 'false' to disable), for each user account specified above in a comma-separated list.	No	N/A
AOLUsername	Comma-separated list of AOL IM (AIM) account IDs (requires that you already have these IDs registered with AOL), for each user account above (leave entries blank for accounts without AOL). Entering valid AOL account info allows AOL users to access applications via instant messaging.	No	N/A
AOLPassword	Corresponding comma-separated list of AOL IM account passwords.	No	N/A
ICQEnable	Enable/Disable ICQ IM Transport (set 'true' to enable, and leave blank or set 'false' to disable), for each user account specified above in a comma-separated list.	No	N/A
ICQUsername	Comma-separated list of ICQ account IDs (requires that you already have these IDs registered with ICQ), for each user account above (leave entries blank for accounts without ICQ). Entering valid ICQ account info allows ICQ users to access applications via instant messaging	No	N/A
ICQPassword	Corresponding comma-separated list of ICQ account passwords.	No	N/A
RetryLimit	Number of times the driver should attempt to reconnect when disconnected from the Jabber server. Enter -1 for unlimited retries.	No	N/A
RetryInterval	Time interval (in seconds) between reconnect attempts.	No	N/A

11.4.1.5.7 Client API MessageInfo Support

These properties are message delivery related which are specified through client API. The table below describes if the protocol or driver implementation honors such properties.

Table 11-14 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	False
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.4.1.6 Configuring the VoiceXML Driver

The VoiceXML Driver supports the Genesys VoiceGenie gateway's outbound call protocol to send messages authored in VoiceXML. The gateway delivers the message using text-to-speech synthesis.

11.4.1.6.1 VoiceXML Driver Interoperability

This section details interoperability features of the VoiceXML Driver.

The VoiceXML driver is compatible with these protocols: VoiceXML over HTTP (VoiceGenie gateway protocol).

VoiceXML Driver features include:

• VoiceXML content only

The Gateway Vendor and Version in Table 11-6 has been verified.

Table 11-15 VoiceXML Driver Gateway Vendor and Version

Vendor	Version
Genesys VoiceGenie	6.4.2

11.4.1.6.2 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values refer to the javadoc of DriverConfigPropertyNames.

Table 11-16 Common VoiceXML Properties

Name	Description	Mandatory	Default Value
InstanceName	Instance Name (for internal use only)	Yes	VoiceXML-Driver
Capability	Message sending and receiving capability	Yes	SEND
SupportedDeliveryTypes	Supported Delivery Types	Yes	VOICE
SupportedContentTypes	Supported Content Types	Yes	text/vxml, text/x-vxml
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	Supported Carriers	No	N/A
Supported Protocols	Supported Protocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.6.3 VoiceXML Custom Properties

The VoiceXML Driver includes the custom properties shown below.

Table 11-17 Custom VoiceXML Properties

Name	Description	Mandatory	Default Values
VoiceXMLOutboundServletURI	The URL of the VoiceXML/VoiceGenie gateway.	Yes	N/A
VoiceXMLOutboundServletUserName	The user name of the VoiceXML gateway.	No	N/A
VoiceXMLOutboundServletPassword	The password of the VoiceXML gateway.	No	N/A
VoiceXMLOutboundServletDNIS	The number that appears in the recipient's ID display.	No	N/A
VoiceXMLReceiveURL	The URL of this driver's servlet which will handle incoming requests from the VoiceXML Gateway. The format is http://<host>:<port>/usermessagingdriver-voicexml/receive. The default behavior, if this property is not set, is to use the local container's HTTP listen host and port. The auto-generated default URL will only work for the first driver instance. For additional instances, the context root is different and this property must be configured using the correct context root replacement for /sdpmessagingdriver-voicexml.	No	N/A

11.4.1.6.4 Client API MessageInfo Support

These properties are message delivery related which are specified through client API. The table below describes if the protocol or driver implementation honors such properties.

Table 11-18 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	False
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.4.1.7 Configuring the Worklist Driver

The Worklist driver enables notifications from all sources to be sent to users in the form of worklist tasks for integration into the users' WebCenter Unified Worklist.

Note:

Worklist Message tasks are accessible both through a WebCenter that has been configured to search the BPEL connection that the Worklist message driver is sending messages to, as well as through the BPEL Worklist application. The BPEL Worklist Application will also show these message-based tasks as Worklist items.

This integration is achieved by exposing a Worklist channel (delivery type) to applications and end users. Messages sent through the user's Worklist channel are processed by the Worklist driver. The User Messaging Service API semantics are the same as those for existing channels such as IM or Email. This driver handles sending messages only. The Driver Application Archive (EAR) is located at: $ORACLE_HOME/communications/applications/sdpmessagingdriver-worklist.ear

11.4.1.7.1 Install the Worklist Driver

To enable the messaging worklist feature, the WebLogic SOA domain must be extended using the extension template available at $ORACLE_HOME/common/templates/applications/oracle.ums.driver.worklist_template_11.1.1.jar. To extend a SOA domain using the Oracle Fusion Middleware Configuration Wizard:

1. Launch Oracle Fusion Middleware Configuration Wizard ($ORACLE_HOME/common/bin/config.sh or %ORACLE_HOME%\common\bin\config.cmd).

2. Select the Extend an existing WebLogic domain option.

3. Select the desired SOA domain directory.

4. Select the Extend my domain using an existing extension template option.

5. Click Browse, and navigate to $ORACLE_HOME/common/templates/applications

6. Select oracle.ums.driver.worklist_template_11.1.1.jar

7. Complete the remaining steps of the Oracle Fusion Middleware Configuration Wizard, and restart the SOA servers.

Note:

Special Considerations if the SOA managed server is on a remote machine: The oracle.ums.driver.worklist_template_11.1.1.jar extension template includes a SOA composite application (sca_sdpmessagingsca-worklist-composite_rev1.0.jar) that is copied to $DOMAIN_HOME/soa/autodeploy, and is auto-deployed by the SOA Infra runtime upon server restart. However, if the SOA Infra runtime is on a remote machine, and the domain is packed with the -managed=true option (the correct option to use), this directory is not included in the archive. Thus, the composite is not deployed upon restarting the SOA managed server.

In order to complete the installation, copy the contents of $DOMAIN_HOME/soa/autodeploy from the AdminServer machine to the corresponding location on the remote machine with the SOA managed server, and restart the SOA managed server. You may have to create the directory structure soa/autodeploy under $DOMAIN_HOME on the remote machine.

11.4.1.7.2 Common Properties

The following common driver properties are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values see the javadoc of DriverConfigPropertyNames.

Table 11-19 Common Worklist Properties

Name	Description	Mandatory?	Default Value
InstanceName	Instance Name (for internal use only)	Yes	Worklist-Driver
Capability	Message sending and receiving capability	Yes	SEND
SupportedDeliveryTypes	Supported Delivery Types	Yes	WORKLIST
SupportedContentTypes	Supported Content Types	Yes	text/plain, text/html
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	SupportedCarriers	No	N/A
SupportedProtocols	SupportedProtocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.7.3 Custom Properties

The following custom property is available:

Table 11-20 Custom Worklist Property

Name	Description	Mandatory	Default Value
BPELConnectionURL	The URL of the BPEL server to connect to. The format is http://<bpel-host>:<bpel-port>. The default behavior, unless changed, is to use the local container's HTTP connection URL.

11.4.1.7.4 Client API MessageInfo Support

This table shows if the protocol or driver implementation honor the following message delivery-related properties that are specified through the client API.

Table 11-21 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	False
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.4.1.8 Configuring the Proxy Driver

The Proxy Driver acts as a Messaging Web Service client to a Fusion Middleware Messaging server hosted elsewhere in the intranet or Internet. It uses SOAP over HTTP (the Parlay X Multimedia Web Service protocol) to send messages and receive messages as well as return message delivery status. The ParlayX Web Service relays messages from one UMS instance to another. It can be used to relay traffic from multiple instances in an Intranet to a terminating instance that has all of the protocol-specific drivers configured to an external gateway such as an SMSC, or to an SMTP or IMAP mail server.

11.4.1.8.1 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the engine when routing outbound messages. Some properties are set by the driver developer and do not normally require modification, while others can be modified by the administrator to change the routing behavior. Some properties such as SendingQueuesInfo are for advanced use and only require modification for advanced deployment topologies. For a complete description of these properties and available values refer to the javadoc of DriverConfigPropertyNames.

Table 11-22 Common Proxy Properties

Name	Description	Mandatory	Default Value
InstanceName	Instance Name (for internal use only)	Yes	Proxy-Driver
Capability	Message sending and receiving capability	Yes	SEND
SupportedDeliveryTypes	Supported Delivery Types	Yes	EMAIL, SMS, VOICE, IM, WORKLIST
SupportedContentTypes	Supported Content Types	Yes	*
SupportedStatusTypes	Supported Status Types	No	DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE
Cost	Cost	No	N/A
Speed	Speed	No	N/A
SupportedCarriers	Supported Carriers	No	N/A
Supported Protocols	Supported Protocols	No	N/A
SupportsCancel	Supports Cancel Operation on the Message	No	False
SupportsReplace	Supports Replace Operation on the Message	No	False
SupportsTracking	Supports Tracking Operation on the Message	No	False
SupportsStatusPolling	Supports Status Polling Operation on the Message	No	False
SenderAddresses	Sender Addresses	No	N/A
DefaultSenderAddress	Default Sender Address	No	N/A
SendingQueuesInfo	Driver Sending Queue Info	Yes	OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1

11.4.1.8.2 Proxy Custom Properties

The Proxy Driver includes the custom properties shown below.

Table 11-23 Custom Proxy Properties

Name	Description	Mandatory	Default Values
GatewayURL	The URL to the hosted 11g UMS Web Service gateway. The URL is in the following format: http://<host>:<port>/sdpmessaging/parlayx/SendMessageService	Yes	N/A
Username	Username of the messaging gateway.	No	N/A
Password	The password of the username	No	N/A
Policies	Comma-separated list of Oracle Web Services Manager WS-Security policies to be attached to proxy driver requests	No	N/A

11.4.1.8.3 Client API MessageInfo Support

These properties are message delivery related which are specified through client API. The table below describes if the protocol or driver implementation honors such properties.

Table 11-24 Client API MessageInfo Support

Name	Description	Support
Expiration	Expiration means how long the message will exist until it expires.	False
Delay	Delay means the amount of time that must elapse before the message is sent.	False

11.5 Securing User Messaging Service

The User Messaging Preferences User Interface and the Parlay X Web Services can be secured at the transport-level using Secure Sockets Layer (SSL). By default, all deployed web services are unsecured. Web Service Security should be enabled for any services that will be deployed in a production environment.

• To enable SSL in the Oracle WebLogic Server, see "Configure SSL for Oracle WebLogic Server" in the Oracle Fusion Middleware Administrator's Guide. This step is sufficient to secure the User Messaging Preferences User Interface.

• To secure the Parlay X Web Services, see "Configuring Transport-Level Security" in the Securing WebLogic Web Services.

UMS supports the use of Oracle Web Services Manager WS-Security policies to protect UMS web services. For more information about Oracle Web Services Manager, see "Using Oracle Web Service Security Policies", in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server.

The recommended security configuration for web services uses Security Assertion Markup Language (SAML) tokens to pass identities between web service clients and UMS. With SAML tokens, instead of the web service client passing a username and password to UMS, a trust relationship is established between the client and UMS by means of exchanging certificates. Once this keystore configuration is in place, the web service client passes only the user identity, and vouches for the fact that it has authenticated the user appropriately.

The recommended policies to use for UMS web services are:

• oracle/wss11_saml_token_with_message_protection_service_policy (server-side)

• oracle/wss11_saml_token_with_message_protection_service_policy (client-side)

11.5.1 Web Service Security on Notification

The different Web services include corresponding notification Web services (MessageNotification, PresenceNotification) that run on the client side and receive notifications (message delivery status, message receipt, presence status change) when the appropriate event occurs. This implementation does not provide for the use of Web Service security (WS-Security) by default during notification of the clients. That is, the server assumes that the notification Web services running on the client side do not use WS-Security, and makes no attempt to authenticate itself when sending notifications. If you enable WS-Security on the client side, the notification from the server will fail because the notification SOAP request will be missing the required headers.

11.5.2 Enabling UMS Service Security

To enable a policy for an UMS web service, follow the steps in "Configuring Oracle WSM Security Policies in Administration Console" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server, selecting policy oracle/wss11_saml_token_with_message_protection_service_policy. This configuration must be repeated for each service that you wish to secure.

11.5.3 Enabling Client Security

Web service client security must be enabled programmatically. When using the client libraries described in Parlay X Messaging Client API and Client Proxy Packages (in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite), WS-Security policy configuration is provided when a client object is constructed. The client constructors take an argument of type Map<String, Object>. In general when using SAML authentication, the key/value pairs (Table 11-25) should be added to the configuration map in addition to other required properties such as the endpoint address.

Table 11-25 Client security keys

Key	Type	Typical Value
oracle.sdp.parlayx.ParlayXConstants.POLICIES	String[]	oracle/wss11_saml_token_with_message_protection_client_policy
javax.xml.ws.BindingProvider.USERNAME_PROPERTY	String	<valid username>
oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY	String	(optional) keystore alias for target service. See Client Aliases.

Example 11-1 Web Service Client Security

import oracle.sdp.parlayx.presence.consumer.PresenceConsumerClient;
 
...
 
Map<String, Object> config = new HashMap<String, Object>();
config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ums_url);
config.put(oracle.sdp.parlayx.ParlayXConstants.POLICIES, new String[] {"oracle/wss11_saml_token_with_message_protection_client_policy"});
config.put(javax.xml.ws.BindingProvider.USERNAME_PROPERTY, "test.user1");
 
PresenceConsumerClient presenceClient = new PresenceConsumerClient(config);

11.5.4 Keystore Configuration

In order to use the recommended WS-Security policy, you must configure a keystore containing the public and private key information required by OWSM. Refer to "Configuring the Credential Store Using WLST" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for information on how to configure the keystore and corresponding credential store entries.

• If both your web service client and UMS server are in the same domain, then they share a keystore and credential store.

• If your web service client and UMS server are in different domains, then you must import the UMS public key into your client domain's keystore, and must import your client domain's public key into the UMS keystore.

11.5.5 Client Aliases

When using certain WS-Security policies such as the SAML policy recommended here, the client must use the server's public key to encrypt the web service request. However, there is generally only one keystore configured per domain. Therefore, if you have a domain in which there are web service clients that communicate with web services in multiple other domains, then you may need to override the default keystore entry used by OWSM.

For example, if you have a domain in which application "A" is a web service client to a UMS web service, and application "B" is a web service client to a web service in another domain, then A's requests must be encrypted using the public key of the UMS domain, and B's requests must be encrypted using the public key of the other domain. You can accomplish this goal by overriding the keystore alias used by OWSM for each request:

• Import (for example) the UMS public key with alias "ums_public_key", and the other public key with alias "other_public_key".

• When creating an UMS web service client, specify the recipient keystore alias parameter, setting the key to oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY and the value to "ums_public_key" as shown in Example 11-2.

  Example 11-2 Client Aliases

  import oracle.sdp.parlayx.multimedia_messaging.send.SendMessageClient
   
  ...
   
  Map<String, Object> config = new HashMap<String, Object>();
  config.put(javax.xml.ws.BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ums_url);
  config.put(oracle.sdp.parlayx.ParlayXConstants.POLICIES, new String[] {"oracle/wss11_saml_token_with_message_protection_client_policy"});
  config.put(javax.xml.ws.BindingProvider.USERNAME_PROPERTY, "test.user1");
  config.put(oracle.wsm.security.util.SecurityConstants.Config.KEYSTORE_RECIPIENT_ALIAS_PROPERTY, "ums_public_key")
  SendMessageClient sendClient = new SendMessageClient(config);
  

• The other web service client will similarly need to override the keystore alias, but the exact mechanism may differ. For example if using a JAX-WS client stub directly, then you can add the override property to the JAX-WS request context. See "Policy Configuration Overrides for the Web Service Client" in Oracle Fusion Middleware Securing WebLogic Web Services for Oracle WebLogic Server for more details.

11.6 Troubleshooting Oracle User Messaging Service

To debug User Messaging Service, first check the server diagnostic logs. The logs may contain exception, error, or warning messages that provide details about incorrect behavior along with actions to remedy the problem. The following table describes additional methods for debugging common User Messaging Service problems.

Table 11-26 Troubleshooting UMS

Symptom	Possible Causes	Solutions
Notifications are not being sent from BPEL or Human Workflow components in SOA.	Notification Mode is set to NONE in SOA Workflow Notification configuration.	Change the Notification Mode setting to EMAIL or ALL using Oracle Fusion Middleware Control.
Email notification is not being sent.	The Outgoing (SMTP) Mail Server settings in the UMS Email Driver are incorrect.	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: OutgoingMailServer OutgoingMailServerPort Note: Validate the values by using them in any e-mail client for connecting to the SMTP server.
	The SMTP server requires authentication or a secure connection (TLS or SSL).	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: OutgoingUsername OutgoingPassword OutgoingMailServerSecurity
Notifications are not being sent because of error message: No matching drivers found for sender address = <address>	The UMS Driver for the appropriate channel is configured with a specific list of SenderAddresses, and the message sent by the application has set a non-matching Sender Address. Note: UMS Server matches the outbound message's sender address, if set, against the available drivers' SenderAddresses to find a matching driver to use for delivering the message. If a driver has set one or more SenderAddresses, then the UMS Server will only send messages with the matching sender address to it.	Check the following settings in the appropriate UMS Driver using Oracle Fusion Middleware Control: SenderAddresses Note: The format for SenderAddresses is a comma-separated list of <DeliveryType>:<Address>. For example: EMAIL:[e-mail], EMAIL:[e-mail] Leave this property blank, if you want this driver to service outbound messages for all sender addresses for this channel (delivery type). If there are multiple driver instances deployed for the same channel (delivery type) with different configurations, use the SenderAddresses to differentiate the driver instances. For example, one instance can be set with a specific value in SenderAddresses to only service outbound messages with that matching sender address, while the other instance can keep the SenderAddresses blank in order to service all outbound messages that do not specify any sender address or one that does not match that of the first driver instance. SenderAddresses that are configured with the incorrect syntax (such as missing <DeliveryType>:) are ignored by the UMS Server for the purpose of driver selection.
The email client inconsistently receives notifications.	The Incoming Mail Server settings in the UMS Email Driver are configured with the same email account to which notifications are being sent. If the notification is sent to the same account, the UMS Email Driver may download and process the email before the email client can display it.	Use an exclusive e-mail account for Incoming Mail Server settings. Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: IncomingMailIDs IncomingUserIDs
SOA Human Workflow notifications are sent, but are not actionable.	The Actionable Email Address is not configured in SOA Workflow Notification Properties.	Set the Actionable Email Address in SOA Workflow Notification Properties with the address of the email account configured in the UMS Email Driver.
	The Human Workflow task is not set to send actionable notifications.	Set the actionable attribute for the Human Workflow task in JDeveloper and redeploy the SOA composite application.
SOA Human Workflow actionable notifications are sent, but no action is taken after responding.	The Incoming Mail Server settings in the UMS Email Driver are incorrect.	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: MailAccessProtocol (IMAP or POP3, in uppercase) ReceiveFolder IncomingMailServer IncomingMailServerPort IncomingMailServerSSL IncomingMailServerSSL IncomingUserIDs IncomingUserPasswords ImapAuthPlainDisable Note: Validate the values by using them in any e-mail client for connecting to an IMAP or POP3 server.
	The mail access protocol is incorrect.	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: MailAccessProtocol (IMAP or POP3, in uppercase)
	The email server is SSL-enabled.	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: IncomingMailServerSS
	The receive folder name is incorrect.	Check the following settings in the UMS Email Driver using Oracle Fusion Middleware Control: ReceiveFolder Note: Some email servers may expect the value INBOX to be inbox or Inbox (that is, case-sensitive). Based on your email server, use an appropriate value.
	A non-default email client is configured for receiving notifications. When the user clicks the approval link, the default mail client page opens, which may send emails to a different email server.	Configure the default email client to receive actionable notifications.
SOA BPEL User Notification or Human Workflow notifications are sent to the correct delivery type (email, sms, and so on) but to the wrong address.	A self-provisioned messaging channel was created by the user in User Messaging Preferences for use in BPEL User Notification or Human Workflow use cases. Note: The User Messaging Preferences UI allows the end user to create his or her own messaging channel for various use cases, but these are not to be used for BPEL User Notification and Human Workflow.	Do not use a self-provisioned messaging channel for BPEL User Notification or Human Workflow use cases (that is, do not set as Default channel, and do not use in a messaging filter for such use cases). BPEL User Notification and Human Workflow utilize User Messaging Preferences only for the delivery type preference, and the actual address is retrieved from the user profile in the identity management system. Note: Addresses from the user profile in the identity management system are available through User Messaging Preferences using pre-defined channel names, such as Business Email, Business Mobile, Business Phone, Instant Messaging. Use these pre-defined messaging channels instead for BPEL User Notification and Human Workflow use cases.