11 Oracle JCA Adapter for UMS

This chapter describes how to use the Oracle User Messaging Service Adapter, which provides a JCA Adapter that wraps the Oracle User Message Service (UMS), an Oracle Fusion Middleware Component that enables communication between users and applications. The chapter also provides information on UMS Adapter concepts, features, configuration, and error handling.

This chapter includes the following sections:

Section 11.1, "UMS and UMS Adapter Concepts"
Section 11.1.1, "Oracle UMS Adapter"
Section 11.2, "Oracle UMS Adapter Features"
Section 11.2.2, "UMS Adapter Error Handling and Transactions"
Section 11.2.3, "Configuring the Oracle UMS Adapter"

11.1 UMS and UMS Adapter Concepts

The User Messaging Service is an Oracle Fusion Middleware Component that enables communication between users and application. It consists of the following:

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.

UMS supports various messaging channels such as Email, SMS, Instant Messaging, and Voice. UMS provides a messaging proxy between the Oracle BPEL or Mediator products and the external world. The User Messaging Service provides two-way messaging: Inbound and Outbound messaging, and provides robust message delivery, including delivering delivery status, and message resend through Enterprise Messages. UMS also provides support for failover address. In summary, the UMS provides a scalable, highly available solution to communication between users and applications.

For additional information on the User Messaging Service, see the Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite.

11.1.1 Oracle UMS Adapter

The User Messaging Service Adapter implements the Java Enterprise Edition Connector Architecture (JCA) version 1.5. The UMS Adapter, in effect, wraps the User Messaging Service, thus enabling communication over messaging channels that include Email.

The UMS Adapter is part of the overall Adapter architecture.J2EE Applications, Mediator and BPEL processes communicate with the Oracle WebLogic Server. See the following diagram.

Figure 11-1 The UMS Adapter as Part of the Adapter Architecture

Description of "Figure 11-1 The UMS Adapter as Part of the Adapter Architecture"

11.2 Oracle UMS Adapter Features

The UMS Adapter includes these features

Support of Email Messaging Channels.
Use of Message Filters-the UMS Adapter enables you to filter email messages in two ways:
1. Establishing Message filters through the Adapter Configuration Wizard Messages Filter Screen,. These include Message filters, Blacklist and Whitelist filters. Message Filters provide the ability to filter incoming messages based on the Email To address, From address, CC address, Subject, and Mail Headers. Mails can similarly be ignored using this filtering. Note: there is no filtering available on the BCC address.
2. Writing and packaging a Java Callout, and providing the name of the callout through the Adapter Configuration Wizard.
Sending Email messages with Subject and Body.
Translation Support for the Email message body.
SSL/TLS security for the outbound SMTP server (this availability is provided through the Java Messaging Service).

The UMS Adapter provides the following Inbound features:

Support for Email Messaging channels.
Reception of messages with Subject, Body and one or more attachments along with internet mail and mime headers.
A Polling/Listener interface. The Adapter polls mailboxes for incoming email on various schedules you establish, which can be both sequential and parallel.
Translation support for the Email message body
XA-enabled transactions with Last Resource Commit (LRC) optimization to participate in global transactions on inbound messages. Note that the UMS Adapter does not support XA Transactions on the Outbound message transactions.
IMAP/POP3 servers with SSL (available through the UMS Server)

Note:

You cannot set and get headers with Keyword headers when you use the MS-2010 Mail server with the UMS Adapter

11.2.1 UMS Adapter Message Concepts

The UMS Adapter enables you to provide different message formats.

For many of your email use cases, you might not want to specify a schema as the message payload could be plain text and you want it received as is. In that case, you can then select the Message is String type checkbox on the Messages Screen.

For example, if you want to send an image of binary data, you can specify the Message is Opaque(Base64Binary)option. If you choose this option, the content will be base64 encoded before being sent.

XSD files are required for translation of messages. If you want to define a new schema or convert an existing data type definition (DTD) or COBOL Copybook you must select Define Schema for Native Format to supply an XSD file.

Selecting Define Schema for Native Format starts the Native Format Builder wizard. This wizard guides you through the creation of a native schema file from file formats that include comma-separated value (CSV), fixed-length, DTD, and COBOL Copybook.

After the native schema file is created, the Messages page is displayed, with the Schema File URL and Schema Element fields filled in.

Unlike other adapters, the UMS Adapter uses a predefined Message Schema to represent the message it uses.

An example of the Message Schema that the UMS Adapter uses follows.

<?xml version= "1.0" encoding= "UTF-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://platform.integration.oracle/blocks/adapter/fw/
metadata/Inbound_UMS"
            targetNamespace="http://platform.integration.oracle/blocks/adapter/ 
            fw/metadata/Inbound_UMS"
            xmlns:imp1="http://xmlns.oracle.com/pcbpel/adapter/opaque/"
            elementFormDefault="qualified" attributeFormDefault="unqualified">
<xsd:import namespace="http://xmlns.oracle.com/pcbpel/adapter/opaque/"   schemaLocation="opaque.xsd"/>
    <xsd:complexType name="MessageType">
        <xsd:sequence>
            <xsd:element ref="imp1:opaqueElement"/>
            <xsd:element name="attachment" type="AttachmentType" minOccurs="0"
                 maxOccurs="unbounded"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:complexType name="AttachmentType">
        <xsd:attribute name="href" type="xsd:string"/>
    </xsd:complexType>
    <xsd:complexType name="ResponseType">
        <xsd:sequence>
            <xsd:element name="MessageId" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="message" type="MessageType"/>
    <xsd:element name="response" type="ResponseType"/>
</xsd:schema>Status OpenFixedClosed

You define the schema according to your translation requirement through the UMS Adapter Configuration Wizard Message screen, and as defined for the message body content). The UMS Adapter imports the xsd you specify into the message schema used by the UMS Adapter.

For example, see the schema snippet below, where the user-defined schema singleString.xsd would be imported through the UMS Adapter Configuration Wizard and refers to the element singleString, which is defined under singleString.xsd through the UMS Adapter Configuration Wizard.

<?xml version= '1.0' encoding= 'UTF-8' ?>
<xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
            targetNamespace="http://xmlns.oracle.com/singleString"
            xmlns="http://xmlns.oracle.com/singleString"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd"
            nxsd:encoding="US-ASCII" nxsd:useArrayIdentifiers="true"
            nxsd:stream="chars" nxsd:version="NXSD">
    <xsd:complexType name="singleString">
        <xsd:sequence>
            <xsd:element name="input" type="xsd:string" nxsd:style="terminated"
                         nxsd:terminatedBy=";"/>
        </xsd:sequence>
    </xsd:complexType>
    <xsd:element name="payload" type="singleString"/>
</xsd:schema>

The following snippet illustrates the Interaction Specification:

<adapter-config name="SendEmail" adapter="UMS Adapter"
                wsdlLocation="SendEmail.wsdl"
  xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  <connection-factory location="eis/ums/UMSAdapter"/>
  <endpoint-interaction portType="SendEmail_ptt" operation="SendEmail">
    <interaction-spec className="oracle.tip.adapter.ums.outbound.UmsInteractionSpec">
      <property name="DeliveryType" value="Email"/>
      <property name="From" value="scott.tiger@example.com"/>
      <property name="To" value="scott.parker@example.com"/>
      <property name="ReplyTo" value=" scott.tiger@example.com"/>
      <property name="Subject" value="Test Email"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

Note:

For the UMS Adapter, message metadata accompanies the message file itself. if you examine the message.dat file, you would see the whole email message including all of the internet and mime headers and the payload. This is similar to what you would see if you performed view->message source from any mail client. Message metadata that are keywords defined and used under user preference based messaging are also be exposed by the adapter as message headers. See the Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite for more information.)

11.2.1.1 Custom Java Callout

On the Java Callout Screen you can specify a custom Java class with custom logic that can be invoked before the Email message is processed by the UMS Adapter.

11.2.1.1.1 Use Cases for Custom Java Callout

One simple use case of the Custom Java Callout is to match the sender address with an address in the LDAP or that resides in a staging area and which has been recorded earlier. To provide this use case, you must implement the interface oracle.tip.pc.services.translation.util.ICustomCallout.

This interface defines a single method execute with a return value of boolean. Depending on the return value, the message is either processed or rejected:

public Inteface CustomCallout{
  public boolean execute (Message message) throws exception;
}

Where Message is the Message class from the UMS Session Description Protocol (SDP) Java API, a well-defined Java API provided by the UMS Server, which can be found at jdeveloper\communications\modules\oracle.sdp.messaging_11.1.1\sdpmessaging.jar . The Boolean value returned indicates whether to accept and process the message or to reject the message.

package oracle.adapter.custom;

import java.io.File;
import oracle.sdp.messaging.Message;
import oracle.tip.pc.services.translation.util.ICustomCallout;
 
public class UMSAdapter_CustomCall implements ICustomCallout{
 
        @Override
        public boolean execute(Message message) throws exception {
        String emailFromAddress = message.getSenders()[0]
.getValue();
 
String fileName = "/tmp/OracleStore/staging/".
concat(emailFromAddress).concat(".usr");
                File file = new File(fileName);
                if(file.exists()) {
                        return true;
                }
                return false;
        }
}

In another use case, as provided through the sample code, a user with the email id of scott.tiger@example.com registers through an internet store web site. The user would be recorded under a staging area by using a file name scott.tiger@example.com.

An email is sent to the user directly to his email id to reply to the sent email. If the user replies to the email, the UMS Adapter picks the email. You can subsequently use a Java Callout to check and ensure the user has registered through the web site.

11.2.1.1.2 Using the Custom Callout Facility

To use the Custom Callout facility, you must

Indicate the name of the class on the Java Callout Screen in the UMS Adapter Configuration Wizard
Bundle the class and other required custom classes as a jar file.
Place the jar file under your Composite Application, under the SCA-INF/lib directory.
A custom java Class can also be packaged along with the composite and deployed rather than placing them in domain directory for WebLogic Server by any of the following two methods:
- The compiled Java class (.class file) can be directly placed under the Composite Project Folder \SCA-INF\classes and deployed.
- Alternatively, the compiled Java class can be made as a JAR and placed under the Composite Project Folder and deployed \SCA-INF\lib

11.2.2 UMS Adapter Error Handling and Transactions

The UMS Adapter, like other technology adapters, uses the default Adapter rejection handling mechanism on the inbound side to reject bad messages.

For example, any translation-related error results in message rejection via the standard handling mechanism. This enables the definition of policies for handling runtime exceptions to ensure that errors can be analyzed. For more information on policies for handling exceptions, see the information in Chapter 2 on error handling.

11.2.2.1 Using a JNDI Name Configured to Use XA With LRC Optimization

The UMS Adapter, by default, uses an XA Transaction with an Inbound Scenario. For this, the Adapter configures a connection factory instance with the property XATransaction set to true, along with transaction support set to Local Transaction under the adapter deployment descriptor. This configuration is required, as the UMS Adapter provides an LRC (Last Resource Commit) optimization to normal XA. LRC is a performance enhancement option that enables one non-XA resource to participate in a global transaction

A default JNDI instance is available, by default, which is configured to use XA. The name of this default JNDI instance is eis/ums/UMSAdapterInbound.

For outbound scenarios, a default JNDI instance, eis/ums/UMSAdapterOutbound is provided. With this JNDI instance, the transaction support is set to NoTransaction.

You can choose to define your own JNDI instances and use them, but you should keep in mind the discussion above.

11.2.2.2 Inbound Error Handling

The UMS Adapter uses the default rejection handling mechanism on the Inbound side of the Adapter for rejecting bad messages. For example, any translation-related errors result in message rejection. Refer to the section on creating fault policies in this Guide for more information on fault policies and adapters.

Under retriable error conditions, and when you specify retry-related endpoint properties, the Adapter tries to re-publish the Inbound message for the configured number of retries before rejecting the message. Transactions are then set for rollback under XA, per the JNDI and XA discussion above.

For non-retriable Inbound error conditions, the message is immediately rejected, with transaction set for the rollback when XA is used.

11.2.2.3 Outbound Error Handling

The UMS Adapter throws an exception for transient (recoverable) error conditions such as connection errors. For retriable errors, you can use a retry policy supported by the Adapter framework; to do this, you can set the binding property jca.retry.count to a retry count you want. Again, as with other Adapters, if you do not set the property, the retry is carried through according to the fault policy.

You can define non-retriable connection errors for outbound transactions through a fault policy. The maximum number of reconnection attempts can be defined through fault-policy.xml.

Adapters translate data from Native representation to standard XML format and back based on the metadata captured by your work at design time, through the Adapter Configuration Wizard. A translation error is thrown when there is an exception thrown by carrying out the translation, and a corresponding binding fault is also thrown.

You can set Endpoint properties related to Outbound retriable errors, as shown in Table 11-1, "UMS Adapter Outbound Endpoint Properties"

Table 11-1 UMS Adapter Outbound Endpoint Properties

Property	Description
`jca.retry.count`	Indicates the maximum number of retries before thrrowing retriable error conditions back to the invoking service engine.
jca.retry.interval	Indicates the time interval between retries, measured in seconds.
jca.retry.backoff	Indicates the retry interval growth factor, measured in positive integers.
jca.retry.maxInterval	Indicates the maximum value of retry interval; that is a cap if the value is greater than 1.
`jca.retry.maxPerio`d	Indicates the maximum total retry period. Retries do not occur longer than the value specified in the parameter.

11.2.2.3.1 Retry Mechanism for Failed Outgoing Notifications with Status Reporting

The UMS Adapter makes use of the existing infrastructure provided by UMS for retrying failed outgoing exceptions. Currently, the UMS Server supports the viewing of failed notifications from the Oracle Enterprise Manager, in addition to the resending of messages.

11.2.2.3.2 Outbound Send with TLS (SSL) to Communication with an SMTP Server

If you want to use Outbound, your use of the UMS Adapter Configuration Wizard has the same flow as it has with a standard UMS Adapter Configuration Wizard; however, there is are additional configuration tasks on the UMS Server side that you need to perform through the Enterprise Manager console.

You need to set the OutgoingMailServerTLS property on the email driver side to true (the default is false.) In addition to setting the SSL/TLS to true, you need to configure the Outgoing ports based on the SSL or TLS settings in the Enterprise Manager.This enables TLS encryption to communicate with the SMTP server.

11.2.2.3.3 Inbound Receive Notification in a Cluster (Through Polling or Through a Listener)

Using the standard Inbound UMS Adapter Configuration Wizard flow, using additional configuration, you can target a clustered environment for deployment. The UMS API supports an environment where the UMS Server and its clients are deployed in a cluster environment.The UMS Adapter also supports high availability in an active-active setup.

The configuration details for UMS Adapter to work properly in a clustered environment follows.

All UMS Adapter activations of the same composite application use the same unique ApplicationName configuration parameters. The UMS Adapter synthesizes the application name parameter from the Inbox address on which the specific endpoint is to listen.

This synthesis enables all activations of a specific composite in a cluster to share all configuration and artifacts such as Access Points and Message Filters

The ApplicationInstanceName configuration parameter is synthesized automatically through the UMS API implementation and the UMS Adapter depends on that synthesis.

Additionally, the UMS Adapter API implementation guarantees that in a cluster environment no two applications will receive the same message.

The UMS Adapter also supports active fail-over of an Inbound service that is active-passive in a clustered environment. You can enable this active fail-over for UMS Adapter support through a JCA service binding property (composite.xml)singleton, set to true.

Listening and Polling work the same way using a UMS adapter in a clustered environment as they do in a non-clustered environment.

11.2.2.3.4 UMS Adapter Properties and Mime Type Configuration

There are several properties associated with the UMS Adapter that you can use to provide additional configuration. Some of these are already set for you when you use the UMS Adapter Configuration Adapter Wizard. All applicable Internet Mail Headers and Mime headers can be configured through normalized message properties/headers.

The following table lists the Activation Spec properties applicable to the UMS Adapter.

Table 11-2 UMS Adapter Activation Spec Properties

Property Name	Description
`JavaCalloutImp`l	Name of the Java class that defines custom logic for a message filtering or any other check. This class is a concrete implementation of the ICustomCallout interface.
`ConsumeMode`	Specifies how the adapter will receive messages from UMS. Set to poller for polling mode Or set to listener for listener mode.
`To`	Address from which to receive incoming messages. One or more comma separated email address for the Email delivery type.
`Delivery Type`	Email support is provided for receiving and sending outgoing messages.
`PollingInterval`	Polling interval in seconds for poller consume mode.
`MessageFilters`	Specify one or more message filters. A single filter would comprise of a Java Pattern String to match the incoming message against, along with the field type and the action (Accept or reject) to be taken.

Table 11-3, "UMS Adapter Interaction Specification Properties" provides a list of interaction specification properties available.

Table 11-3 UMS Adapter Interaction Specification Properties

Property Name	Description
`Delivery Type`	Email support for only receive and sending outgoing messages.
`Subject`	Subject of Outgoing Message
`From`	Sender addresses of outgoing message
`To`	One or more recipient addresses
`Reply-to`	Reply-To address
`CC`	One or more cc addresses for email delivery.
`Bcc`	One or more Bcc addresses for email delivery
`SendEmailAsAttachment`	`True`, to send email as an attachment

The UMS Adapter exposes all applicable internet messages headers and Mime message headers and mime part headers (within a multipart construct.)

Mime headers are applicable only for the first body part of the message that is the UMS Adapter payload.

Mime headers for attachments are stored along with the attachment as normalized message properties that can be manipulated from within a BPEL process.

Table 11-4, "Message Headers" describes all the applicable headers defined by internet message format along with mapping and corresponding adapter header.

Table 11-4 Message Headers

Header Field Name	Minimum Occurrence	Maximum Occurrence	Mapped Adapter Header Field Name
`Return-path`	0	1	`jca.ums.return-path`
`Received`	0	unlimited	`jca.ums.received`
`Resent-Date`	0	unlimited	`jca.ums.received`
`Resent-From`	0	unlimited	`jca.ums.resent-from`
`Resent-Sender`	0	1	`jca.ums.resent-sender`
`Resent-To`	0	unlimited	j`ca.ums.resent-to`
`Resent-Cc`	0	unlimited	`jca.ums.resent-cc`
`Resent-Bcc`	0	unlimited	`jca.ums.resent-bcc`
`Resent-Message-ID`	0	unlimited	`jca.ums.resent-message-id`
`Date`	1	unlimited	j`ca.ums.date`
`From`	1	unlimited	`jca.ums.from`
`Sender`	0	1	`jca.ums.sender`
`Reply-to`	0	1	`jca.ums.reply-to`
`To`	0	1	`jca.ums.to`
Cc	0	1	`jca.ums.cc`
Bcc	0	1	j`ca.ums.bcc`
`Message-ID`	0	1	`jca.ums.message-id`
`In-Reply-To`	0	1	`jca.ums.in-reply-to`
`References`	0	1	`jca.ums.references`
`Subject`	0	1	`jca.ums.subject`
`Comments`	0	unlimited	`jca.ums.comments`
`Keywords`	0	unlimited	`jca.ums.keywords`

Table 11-5, "Mime-Part Message Headers" describes all applicable Mime message headers.

Note:

For the outbound UMS Adapter, you can use the property JCA.UMS.MSG.CONTENT-TYPE which can be used for specifying encoding. But if you do not set the value, the outbound UMS adapter uses server encoding for email by default.

When the SOA server is started in native encoding, for example, with iso8859-1, it cannot handle ccjk characters. The content will be garbled. As a workaround, you can set the jca property for the outbound UMS adapter as:

JCA.UMS.MSG.CONTENT-TYPE = 'text/plain; charset=utf-8'

Table 11-5 Mime-Part Message Headers

Header Field Name	Mapped Adapter Header Field Name	Notes
Content-Type	`jca.ums.part.content-type`
Content-Transfer-Encoding	`jca.ums.part.content- transfer-encoding`
Content-ID	jca.ums.part.content-id
Content-Description	`jca.ums.part.content- description`
Content-Disposition	`jca.ums.part.content- disposition`
Content-Language	j`ca.ums.msg.content-language`
Mime-Extension-field	`jca.ums.part.mime-extension-headers`	Any other mime header field hat begins with the string “Content-“. You can add more than one header as `Content-* : value CRLF Content*- : value` `CRLF - \r\n`

11.2.2.3.5 Proprietary Headers

The UMS Adapter enable you to add any proprietary headers. Table below shows the mechanism for doing so.

Table 11-6 Proprietary Headers

Header Name Notes

Header Name	Notes
j`ca.ums.msg.proprietary-headers`	More than one proprietary header can be added in the following format: Header Name : value CRLF Header Name : value (Header Name – should be similar to ums.adapter.xxxxx CRLF - \r\n)

jca.ums.msg.proprietary-headers

More than one proprietary header can be added in the following format:

Header Name : value CRLF Header Name : value

(Header Name – should be similar to ums.adapter.xxxxx CRLF - \r\n)

11.2.2.4 Email Attachments

The UMS Message XML can contain a list of Attachment elements that have an href attribute. The Attachment Manager stores other mime details associated with the attachment as MimeType, Content ID along with a stream object (which is the attachment content).

Currently, the UMS Adapter supports both inbound and outbound attachments.

See the following example for a sample XML Message with attachment element.

<Receive1_ReceiveEmail_InputVariable>
<part name="body" >
  <Email>
    <payload>This is a test mail.-Sagar</payload>
    <attachment>
      <Attachment href="0DF86C104BF511EoAF5977BAA7C7CFD9"/>
    </attachment>
  </Email>
  </part>
</Receive1_ReceiveEmail_InputVariable>

On the inbound side, the UMS Adapter sets all mime details before passing the attachment to the Attachment Manager.

11.2.2.5 Mail Attachment Handling

The UMS Adapter uses the Fabric Attachment Manager to store and retrieve attachments.

UMS Message schema defines Attachment element with a href attribute as shown below.

<copy>
   <from expression="ora:readBinaryFromFile('/home/testuser
       /oracle_sig_log0.gif')"/>
   <to variable="Invoke1_SendNotification_inputVariable" part="body"
       query="/ns2:message/ns2:attachment[1]"/>
</copy>

UMS Message XML can have list of attachment elements with a href attribute. Attachment manager stores other mime details associated with attachment as MimeType; Content ID and others. in addition to a stream object (attachment content). Sample XML Message with attachment element

On the inbound side, the adapter sets all mime details before passing attachment to the Attachment Manager, while on the outbound side, the adapter extracts any mime details received along with attachment object and uses them while creating the outgoing SDP message notification.

The Fabric Attachment Manager updates the href attribute with a key after storing the attachment to the database. This key can later be used to retrieve attachment content.

You can examine below the sample Normalized Message payload map with an XML structure having attachment element, which is passed from UMS Adapter to BPEL/Mediator service engine.

A sample XML Message with attachment element follows:

<Receive1_ReceiveEmail_InputVariable>
<part name="body" >
  <Email>
    <payload>This is a test mail</payload>
    <attachment href="0DF86C104BF511EoAF5977BAA7C7CFD9"/>
  </Email>
  </part>
</Receive1_ReceiveEmail_InputVariable>

11.2.2.5.1 Retrieving Mime Information Associated with an Attachment in BPEL

The snippet below shows how attachments can be retrieved in BPEL

First, obtain the Mime Information associated with the attachment.

<assign name"Assign1">
<copy>
   <from exporession="oraReadBnaryFromFileWithMimeHeaders('/home/testuser/oracle_  sig_logo.gif','one','image/gif', ", '7bit', 'oracle_logo_gif_file', 'en/ja')"/>
   <to variable="invoke="1_SendNotification_InputVariable" part="body"
    query='/ns3:message/ns3:attachment[1]"/>
</copy>
<bpelx:InsertAfter>
    <bpelx:from variable=Invoke1_SendNotification_InputVariable"
            part="body" query=/ns3:message:/ns3:attachment"/>
<bpelx:to variable=Invoke1_SendNotification_InputVariable" part="body"
            part="body" query=/ns3:message:/ns3:attachment"/>

</bpelx:insertAfter>
<copy>
    <from expression="ora.readBinaryFromFileWithMimeHeaders{'/home/testuser/
           install-mq-7.0.txt',",","," 'install_mq_file',''}"/>
     <to variable="Invoke1_SendNotification_InputVariable" part="body"
           query="/ns3:message/ns3:attachment[2]"/>
</copy>

11.2.2.5.2 Setting Mime Information for Multiple Attachments in BPEL

The following snippet shows how you can set Mime Information for multiple attachments in BPEL.

<assign name="Assign1">
<copy>
<from exporession="oraReadBnaryFromFileWithMimeHeaders('/home/testuser/oracle_sig_logo.gif','one','image/gif', ", '7bit', 'oracle_logo_gif_file', 'en/ja')"/>
<to variable="invoke="1_SendNotification_InputVariable" part="body"
    query='/ns3:message/ns3:attachment[1]"/>

</copy>
<bpelx:InsertAfter>
  <bpelx:from variable=Invoke1_SendNotification_InputVariable"
        part="body" query=/ns3:message:/ns3:attachment"/>
<bpelx:to variable=Invoke1_SendNotification_InputVariable" part="body"
      part="body" query=/ns3:message:/ns3:attachment"/>

</bpelx:insertAfter>
   <from exporession="oraReadBnaryFromFileWithMimeHeaders('/home/
    testuser/oracle_  sig_logo.gif','one','image/gif', ", '7bit',
   'oracle_logo_gif_file', 'en/ja')"/>
<copy>
   <to variable="invoke="1_SendNotification_InputVariable" part="body"
    query='/ns3:message/ns3:attachment[2]"/>

</copy>

11.2.2.6 UMS Adapter Inbound and Outbound Operations

Operations you configure via the UMS Adapter Configuration Wizard include the following Inbound and Outbound Operations:

Inbound Receive Notification
Outbound Send Notification
Outbound Send Notification (Message ID as Reply)

Note:

You can often use the BPE Invoke activity's property tab to select jca.properties to set a value from the Invoke activity. However, you cannot set jca.ums.message-id, as these message IDs are auto-generated.

1)In BPEL, Invoke activity we have properties tab.

11.2.2.6.1 Oracle UMS Adapter Inbound ReceiveNotification Concepts

In this scenario, the UMS Adapter registers an access point on the UMS Server to consume and process incoming notifications. This section provides an overview of different configurations and concepts associated with Oracle UMS Adapter Inbound Receive Notification.

An example of a Receive Email WSDL follows.

<wsdl:definitions name="ReceiveEmail"
                  targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/ums/
                  UMSAdapter_In_SinglePart_Xlation/
                  SOAComposite_email_poller_bpel/ReceiveEmail"
                  xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/ums/
                  UMSAdapter_In_SinglePart_Xlation/
                  SOAComposite_email_poller_bpel/ReceiveEmail"
                  xmlns:pc="http://xmlns.oracle.com/pcbpel/"
                  xmlns:imp1="http://platform.integration.oracle/blocks/adapter/
                  fw/metadata/UMSAdapter"
                  xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05
                  /partner-link/">
    <plt:partnerLinkType name="ReceiveEmail_plt">
        <plt:role name="ReceiveEmail_role">
            <plt:portType name="tns:ReceiveEmail_ptt"/>
        </plt:role>
 
    </plt:partnerLinkType>
    <wsdl:types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://platform.integration.oracle/blocks/adapter
            /fw/metadata/UMSAdapter"
                    schemaLocation="xsd/UMS.xsd"/>
        </schema>
    </wsdl:types>
    <wsdl:message name="ReceiveEmail_msg">
        <wsdl:part name="body" element="imp1:Email"/>
    </wsdl:message>
    <wsdl:portType name="ReceiveEmail_ptt">
        <wsdl:operation name="ReceiveEmail">
            <wsdl:input message="tns:ReceiveEmail_msg"/>
        </wsdl:operation>
    </wsdl:portType>
</wsdl:definitions>

11.2.2.6.2 Oracle UMS Outbound Send Notification Concepts

In this scenario, the UMS Adapter processes outgoing send notifications. This section provides an overview of different configurations and concepts associated with the Oracle UMS Adapter Outbound send notification, of which there are two types, the normal send and the send with Receive Message id as reply request.

11.2.2.6.3 Receive Message id as reply request

A type of outbound synchronous request is the Receive Message id as reply request. It is a variation of the one way invoke, but with Receive Message id as reply request, a unique message ID is replied back from the UMS Server. You can use this type of request if you want to get this message id to check message delivery status information.

If you choose to use this type of request, you select the Receive Message Id as a reply request checkbox when selecting an Operation.

11.2.3 Configuring the Oracle UMS Adapter

You configure the User Message Service using the Enterprise Manager Console and the Email Adapter Configuration Wizard in JDeveloper to configure the UMS Adapter.

To configure the User Messaging service drivers, you perform the task from the Enterprise Manager Console. Specifically, to use the Email messaging channel, you need to configure the Email driver properties. The following section provides information on configuring the Email driver for the UMS Adapter.

11.2.3.1 Configuring the Email Driver for the UMS Adapter - Outbound Connectivity

In this procedure, you provide the necessary input to setup the UMS Email Driver for outbound connectivity with the email server.

To configure the Email Driver via the Enterprise Manager, click on User Messaging Email Driver -> Email Driver Properties.
Enter the name of the SMTP server in the OutgoingMailServer location.
Enter the port number of the SMTP server in the OutgoingMailServerPort. Typically, this is 25.
Enter the type of security you want to use with the SMTP server. Possible values are None, TLS and SSL. Default value is None.
Provide the username used for SMTP authentication in OutgoingDefaultFromAddr. This is required only if SMTP authentication is supported by the SMTP server. (An alternative field is OutgoingUsername)
Provide the password used for SMTP authentication for OutgoingPassword. This is required if SMTP authentication is supported by the SMTP server.

Figure 11-2 The Enterprise Manager Console Showing the Email Driver Properties Screen

Description of "Figure 11-2 The Enterprise Manager Console Showing the Email Driver Properties Screen"

11.2.3.2 Configuring the Email Driver for UMS Adapter - Inbound Connectivity

The following is the minimum configuration which you need to use to set up the UMS Email Driver for inbound scenarios.

Enter the MailAccessProtocol. This is the E-mail receiving protocol. The possible values are IMAP and POP3. This value is required only if email receiving is supported on the driver instance.
Enter the value for the ReceiveFolder. The name of the folder the driver is polling messages from. The default value is INBOX.
Enter the value of the IncomingMailServer. This is the host name of the incoming mail server. Required only if e-mail receiving is supported on the driver instance.
Enter the value of the IncomingMailServerPort. This is the port number of IMAP4 that is, 143 or 993) or POP3 (that is, 110 or 995) server.
Enter the value of the IncomingMailServerSSL. This indicates if you want to enable SSL when connecting to the IMAP4 or POP3 server. The default value is disabled.
Enter the email addresses for the IncomingMailIDs. These are the email addresses corresponding to the user names.This is required only if email receiving is supported on the driver instance.
Enter the list of user name for the IncomingUserIDs. This is 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. Required only if email receiving is supported on the driver instance.
Enter the IncomingUserPasswords. This is the list of passwords corresponding to the user names. This is required only if the driver instance supports email receiving.

For more details on configuration, see Oracle® Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

11.2.3.3 Designing the Adapter Service and the BPEL Process for Inbound Connectivity

Use the UMS Adapter Configuration Wizard within JDeveloper to design the inbound UMS Adapter reference.

Drag and drop UMS Adapter from the Component Palette to the External References swim lane.The Adapter Configuration Wizard Welcome page is displayed.

Figure 11-3 UMS Adapter Configuration Wizard, Welcome Screen

Description of "Figure 11-3 UMS Adapter Configuration Wizard, Welcome Screen"
Click Next. The Service Name page is displayed
Enter the Service Name, for example ReceiveEmail, in the Service Name text box on the Service Name Screen.

Figure 11-4 The UMS Adapter Configuration Wizard Service Name Screen

Description of "Figure 11-4 The UMS Adapter Configuration Wizard Service Name Screen"
Figure 11-5 The UMS Adapter Configuration Wizard Connection Screen

Description of "Figure 11-5 The UMS Adapter Configuration Wizard Connection Screen"
On the UMS Adapter Connection page, enter the Connection JNDI Name. Here, eis/ums/UMSAdapterInbound is specified as the JNDI name, which is the default JNDI name for Inbound Connections.On the Operation Type screen of the UMS Adapter Configuration wizard, select the operation to perform. Based on your selection, different adapter configuration wizard pages appear and prompt you for configuration information. For Inbound connectivity, on the Operation screen, select Inbound Receive Notification as the operation type and click Next.

Figure 11-6 The UMS Adapter Configuration Wizard Operation Screen, Inbound Receive Operation Type Chosen

Description of "Figure 11-6 The UMS Adapter Configuration Wizard Operation Screen, Inbound Receive Operation Type Chosen"
The Notification Details page of the Adapter Configuration Wizard enables you to specify the mode, Polling or Listener, in which to receive incoming notifications from the UMS Server.

Figure 11-7 UMS Adapter Configuration Wizard Notification Details Screen

Description of "Figure 11-7 UMS Adapter Configuration Wizard Notification Details Screen"
Selecting the Polling mode enables you to specify inbound polling parameters:
- Polling Frequency. The frequency with which to poll the UMS for new notifications to retrieve.
- Frequency unit. Specify seconds, minutes, hours, days or weeks as the unit for frequency.
- Inbound Thread Count. Specify the number of polling threads.
The UMS Adapter receives messages until the messages are available in the Inbox. When there are no more messages, and only then, the UMS Adapter sleeps for the polling interval you specify on this screen. This sleeping activity avoids mounting large number of messages in the Inbox, within high-incoming message volume scenarios. Each polling thread retrieves one message at a time, processes it and then publishes it.

Figure 11-8 Notification Details Screen when Polling is Selected for an Inbound Receive Operation

Description of "Figure 11-8 Notification Details Screen when Polling is Selected for an Inbound Receive Operation"
Selecting the Listening Mode enables you to specify Message Listener Threads. This property controls the number of listener worker threads on the UMS Server side. The default value is 1. Specifying this property means the UMS Server will provide multi-threaded asynchronous receiving of incoming notifications.

Figure 11-9 UMS Adapter Configuration Wizard Notification Details with Listener Mode Selected

Description of "Figure 11-9 UMS Adapter Configuration Wizard Notification Details with Listener Mode Selected"
The second page of the Notification Details Page of the UMS Adapter configuration wizard enables you select the type of notification to receive with the Notification Endpoint Configuration. You can specify more than one comma-separated email mail box address from which you want to receive email notifications.

Figure 11-10 The UMS Adapter Configuration Wizard Inbound Notification Details Screen, Second Page

Description of "Figure 11-10 The UMS Adapter Configuration Wizard Inbound Notification Details Screen, Second Page"
Click Next to continue, or Finish to complete using the UMS Adapter Configuration Wizard without configuring message filters against incoming messages.
A Message Filter contains a matching criterion and an action. You can register a series of message filters. They are applied in order against an incoming (received) message; if the specified criterion matches the message, the action is taken.

For example, you can implement any required blacklists, by rejecting all messages from a given sender address.

You can specify three different types of filters on this screen. (For more information on Java Patterns, or Regular Expressions, see the reference at http://download.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html and the tutorial at http://download.oracle.com/javase/tutorial/essential/regex)
1. Blacklist Filter-Blacklist filters match against an incoming message's sender address, and reject the message if the sender address matches the given Java pattern. (That is, a Java regular expression).
2. Whitelist Filter-Whitelist filters match against an incoming message's sender address and accepts the message if the sender address matches the given Java pattern.
3. Message Filter-A message filter matches against any of the fields you indicate with a given pattern and accepts or rejects the messages depending upon the action you specify. These fields include: CONTENT, HEADER, METADATA, RECIPIENT, REPLYTO, SENDER, SUBJECT
There are only two types of Actions that apply to the Message Filters, either ACCEPT or REJECT the message. Message Filters are applied in the same order in which you define them on the Message Filter page.

Click Finish to complete the configuration through the Wizard, or click Next to proceed to the Java Callout Screen to specify a Java class through which you can apply additional filtering.

Figure 11-11 UMS Adapter Message Filters Screen

Description of "Figure 11-11 UMS Adapter Message Filters Screen "
On the Java Callout screen, specify the name of the Java class you want the UMS Adapter to invoke and which will run custom logic you provide.

Figure 11-12 UMS Adapter Configuration Wizard Custom Java Callout Screen

Description of "Figure 11-12 UMS Adapter Configuration Wizard Custom Java Callout Screen"
If you want to provide a custom Java callout, select the checkbox and provide a classname in the text box. See the description in the custom Java Callout class section in this chapter.
Click Finish on the page below to complete configuring the UMS Adapter service. When you finish configuring the Oracle UMS Adapter, a JCA file is generated for the inbound service. The file is named after the service name you specified on the Service Name page of the Adapter Configuration Wizard. You can rerun the Wizard later to change your operation definitions.

11.2.3.4 Designing the Adapter Service and the BPEL Process for Outbound Connectivity

Use the UMS Adapter Configuration Wizard within JDeveloper to design the outbound UMS Adapter reference.

Drag and drop Database Adapter from the Component Palette to the External References swim lane.The Adapter Configuration Wizard Welcome page is displayed.

Figure 11-13 UMS Adapter Configuration Wizard Welcome Screen

Description of "Figure 11-13 UMS Adapter Configuration Wizard Welcome Screen"
The UMS Adapter Service Name screen is displayed. Enter SendMail for the Outbound Service Name, for example.
Figure 11-14 UMS Adapter Configuration Wizard Service Name Screen, Outbound Send Mail Operation

Description of "Figure 11-14 UMS Adapter Configuration Wizard Service Name Screen, Outbound Send Mail Operation"
The UMS Adapter Connection Name screen is displayed,.with the Connection JNDI Connection Name

Figure 11-15 UMS Adapter Connection JNDI Name

Description of "Figure 11-15 UMS Adapter Connection JNDI Name"
On the Operation screen, select Outbound as the Operations type. The Operation Name defaults to SendNotification.

Figure 11-16 UMS Adapter Configuration Wizard Operation Screen with Outbound Send Operation Selected

Description of "Figure 11-16 UMS Adapter Configuration Wizard Operation Screen with Outbound Send Operation Selected"
The Outbound Notification Details screen appears. The Email button is selected. Enter the Endpoint Configuration detail items, or browse to find them. You also can specify a failover address for any primary address you provide. For example, scott.tiger@sport.com:failover-id@example.com. This failover addressing applies to To, CC and Bcc addresses.

You can click on the browse button and browse the identity service using the Identity Look-up Dialog to search and fill address attributes, as needed.Click Next to proceed or Finish to complete using the Wizard.
Define the message for the UMS Send operation using the Messages Screen. If you choose Message is Opaque(Base64Binary) or Message is String Type, you do not have to specify a URL for the Schema and a Schema Element. If you choose a URL for the Schema, you must specify a Schema Element.

Figure 11-17 UMS Adapter Configuration Wizard Messages Screen

Description of "Figure 11-17 UMS Adapter Configuration Wizard Messages Screen"
Click Finish to complete using the UMS Adapter Configuration Wizard.
The Finish Screen appears. You have completed using the UMS Adapter Configuration Wizard. Click Finish to complete creating the xsd and WSDL at the locations indicated on the screen.

11.3 Sample

You can obtain the sample from the Oracle SOA Samples web site. To use the sample, you need to create a composite, deploy it and configure a mail server to use with an email client.

11.3.1 Creating the Composite

You must create a JDeveloper Application to contain the SOA Composite for the Umail Adapter. To create the appropriate application and a project:

In the Application Navigator of JDeveloper, click New Application. Select Application Template as SOA Application.
Enter SOA-Email-AutoReply in the Application Name field, and click Next.
Enter SOA-Email-AutoReply in the Project Name field.
Select Composite With BPEL in the Composite Template box, as shown in the figure below, and click Finish. The Create BPEL Process - BPEL Process page is displayed.
Enter BPEL_Email_AutoReply in the Name field, select Define Service Later from the Template box.
Click OK. The SOA-Email-AutoReply application and the project appear in the design area.

11.3.2 Creating the Inbound Oracle UMS Adapter Service

The next group of tasks enables you to create an inbound Oracle UMS Adapter Service to read incoming emails from a given email inbox address:

Drag and drop the Oracle UMS Adapter from the Component Palette to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed
Enter ReceiveEmail in the Service Name field
Click Next. The Adapter Connection page is displayed
Click Next. The Adapter Operation page is displayed.
Select Operation type as Inbound Receive Notification as shown below and click Next. The Inbound Operation Details page is displayed.
Select the Operation Mode Polling, the default, and click Next. The Adapter Inbound Notification Details page is displayed.
Enter test2@blr2240893.idc.oracle.com into Email Endpoint Configuration text box, the email address from which to receive incoming messages, as shown below. Click Next. The Adapter Messages page is displayed.
On the Message Page, Select Message is String type checkbox, as shown below. Click Next. The Message Filters page is displayed.
Click Next on the Message Filters page. The Custom Java Callout page is displayed.
Click Next on the Java Callout page. The Adapter Wizard Finish page is displayed.
Click Finish on the Finish page.
The inbound Oracle UMS Adapter is now configured and the composite.xml file appears.

11.3.3 Creating the Outbound UMS Adapter service

Perform the following steps to create an outbound Oracle UMS Adapter service to send out an email:

Drag and drop the UMS Adapter from the Component Palette to the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed. Enter SendReplyEmail in the Service Name field.
Click Next. The Connection Page is displayed.
Click Next. The Operation Page is displayed. Select Outbound Send Notification as the Operation type.
Click Next. The Outbound Notification Details page is displayed. Enter dummy in the To field.
Click Next. The Message page is displayed. Select the checkbox which says Message is String type.

11.3.4 Wiring Services and Activities

You have to assemble or wire the three components that you have created: the Inbound adapter service, the BPEL process, and the outbound adapter reference. Perform the following steps to wire the components:

Drag the small triangle in the ReceiveEmail in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the SendEmailReply External References area. The JDeveloper composite.xml appears.
Click File, Save All.

11.3.5 Add a Receive Activity

The next series of steps enables you to add a Receive Activity.

Double-click BPEL_Email_AutoReply. The BPEL_Email_AutoReply.bpel page is displayed.
Drag and drop a Receive activity from the JDeveloper Component Palette to the Design area.
Double-click the Receive activity. The Receive dialog is displayed.
Enter ReceiveEmail in the Name field.
Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
Select ReceiveEmail, and click OK.
Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
Select the default variable name and click OK. The Variable field is populated with the default variable name.
Check Create Instance, and click OK. The JDeveloper BPEL_Email_AutoReply.bpel page appears, as shown below

11.3.6 Obtaining Email Header Information

Perform the following steps to extract the email header information.Using the Receive construct, and the properties tab, one can fetch any header properties of the incoming mail.This value can be assigned to the already created variables in the Assign activity of BPEL, and used later.There is also the ability to set an header property on the Outbound mail.This can be accomplished also via the Properties tab of the Invoke activity.Thus, Mail can be received (using the Inbound UMS Adapter) and also sent (using the Outbound UMS Adapter) and orchestration accomplished via BPEL or Mediator.Using BPEL/Mediator API's the various headers and payload can be manipulated.

Create temporary variables to hold header information. To add new variables, click the icon, Variables… The Variables Dialog box is displayed. Add a new variable from of simple type string as below.
Following the same step as above, create one more variable, subject.
Double-click the Receive activity. The Receive dialog is displayed. Click the Properties tab.
Assign the jca.ums.from property value to the from variable by selecting it through the Browse Variables Dialog, as shown below.

11.3.7 UMS Adapter Configuration Changes for IBM WebSphere Server

For Poller Mode and Listener Mode to work on the Inbound side of the UMS Adapter when IBM WebSphere Application Server is installed, you need to create a few settings on the IBM WebSphere Application Server Console.

Configure LRC/Last Participant support for the IBM WebSphere Application Server.
Ensure that JAAS subject propagates from the scheduling thread to the target thread.
Set Heuristic completion direction to COMMIT.
Save your changes to the master configuration.
Restart the Server.

On the composite level, ensure that async persists, as in the following code snippet within the composite.xml.

<component name="BPELProcess1" version="1.1"> 
  <implementation.bpel src="BPELProcess1.bpel"/> 
    <property name="bpel.config.transaction" type="xs:string" 
many="false">requiresNew</property> 
    <property name="bpel.config.oneWayDeliveryPolicy" type="xs:string" 
              many="false">async.persist</property>