Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
11g Release 1 (11.1.1.7)

Part Number E10226-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

27 Configuring Oracle User Messaging Service

This chapter describes the features and architecture of Oracle User Messaging Service (UMS). It also describes how to configure and secure Oracle UMS in your environment.

This chapter includes the following sections:

For more information about Oracle User Messaging Service tuning and performance properties, see Oracle Fusion Middleware Performance and Tuning Guide.

27.1 Introduction to User Messaging Service

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

27.1.1 Components

There are three types of components that comprise 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 Portal Spaces application that can send messages from a web interface.

In addition to the components that comprise 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.

27.1.2 Architecture

The system architecture of Oracle User Messaging Service is shown in Figure 27-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 Enterprise JavaBeans (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 Oracle SOA Suite or Oracle BAM in their respective Oracle WebLogic Server instances. An Oracle WebCenter Portal installation includes the necessary libraries to act as a UMS client application, invoking a server deployed in a SOA instance.

Figure 27-1 UMS Architecture

Description of Figure 27-1 follows
Description of "Figure 27-1 UMS Architecture"

27.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 email). For example, when you build a SOA application that sends email notification, you drag and drop an Email activity from the Oracle JDeveloper Component Palette to the appropriate location within a workflow. The application connects then sends notifications.

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

To enable the workflow participants to receive and forward notifications, use Oracle Enterprise Manager Fusion Middleware Control 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 27-2). Oracle User Messaging Service includes drivers that support messaging through email, IM, SMS, and voice channels. For more information, see Section 27.4, "Configuring User Messaging Service Drivers."

Figure 27-2 Oracle Enterprise Manager Fusion Middleware Control

EM Grid Control
Description of "Figure 27-2 Oracle Enterprise Manager Fusion Middleware Control"

For workflow participants to receive the notifications, they must register the devices that they use to access messages through User Messaging Preferences (Figure 27-3).

Figure 27-3 User Messaging Preferences

User Preferences screen
Description of "Figure 27-3 User Messaging Preferences"

27.3 Accessing User Messaging Service Configuration Pages

You configure Oracle User Messaging Service through Oracle Enterprise Manager Fusion Middleware Control.

27.3.1 Setting the Storage Method

Use the Server Properties page to set the deployment type for the Messaging Server (that is, select the storage method for runtime 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.

27.3.2 Adding or Removing User Messaging Preferences Business Terms

The Server Properties 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, see Section 27.3.2.1, "Adding Business Terms."

27.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.

27.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.

27.4 Configuring User Messaging Service Drivers

Oracle User Messaging Service includes the following drivers.

Note:

For the cluster environment, 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.

27.4.1 Configuring a Driver

To configure a driver:

  1. Log in to Oracle Enterprise Manager Fusion Middleware Control as an administrator.

  2. Expand the Fusion Middleware folder.

  3. Navigate to the User Messaging Service home page.

    Description of ns_login.gif follows
    Description of the illustration ns_login.gif

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

    Description of ns_assoc_drv.gif follows
    Description of the illustration ns_assoc_drv.gif

  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 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 is displayed.

    Description of ns_configdriver.gif follows
    Description of the illustration ns_configdriver.gif

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

27.4.1.1 Introduction to Driver Properties

Oracle User Messaging Service drivers share common properties (listed in Table 27-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 27-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-delimited list of supported carriers.

No

SupportedContentTypes

The content type supported by the driver.

Yes

SupportedDeliveryTypes

The delivery types supported by the driver.

Yes

SupportedProtocols

A comma-delimited list of supported protocols. Enter 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 a tracking operation on a message.

No


27.4.1.2 Securing Passwords

Sensitive driver properties (namely, passwords) can be stored securely in the credential store using Oracle Enterprise Manager Fusion Middleware Control. 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 are 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 is stored in the credential store with the username as part of the key. The key and a fixed folder (map name) are stored in the driver deployment's driverconfig.xml file.

    • 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 is stored directly in the driverconfig.xml file.

  4. Click 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 file. For an indirect password, the format is:

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"/>

27.4.1.3 Configuring the Messaging Extension Driver

The extension driver extends the messaging capability of the User Messaging Service by enabling support for arbitrary administrator-defined channels (protocols) and delivering the notifications for such channels to an administrator-defined web service listener endpoint.

Note:

An instance of this driver is deployed, but not targeted to any servers in the default installation. To enable this driver instance, it must be targeted to the appropriate servers where UMS (usermessagingserver) is running.

27.4.1.3.1 Driver Application Archive (EAR)

The EAR file is $oracle_home/communications/applications/sdpmessagingdriver-extension.ear.

27.4.1.3.2 Common Properties

These are common driver properties that are indicative of the capabilities of this driver for use by the messaging 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. See Table 27-2. For a complete description of these properties and available values, see the JavaDoc for driverconfigpropertynames.

Table 27-2 Extension Driver Common Properties

Name Description Mandatory? Default Value

InstanceName

Instance name (for internal use only)

Yes

Extension-Driver

Capability

Message sending and receiving capability

Yes

SEND

SupportedDeliveryTypes

Supported delivery types

Yes

URI

SupportedContentTypes

Supported content types

Yes

text/plain, text/html, text/xml

SupportedStatusTypes

Supported status types

No

DELIVERY_TO_GATEWAY_SUCCESS, DELIVERY_TO_GATEWAY_FAILURE

Cost

Cost

No

 

Speed

Speed

No

 

SupportedCarriers

Supported carriers

No

 

SupportedProtocols

Supported protocols

No

popup

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

 

DefaultSenderAddress

Default sender address

No

 

SendingQueuesInfo

Driver sending queue info

Yes

OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1


27.4.1.3.3 Custom Properties

This driver supports multiple configuration groups called extension endpoint groups. An extension endpoint group holds the configuration for a remote endpoint at which to deliver extension notifications. Each endpoint must have a distinct combination of protocol and mapped domain. The properties of the extension endpoint group are listed in Table 27-3:

Table 27-3 Extension Driver Custom Properties

Name Description Mandatory?

Group Name

The name of this extension endpoint configuration group.

Yes

Endpoint URL

Remote endpoint listener URL.

Yes

Mapped Domain

The extension endpoint used to deliver messages where the domain part of the recipient URI matches this value.

No

Protocol

The extension endpoint used to deliver messages where the protocol (scheme) part of the recipient URI matches this value.

Yes

Security Policies

Comma-separated list of WS-Security policies to apply to this endpoint.

No

Username

Username to propagate through WS-Security headers.

No

Keystore Alias

Keystore alias to use for looking up WS-Security policy public keys.

No

Credential Store Key

Key to use for looking up the WS-Security username and password from the Oracle Web Services Management credential store map.

No


27.4.1.3.4 Extension Driver Security

If the remote extension endpoint is secured using WS-Security, then additional configuration of the extension driver is required. There are two typical WS-Security configurations that are supported. The extension driver can either use SAML tokens or username tokens.

To use extension driver security:

  1. To use SAML tokens, the Security Policies configuration property should contain value oracle/wss11_saml_token_identity_switch_with_message_protection_client_policy, and the Keystore Alias configuration property should contain a valid alias for keystore entries that is accepted by the remote extension endpoint.

  2. To use username tokens, the Security Policies configuration property should contain value oracle/wss11_username_token_with_message_protection_client_policy, and the Credential Store Key configuration property should contain a valid alias for a credential store entry that is accepted by the remote extension endpoint.

For more details about using WS-Security policies, see Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

27.4.1.3.5 Client API Messageinfo Support

Table 27-4 describes whether the protocol or driver implementation honors the following message delivery-related properties that are specified through the client API.

Table 27-4 Client API MessageInfo Support

Name Description Supported?

Expiration

Expiration means how much later in seconds for the message to expire.

False

Delay

Delay means how much later to send the message out.

False


27.4.1.3.6 Usage Instructions

Perform the following steps to use the extension driver:

To use the extension driver:

  1. Implement and deploy a web service listener endpoint based on the MessagingNotifyService WSDL (umsnotify.wsdl):

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                      xmlns:tns="http://xmlns.oracle.com/ucs/messaging/extension"
                      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                      name="MessagingNotifyService"
                      targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
     
        <wsdl:types>
     
        <xsd:schema targetNamespace="http://xmlns.oracle.com/ucs/messaging/extension">
          <xsd:element name="notification">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="messageId" type="xsd:string" minOccurs="0"
     maxOccurs="1">
                  <xsd:annotation>
                    <xsd:documentation>Unique message identifier from User
     Messaging Service.</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="sender" type="xsd:string">
                  <xsd:annotation>
                    <xsd:documentation>The sender address.</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="recipient" type="xsd:string">
                  <xsd:annotation>
                    <xsd:documentation>The recipient address (typically
     username).</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="subject" type="xsd:string" minOccurs="0"
     maxOccurs="1">
                  <xsd:annotation>
                    <xsd:documentation>The subject of the message, if
     available.</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="contentType" type="xsd:string"
     default="text/plain">
                  <xsd:annotation>
                    <xsd:documentation>The MIME type of the message. e.g.
     text/plain, text/html, text/xml.</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="content" type="xsd:string">
                  <xsd:annotation>
                    <xsd:documentation>The main body of the message. Textual
     content only (no binary content).</xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
                <xsd:element name="parameters" type="tns:parameter" minOccurs="0"
     maxOccurs="unbounded">
                  <xsd:annotation>
                    <xsd:documentation>Additional key-value pairs. This interface
     does not define any specific key-value pair meanings. Use of such parameters
     is defined on a private basis by particular implementations of this interface.
       </xsd:documentation>
                  </xsd:annotation>
                </xsd:element>
              </xsd:sequence>
            </xsd:complexType>
          </xsd:element>
          <xsd:complexType name="parameter">
            <xsd:sequence>
              <xsd:element name="name" type="xsd:string">
                <xsd:annotation>
                  <xsd:documentation>Parameter name</xsd:documentation>
                </xsd:annotation>
              </xsd:element>
              <xsd:element name="value" type="xsd:string">
                <xsd:annotation>
                  <xsd:documentation>Parameter value</xsd:documentation>
                </xsd:annotation>
              </xsd:element>
            </xsd:sequence>
          </xsd:complexType>
          <xsd:element name="notificationResponse">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="messageId" type="xsd:string" minOccurs="0"
     maxOccurs="1">
                  <xsd:annotation>
                    <xsd:documentation>A message identifier returned in response to
     successfully accepting the message. If returned, the identifier should be
     unique. Note: A fault is raised if the message cannot be
     accepted.</xsd:documentation>
                  </xsd:annotation></xsd:element>
              </xsd:sequence>
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="notificationFault">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="code" type="xsd:string"/>
                <xsd:element name="message" type="xsd:string"/>
              </xsd:sequence>
            </xsd:complexType>
          </xsd:element>
        </xsd:schema>
      </wsdl:types>
      <wsdl:message name="notifyRequest">
        <wsdl:part element="tns:notification" name="parameters" />
      </wsdl:message>
      <wsdl:message name="notifyResponse">
        <wsdl:part element="tns:notificationResponse" name="parameters"/>
      </wsdl:message>
      <wsdl:message name="notifyException">
        <wsdl:part element="tns:notificationFault" name="parameters"/>
      </wsdl:message>
      <wsdl:portType name="Notify">
        <wsdl:operation name="invoke">
          <wsdl:input message="tns:notifyRequest"/>
          <wsdl:output message="tns:notifyResponse"/>
          <wsdl:fault message="tns:notifyException" name="NotifyException"/>
        </wsdl:operation>
      </wsdl:portType>
      <wsdl:binding name="NotifySOAPBinding" type="tns:Notify">
        <soap:binding style="document"
     transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="invoke">
          <soap:operation
            soapAction="http://www.oracle.com/ucs/messaging/extension" />
          <wsdl:input>
            <soap:body use="literal" />
          </wsdl:input>
          <wsdl:output>
            <soap:body use="literal" />
          </wsdl:output>
          <wsdl:fault name="NotifyException">
            <soap:fault name="NotifyException" use="literal"/>
          </wsdl:fault>
        </wsdl:operation>
      </wsdl:binding>
     
      <wsdl:service name="NotifyService">
        <wsdl:port binding="tns:NotifySOAPBinding" name="Notify">
          <soap:address location="http://localhost:8001/NotifyService"/>
        </wsdl:port>
      </wsdl:service>
    </wsdl:definitions>
    
  2. Configure the extension driver.

    1. Target the predeployed extension driver called usermessagingdriver-extension or a new deployment to the appropriate servers where UMS (usermessagingserver) is running and start the driver.

    2. In Enterprise Manager Fusion Middleware Control, navigate to the usermessagingserver home page.

    3. Click User Messaging Service > Driver Properties.

    4. Select and Edit the driver usermessagingdriver-extension or create a new driver with the same name as your new driver deployment.

    5. Under Driver-Specific Configuration, add a new extension endpoint configuration group and specify the correct properties: EndpointURL is the URL to the web service listener endpoint created in Step 1. Protocol is the value of the new messaging channel for which you want to add notification support (for example, popup).

    6. Under Common Configuration, update Supported Protocols with a comma-separated list of protocols defined in each Extension Endpoint group.

    7. Click OK to save the configuration.

This completes the configuration and integration of a new messaging channel (protocol) in UMS using the extension driver.

To send notifications to this new channel (protocol), recipients must be specified for the URI delivery type using the URI addressing format:

URI:scheme:scheme-specific-address-value

where scheme is the protocol. The URI delivery type is optional. For example, if the extension driver was configured to support the protocol popup, an application can compose a message to popup:john.doe@example.com.

End users can also declare their messaging preferences by creating a new messaging channel for the new channel type in the Worklist/UMS Preferences UI. User preferences are only applied when applications send user-based notifications (that is, to recipients of the form USER:username).

Note:

Proper configuration of SSL/TLS in the Oracle WebLogic Server container is a prerequisite for secure connections between UMS and the email server. See "Configuring SSL" in Oracle Fusion Middleware Securing Oracle WebLogic Server.

27.4.1.4 Configuring the Email Driver

The email driver both sends and receives messages (that is, its capability property is set to both by default). The email driver sends messages over SMTP and uses either IMAP or POP3 for receiving messages.

Note:

For information about configuring the email driver with human workflow from the Workflow Notification Properties page, see Section 21.1, "Configuring Human Workflow Notification Properties."

For troubleshooting Human Workflow Notification issues, see Table 27-29, "Troubleshooting UMS".

27.4.1.4.1 Email Driver Interoperability

This section details interoperability features of the email driver.

The email driver is compatible with these protocols: POP3, IMAP4, and SMTP.

Note:

Oracle suggests that you specify IMAP as the protocol in a high-availability environment.

Email driver features include:

  • Automatic connection retry

  • SMTP for message sending

  • IMAP4 and POP3 for message receiving (using polling)

  • scalable, highly available

  • Message loss prevention and duplication avoidance

The gateway vendors and versions in Table 27-5 have been verified.

Table 27-5 Email 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


27.4.1.4.2 Common Properties

Table 27-6 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging 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 27-6 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


27.4.1.4.3 Email Custom Properties

Table 27-7 lists properties specific to this driver and generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Note:

The following fields must be configured if UMS is used for incoming emails:

  • IncomingMailServer

  • IncomingMailServerPort

  • IncomingMailIDs

  • IncomingUserIDs

  • IncomingUserPasswords

Table 27-7 Custom Email Properties

Name Description Mandatory? Default Value

* These fields must be configured only if UMS is used for incoming emails.

MailAccessProtocol

Email receiving protocol. The possible values are IMAP and POP3. Required only if email 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 for some reason. The default value is -1, which means there is no limit to the number of tries.

No

-1

MailDelFreq

The frequency to permanently remove deleted messages. The unit is in seconds and the default value is 600 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 default is Disabled. For the POP3 protocol, the messages are always deleted right after they are processed.

No

Disabled

Debug

This value indicates if the driver is running in Debug mode. When enabled, JavaMail prints out requests and responses between the email driver and the mail server to Fusion Middleware Control. The default is Disabled.

No

Disabled

CheckMailFreq

The frequency with which to retrieve messages from the mail server. The unit is in seconds and the default value is 30 seconds.

No

30

ReceiveFolder

The name of the folder from which the driver is polling messages. The default value is INBOX.

No

INBOX

OutgoingMailServer

The name of the SMTP server. This is mandatory only if email sending is required.

No

N/A

OutgoingMailServerPort

The port number of the SMTP server; typically 25.

No

25

OutgoingMailServerSecurity

The security setting used by the SMTP server. Possible values are None, TLS, and SSL. The default value is None.

No

None

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. This is required only if SMTP authentication is supported by the SMTP server. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.

No

N/A

IncomingMailServer

The hostname of the incoming mail server. Required only if email receiving is supported on the driver instance.

No*

N/A

IncomingMailServerPort

Port number of IMAP4 (that is, 143 or 993) or POP3 (that is, 110 or 995) server.

No*

N/A

IncomingMailServerSSL

Indication to enable SSL when connecting to IMAP4 or POP3 server. The default is Disabled.

No*

Disabled

IncomingMailIDs

The email addresses corresponding to the user names. Each email 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 email receiving is supported on the driver instance.

No*

N/A

IncomingUserIDs

The list of user names of the mail accounts from which the driver instance is polling. Each name must be separated by a comma, for example, foo,bar. This is required only if email 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. This is required only if email receiving is supported on the driver instance. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.

No*

N/A

ProcessingChunkSize

The number of messages processed during each message polling. The default is 100.

No

100

ImapAuthPlainDisable

Indication to disable or enable plain text authentication (AUTHENTICATE PLAIN command) for IMAP user authentication. The default is Disabled.

No

Disabled. When this property is disabled, that means that plain text is allowed.


27.4.1.4.4 Client API Messageinfo Support

These properties are message delivery-related that are specified through client API. Table 27-8 describes if the protocol or driver implementation honors such properties.

Table 27-8 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

False

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.4.1.5 Configuring the SMPP Driver

Short Message Peer-to-Peer (SMPP) is a popular GSM SMS protocols. User Messaging Service includes a prebuilt implementation of the SMPP protocol as a driver that can send and receive short messages. If the sending feature is enabled, the SMPP driver opens one TCP connection to the Short Message Service Center (SMS-C) 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 or an SMS gateway that supports this version.

27.4.1.5.1 SMPP Driver Interoperability

This section details interoperability features of the SMPP Driver.

The SMPP driver is compatible with this protocol: 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 27-9 have been verified.

Table 27-9 SMPP Driver Gateway Vendors

Vendor

Syniverse

Clickatell

Logica CMG

OpenSMPP (simulator)


27.4.1.5.2 Common Properties

Table 27-10 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging 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 27-10 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


27.4.1.5.3 Custom Properties

Table 27-11 lists properties specific to this driver and generally associated with configuring access to the remote gateway and certain protocol or channel-specific behavior.

Table 27-11 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 messages.

Yes

N/A

ReceiverSystemId

The account ID that is used to receive messages.

Yes

N/A

TransmitterSystemType

The type of transmitter system. The default is Logica.

Yes

The default value is Logica.

ReceiverSystemType

The type of receiver system. The default is Logica.

Yes

The default value is Logica.

TransmitterSystemPassword

The password of the transmitter system. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.

Yes

N/A

ReceiverSystemPassword

The password for the receiver system. This includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, and Use Cleartext Password) and Password.

Yes

N/A

ServerTransmitterPort

The TCP port number of the transmitter server.

Yes

N/A

ServerReceiverPort

The TCP port number of the receiver server.

Yes

N/A

DefaultEncoding

The default encoding of the SMPP driver. The default is IA5. Choose from the drop-down list: IA5, UCS2, and GSM_DEFAULT.

No

IA5

EncodingAutoDetect

If enabled, the SMPP driver encodes automatically. The default is Enabled.

No

Enabled

LocalSendingPort

The local TCP port used by the SMPP driver to send messages to the SMS-C.

No

N/A

LocalReceivingPort

The local TCP port used by the SMPP driver to receive messages from the SMS-C.

No

N/A

LocalAddress

The hostname (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. Default is 1.

No

1

EnquireInterval

The interval, in seconds, to send an enquire message to the SMS-C. The default is 30 seconds.

No

30

ThrottleDelay

The delay, in seconds, between throttles. Default is 30.

No

30

BindRetryDelay

The minimum delay, in seconds, between bind entry attempts. Default is 30.

No

30

ResponseTimer

Time lapse allowed between SMPP request and response, in seconds. The default is 30.

No

30

RegisteredDeliveryMask

The registered delivery bit mask. The default is 0xFF, which does not change the delivery flag value.

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. The default is Disabled.

No

Disabled

PriorityAllowed

The highest priority allowed for the SMPP driver. The range is 0 (normal) to 3 (highest). The default is 0.

No

0

BulkSending

Setting this value to enabled (the default) enables sending messages in bulk to the SMS-C.

No.

Enabled

PayloadSending

If you enable this property, the SMPP driver always uses the message_payload parameter that is defined in the SMPP specification, while sending a message to the SMS-C. The default is Disabled.

No

Disabled

SourceTon

The type of number (TON) for ESME address(es) served through SMPP receiver session. The default is 0.

No

0

SourceNpi

The numbering plan indicator (NPI) for ESME address(es) served through the SMPP receiver session. The default is 0.

No

0

DestinationTon

The TON for destination. The default is 0.

No

0

DestinationNpi

The NPI for destination. The default is 0.

No

0

ExtraErrorCode

A comma-separated list of error codes.

No

N/A

MaxChunks

The maximum SMS chunks for a message. The default is -1 (no maximum).

No

-1 (no maximum)

ChunkSize

The size of each SMS message chunk. Default is 160.

No

160

LongMessageSending

Supports sending long messages. The default is Disabled.

No

Disabled

DatagramMessageMode

Supports datagram message mode. The default is Disabled.

No

Disabled


27.4.1.5.4 Client API MessageInfo Support

These properties are message delivery-related that are specified through client API. Table 27-12 describes if the protocol or driver implementation honors such properties.

Table 27-12 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

True

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.4.1.6 Configuring the XMPP Driver

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

27.4.1.6.1 Introduction to XMPP

XMPP is an open, XML-based protocol for IM 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 email 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 an XMPP ID (or Jabber ID or JID) with the following form: [username]@domain[/resource]. See RFC 3920 for details on the addressing scheme.

In an XMPP network, users identified by their XMPP IDs as mentioned above (which typically consist of a username and the domain of the XMPP server to which the user connects). An end user of XMPP connects to an XMPP server using an XMPP client to send instant messages to other XMPP users. XMPP, however, is not the only protocol network available for IM. XMPP has an extensible and modular architecture. It integrates with proprietary IM networks, enabling XMPP users to communicate with those on other networks.

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 with which to log in.

27.4.1.6.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 27-13 have been verified.

Table 27-13 XMPP Driver Gateway Vendors and Versions

Vendor Version

ejabberd

2.1.3

jabberd2

2.2.14

jabberd14

1.6.1.1-p1

Oracle Beehive

2.0.1.2.1


27.4.1.6.3 Third-Party Software

The XMPP Driver uses or requires the following third-party software (you may optionally choose to install and configure your own XMPP server):

Table 27-14 Required Third-Party Software

Name Instructions Version(s)

Apache Smack

This driver uses the Apache Smack XMPP Java library to connect to a Jabber/XMPP IM Server. This driver includes a licensed copy of Smack (version 3.0.4).

3.0.4


Note:

You are not required 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.

27.4.1.6.4 Driver Application Archive (EAR)

The EAR file is $ORACLE_HOME/communications/applications/sdpmessagingdriver-xmpp.ear.

27.4.1.6.5 Common Properties

Table 27-15 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging 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 27-15 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 a cancel operation on the message

No

False

SupportsReplace

Supports a replace operation on the message

No

False

SupportsTracking

Supports a tracking operation on the message

No

False

SupportsStatusPolling

Supports a 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 information

Yes

OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1


27.4.1.6.6 XMPP Custom Properties

The XMPP Driver includes the custom properties shown in Table 27-16.

Table 27-16 Custom XMPP Properties

Name Description Mandatory Default Values

IMServerHost

Jabber/XMPP server hostname.

No

N/A

IMServerPort

Corresponding Jabber/XMPP server port. The default is 5222.

Yes

5222

IMServerUsername

Jabber/XMPP username with which you log in. You may also enter a complete Jabber ID if its domain name is different from the Jabber/XMPP server hostname (for example: myUserName or myUserName@xmpp-domain).

Note: An attempt is made to register this user account if it does not exist and the server supports account registration.

No

N/A

IMServerPassword

Corresponding password for the username listed above. Includes Type of Password (choose from Indirect Password/Create New User, Indirect Password/Use Existing User, Use Cleartext Password) and Password.

No

N/A

SecurityMode

Security mode to use when making a connection to the server. Available options are: None (Security is disabled and only unencrypted connections are used), TLS (Security through TLS encryption is used whenever it is available), and SSL (Security through SSL encryption is used). The default is TLS.

No

TLS

SASLAuthenticationEnabled

Whether to use SASL authentication when logging into the server. If SASL authentication fails, then the driver tries to use non-SASL authentication. By default, SASL is enabled.

No

Enabled


27.4.1.6.7 Client API MessageInfo Support

These properties are message delivery-related that are specified through the client API. Table 27-17 describes if the protocol or driver implementation honors such properties.

Table 27-17 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

False

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.4.1.7 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.

27.4.1.7.1 VoiceXML Driver Interoperability

This section details interoperability features of the VoiceXML Driver.

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

The VoiceXML driver features include:

  • VoiceXML content only

The gateway vendor and version in Table 27-18 has been verified.

Table 27-18 VoiceXML Driver Gateway Vendor and Version

Vendor Version

Genesys VoiceGenie

6.4.2


27.4.1.7.2 Common Properties

Table 27-19 lists common driver properties that are indicative of the capabilities of this driver for use by the messaging 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 27-19 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


27.4.1.7.3 VoiceXML Custom Properties

The VoiceXML Driver includes the custom properties shown in Table 27-20.

Table 27-20 Custom VoiceXML Properties

Name Description Mandatory Default Values

VoiceXMLOutboundServletURI

The URL of the VoiceXML gateway.

Yes

N/A

VoiceXMLOutboundServletUserName

The user name of the VoiceXML gateway.

No

N/A

VoiceXMLOutboundServletPassword

The password of the user of the VoiceXML gateway.

No

N/A

VoiceXMLOutboundServletDNIS

The number that should appear in the recipient's caller ID display.

No

N/A

VoiceXMLReceiveURL

The URL of this driver's servlet that handles 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 listener host and port. The default behavior only works 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


Note:

In a clustered (high-availability) environment with Oracle HTTP Server (OHS) configured, do not use the OHS port to configure the VoiceXML driver receive URLs. Using the OHS port to configure the VoiceXML driver receive URLs causes a conflict with the drivers.

Each VoiceXML driver must be configured with its own WLS server's port.

27.4.1.7.4 Client API MessageInfo Support

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

Table 27-21 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

False

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.4.1.8 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 Portal Unified Worklist.

Note:

Worklist message tasks are accessible both through an Oracle WebCenter Portal that has been configured to search the BPEL connection to which the worklist message driver is sending messages, and through Oracle BPM Worklist. Oracle BPM Worklist also shows 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.

Note:

The worklist channel supports all rich text tags supported by the af:richTextEditor for the text/html content type. For more information about the Rich Text Editor, see <af:richTextEditor>.

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

You can install the Worklist Driver onto an Oracle WebLogic platform, or onto an IBM WebSphere platform. Choose the appropriate installation instructions below.

27.4.1.8.1 Install the Worklist Driver on the Oracle WebLogic Server Platform

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 computer: 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 computer, 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.

To complete the installation, copy the contents of $DOMAIN_HOME/soa/autodeploy from the AdminServer computer to the corresponding location on the remote computer 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 computer.

27.4.1.8.2 Install the Worklist Driver on IBM WebSphere Platform

To enable the messaging worklist feature, the WebSphere SOA cell must be extended using the extension template available at $ORACLE_HOME/common/templates/was/oracle.ums.driver.worklist_template_11.1.1.jar.

To extend a SOA cell using the Oracle Fusion Middleware Configuration Wizard:

  1. Set the environment variable CONFIG_JVM_ARGS with the value -DTemplateCatalog.enable.selectable.all=true. For example, in Linux bash shell: exportCONFIG_JVM_ARGS="-DTemplateCatalog.enable.selectable.all=true"
    At the Windows command prompt: set CONFIG_JVM_ARGS=-DTemplateCatalog.enable.selectable.all=true

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

  3. Click Select and Configure Existing Cell.

  4. Select the desired SOA cell and click Next.

  5. Select Oracle User Messaging Service Worklist Driver on the Add Products to Cell screen and click Next.

  6. Complete the remaining steps of the Oracle Fusion Middleware Configuration Wizard with default selections, and restart the SOA cell.

27.4.1.8.3 Common Properties

The common driver properties shown in Table 27-22 are indicative of the capabilities of this driver for use by the messaging 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 27-22 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 information

Yes

OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1


27.4.1.8.4 Custom Properties

The custom property shown in Table 27-23 is available.

Table 27-23 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, if this property is not set, is to use the local container's HTTP connection URL.

   

27.4.1.8.5 Client API MessageInfo Support

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

Table 27-24 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

False

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.4.1.9 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 and return message delivery status. The ParlayX Web Service relays messages from one UMS instance to another. It can 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.

27.4.1.9.1 Common Properties

Table 27-25 shows common driver properties that are indicative of the capabilities of this driver for use by the messaging 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 27-25 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 information

Yes

OraSDPM/QueueConnectionFactory:OraSDPM/Queues/OraSDPMDriverDefSndQ1


27.4.1.9.2 Proxy Custom Properties

The Proxy Driver includes the custom properties shown in Table 27-26.

Table 27-26 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-delimited list of Oracle Web Services Manager WS-Security policies to be attached to proxy driver requests

No

N/A


27.4.1.9.3 Client API MessageInfo Support

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

Table 27-27 Client API MessageInfo Support

Name Description Support

Expiration

Expiration means how long the message may exist until it expires.

False

Delay

Delay means the amount of time that must elapse before the message is sent.

False


27.5 Configuring User Messaging Service Access to the LDAP User Profile

As part of the LDAP provider setup in a SOA deployment, you configure the "User Name Attribute" through the WebLogic Server Administration Console. If you configure that attribute with a value other than the default "cn" or if the user's email address is stored in an LDAP attribute which is different from "mail", you must make an additional configuration change in Oracle Platform Security Services (OPSS) for UMS to successfully access the user profile to obtain the list of communication channels provisioned in LDAP, such as business email.

For more information about Oracle Platform Security Services (OPSS), see Oracle Fusion Middleware Application Security Guide.

To configure access to the LDAP user profile:

  1. Modify the jps-config.xml file in the $DOMAIN_HOME/config/fmwconfig directory by adding a <property> element in the idstore.ldap serviceInstance section.

    • To use the value of the User Name Attribute while searching the back-end LDAP server for user profile, add the following element:

      <property name=”username.attr” value=”username_attribute_value”/>
      

      where username_attribute_value is the value of the User Name Attribute property in the LDAP provider configuration. For instance, if the value of the User Name Attribute is mail, add the following line:

      <property name=”username.attr” value=”mail”/> 
      

      The following sample code shows the above line inserted in the jps-config.xml file:

      <!-- JPS WLS LDAP Identity Store Service Instance --> 
        
      <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider"> 
       
        <property name="idstore.config.provider"
      value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvide
      r"/> 
      
        <property name="CONNECTION_POOL_CLASS" 
      value="oracle.security.idm.providers.stdldap.JNDIPool"/> 
       
        <property name=”username.attr” value=”mail”/> 
       
      </serviceInstance>
       
      
    • If the LDAP attribute containing the user's business email addresses is something other the mail attribute, add the following element:

      <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_EMAIL=attr_containing_email"/>
      

      where attr_containing_email is the attribute name in the LDAP provider that contains the user's email address. For instance, if the user attribute containing the email address is externalEmail, add the following line:

      <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_EMAIL=externalEmail"/>  
      

      The following sample code shows the above line inserted in the jps-config.xml file:

      <!-- JPS WLS LDAP Identity Store Service Instance --> 
        
      <serviceInstance name="idstore.ldap" provider="idstore.ldap.provider">  
       
        <property name="idstore.config.provider"
      value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvide
      r"/>  
      
        <property name="CONNECTION_POOL_CLASS"
       value="oracle.security.idm.providers.stdldap.JNDIPool"/>  
       
        <property name="PROPERTY_ATTRIBUTE_MAPPING" value="BUSINESS_
      EMAIL=externalEmail"/> 
       
      </serviceInstance>
       
      

    Note:

    You may have other properties defined in the same section.

  2. Restart your domain.

27.6 Securing the Oracle 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 are deployed in a production environment.

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 because 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:

27.6.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 fails because the notification SOAP request is missing the required headers.

27.6.2 Enabling UMS Service Security

To enable a policy for a 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 you want to secure.

27.6.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 27-28) should be added to the configuration map in addition to other required properties such as the endpoint address.

Table 27-28 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

(optional) <valid username>

Note: Do not specify this key while using oracle/wss11_saml_token_with_message_protection_client_policy.

oracle.wsm.security.util.SecurityConstants.Conf
ig.KEYSTORE_RECIPIENT_ALIAS_PROPERTY

String

(optional) keystore alias for target service. See Client Aliases.


Example 27-1 Web Service Client Security

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"});
 
SendMessageClient sendClient = new SendMessageClient(config);

27.6.4 Keystore Configuration

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.

27.6.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 be required 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 27-2.

    Example 27-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 similarly must 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.

27.6.6 Securing JMS Resources

This (optional) procedure enables administrators to restrict access to the Oracle User Messaging Service's JMS resources (such as queues) for enhanced security.

Note:

This section details steps to follow to secure JMS Resources. If you are starting with a new installation (11g Release 1 11.1.1.3) of Oracle User Messaging Service, then follow these steps.

If you are not upgrading to 11g Release 1 11.1.1.3, then these instructions are not to be used.

If you previously created a domain in an earlier release and are upgrading, but have not already done so, then complete the steps in the latest Release Notes before proceeding.

To secure the JMS system resources, lock all JMS sub-deployments that start with the name UMSJMSSystemResource (there may be multiple automatically-created resources for UMS in a multi-server or cluster deployment) with the role OracleSystemRole. Do this using the Oracle WebLogic Server Administration Console, or you may run a WLST script (available at $ORACLE_HOME/communications/bin/secure_jms_system_resource.py) as follows:

$ORACLE_HOME/common/bin/wlst.sh
$ORACLE_HOME/communications/bin/secure_jms_system_resource.py
--username=<admin_username> --password=<password>
--url=t3://<admin-host>:<admin-port> --jmsSystemResource
<UMSJMSSystemResource> --role OracleSystemRole

For example:

$ORACLE_HOME/common/bin/wlst.sh
$ORACLE_HOME/communications/bin/secure_jms_system_resource.py
--username=weblogic --password=<password> --url=t3://localhost:7001
--jmsSystemResource UMSJMSSystemResource --role OracleSystemRole

By default, the UMS system runs as the user OracleSystemUser for accessing JMS resources. If the user OracleSystemUser does not exist, or you secure the UMS JMS resources with any other role that some other user has been granted, you must override the default user identity used by the UMS system by specifying an alternate username for the following JVM system property when you start the container:

oracle.ums.system.user=<username>

For example, if the user is MySystemUser, you can pass the JVM system property on command line as: -Doracle.ums.system.user=MySystemUser

27.7 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. Table 27-29 describes additional methods for debugging common User Messaging Service problems.

Table 27-29 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 email 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 only sends 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-delimited list of <DeliveryType>:<Address>.

    For example:

    EMAIL:sender@example.com, EMAIL:sender@example2.com

  • 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 value in SenderAddresses to only service outbound messages with that matching sender address, while the other instance can keep the SenderAddresses blank 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 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 email 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

  • IncomingUserIDs

  • IncomingUserPasswords

  • ImapAuthPlainDisable

Note: Validate the values by using them in any email 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 nondefault 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 use 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 predefined channel names, such as Business Email, Business Mobile, Business Phone, Instant Messaging. Use these predefined messaging channels instead for BPEL User Notification and Human Workflow use cases.