Ums adapter

7/23/2019 Ums adapter

1/47

8/12 Oacle Reie

ie..oacle.com/eie/pinable-ie.do

UMS Adapter : Functional Specification

Document: UMSAdapterFunctionalSpec.odt Show : Open/Fixed Wednesday, March 7, 2012 10:23:56 PM PST

1 - 36

37 Functional Specification for Oracle UMS Adapter,

SOA 12C

Project ID: UMS Adapter

Version: 18 Ma 2009

Status: Review Draft

Author: Sagar Shirguppi

Project Manager: [email protected] Control

Document Change History

Date Author Version Change Description

23-May-09 Sagar Shirguppi 0.2 Initial Draft

03-Jun-09 Sagar Shirguppi 0.4 Added UMS related details.

04-Jun-09 Sagar Shirguppi 0.6 User Interface details to design the Adapter service.

30-Jun-09 Sagar Shirguppi 0.7 Incorporated Sr imant's feedback

07/13/09 Sagar Shirguppi 0.8 Incorporated Kalpaks feedback

10/11/10 Sagar Shirguppi 0.9 David Li Feedback

Contributors

Name Organization Title

Kalpak Kothari UMS Development Manager

Patrick Vinograd UMS PMTS

Srimant Misra ST Development Manager

Reviewers

Name Role Title Date Reviewed

Review Documents Properties Members Options search


2/47

8/12 Oacle Reie


Vikas Anand PM Principal Product Manager

Kalpak Kothari Dev Manager

Srimant Misra Dev Manager

David Li PMTS

Document References

Document Title Type of Reference Document Location

Bugs: 8213748 Bugs here

Table of Contents

Document Control 1

Document Change His tory 1

Contributors 1

Reviewers 1

Document References 2

1Project Overview 3

1.1Problem/Need Statement 3

1.2High Level Requirements 3

1.3Assumptions and Constraints 4

1.4Features Scoped Out or Deferred to a Future Release. 4

2Concepts & Terminology 4

3Requirements 4

3.1Functionality 5

3.1.1Inbound Receive Notification (Email, SMS, IM) - Polling or through a Listener. 5

. 3.1.1.1Email Driver Configuration on UMS side. 6

. 3.1.1.2Design Adapter Service and the BPEL Process. 6

3.1.1.3Message Mapping 173.1.1.4Connection Factory Properties 19

3.1.1.5Activation Specification Properties 19

3.1.1.6Endpoint Properties 20

3.1.1.7Normalized Message Properties 20

3.1.1.8Receive Mode Polling Vs Listener 23

3.1.1.9Inbound Polling Semantics 23

3.1.1.10Inbound Listener Semantics 24

3.1.1.11Transaction Semantics 24

3.1.1.12Inbound Error Handling 26

3.1.1.13Attachment Handling 26

3.1.2Inbound Receive Notification in a Cluster (Polling or through a Listener) 27

3.1.3Inbound In with SSL to communicate with IMAP/POP3 server 27

3.1.4Outbound Send Notification (Email, SMS, IM, Voice) 28

. 3.1.4.1Email Driver Configuration on UMS side. 28

. 3.1.4.2Design the Adapter Service and BPEL Process. 28

3.1.4.3Message Mapping 37

3.1.4.4Interaction Specification Properties 39

3.1.4.5Normalized Message Properties Outbound 40

3.1.4.6Endpoint Properties 40

3.1.4.7Connection Factory Properties 40

3.1.4.8Transaction Semantics on the Outbound 40

3.1.4.9Outbound Error Handling 41

3.1.4.10Retry Mechanism for Failed Outgoing Notifications with status reporting 41

3.1.5Outbound Send with TLS (SSL) to communicate with the SMTP server 41


3/47

8/12 Oacle Reie


4Client Interfaces 42

4.1Task Analysis, Roles, and Use Cases 42

4.1.1HP 42

4.1.2Rabobank 43

4.1.3B2B Requirements 45

5Other Design Considerations 46

5.1Scalability/Availability 46

5.2Deployment and Life Cycle 46

5.3API & Libraries 46

5.4Extensibility 46

1 Project OverviewThis document captures the requirements/functionality for a JCA compliant UMS (User Messaging Service) Adapter.

Adapter will wrap User Messaging Service allowing business workflow to subscribe to different delivery channels as

Email, SMS and IM. Adapter will act as a proxy between SOA Suite and the external world and will be capable of acting

as a Provider or as a Consumer.

1.1 Problem/Need StatementIn the enterprise world, Email is the main communication option between Business to Business and it is very

important to have this along with other messaging channels like SMS, IM and Voice integrated into the SOA suite.

UMS (User Messaging Service) is a Fusion Middleware component, which provides services to send/receive

notifications/alerts through various messaging channels as Email, SMS, IM, and Voice.

Currently under SOA suite we have Human Workflow and notification agents, which use UMS to send/receive

notifications. But apparently these use cases are more human centric. There is a need for a JCA Adapter that can be

used to realize some of the use cases, which are more data centric. For example kicking a workflow with a new mail

in the inbox, along with filtering, transforming or formatting based on certain business requirements.

Again, main advantages with JCA based adapter are,

1. Being part of the adapter stack, UMS Adapter will by default be available to the Mediator service engine

too. Currently there is no way under Mediator to consume or reference messaging channels such as Email,

SMS etc.

2. With standard life cycle and work management contracts, adapter will be able to provide a controlled run-

time environment along with monitoring capabilities.

3. Standard Error handling capabilities like rejection handling and fault policies for exception conditions.

4. With well defined transaction contract for JCA adapters, adapter would be able to participate in the

distributed transactions.

1.2 High Level Requirements1. The requirement is to have a generic, comprehensive JCA based UMS Adapter.

2. The Adapter should act as a Service Consumer as well as Provider.

3. The Adapter should provide support for different messaging channels such Email, Voice, IM, SMS etc.

Should be supporting popular protocols s uch as SMTP, IMAP, POP, SMPP and XMPP.

4. The Adapter Should support SSL for Email channel.

5. The Adapter should implement JCA Interface and thus be able to seamlessly integrate with SOA

Applications.

6. The Adapter should be integrated with Translator Infrastructure (NXSD).

7. The Adapter should be able to send/receive notifications/alerts with message bodies of multiple parts,

format of which might be described by different MIME types.

8. The Adapter should be able to provide status information from messaging gateways along with retrying

capabilities for failed messages.

9. The Adapter should be able to participate in the global transactions with various participants, for inbound

and outbound scenarios.


4/47

8/12 Oacle Reie


1.3 Assumptions and Constraints1. UMS POJO Client API. We have it starting from PS2.

. XA Transaction support from UMS (This has been added as a requirement for 12c. A360 requirement

557827: Ability for UMS to participate in an XA transaction)

. Parameterized synchronous receive call in case of synchronous receiving of messages from UMS. Note -

A360 requirement 557688: Throttling to control the number of inbound messages to be delivered.

1.4 Features Scoped Out or Deferred to a Future Release.1. Multiple Payload Support - Delivery Channel Specific Payload in single message for recipients with different

delivery types, available under UMS.

2. Translation support for more than one body parts, in case of a Multipart message.

3. Support for specifying the body part index to carry out translation on that particular body part, in case of a

Multipart message.

2 Concepts & Terminology1. JCA Java Connector Architecture

2. SMTP Simple Mail Transfer Protocol is an Internet Standard for electronic mail (email) transmis sion across

Internet Protocol (IP) networks.

3. IMAP Internet Message Access Protocol is one of the most prevalent Internet Standard protocol for e-mail

retrieval from a remote mail server.

4. POP Post Office Protocol is too a well known Internet Standard protocol used by email clients to access

email from mail server.

5. SMPP Short Message Peer-To-Peer protocol is a telecommunication protocol for exchanging SMS messages

between peer entities such as Short Message Service Centers and/or External Short Messaging Entities.

6. XMPP Extensible Messaging and Presence Protocol is an open standard communication protocol for

message-oriented middleware based on XML.

7. SSL Secure Socket Layer

8. S/MIME Secure/Multipurpose Internet Mail Extensions is a standard for public key encryption and signing

of MIME data.

3 Requirements1. Support for Inbound Communication

1. JCA 1-way Inbound Interaction Asynchronous publishing of message notifications from UMS(Email, SMS

and IM Channel)

2. Adapter should be able to asynchronously receive messages/notifications from UMS. In this case the

adapter will register a POJO listener with UMS for callbacks. User should be able to specify number of listener

threads.

3. Adapter should also be able to poll UMS for any messages/notifications with a predefined polling interval to

retrieve available messages. For example poll for any new messages on a certain email inbox and fetch them

as and when available. User should be able to specify the polling interval and number of polling threads.

4. A single adapter endpoint should be able to receive messages from one or more inboxes.

5. With synchronous receive (polling mode), adapter should be able to receive and acknowledge received

messages, thus should make use of reliable messaging support from UMS to ensure no message loss.

6. Adapter should be able to receive messages with subject, body and one or more attachments (multipart

messages with different mime types) if available.

7. If the user chooses Email as the message delivery channel, the adapter should be able to retrieve emails

from IMAP/POP3 servers supporting SSL. (This support is already available with UMS)

8. Adapter should make use of Message Filtering Support given by UMS for selective receive of incoming

messages. This also involves user preference based messagingsupport given by UMS, where user can pass

business terms along with facts or values for the same as message metadata. The same can then be used

afterwards for the message filtering.

9. Adapter should give a Java Callout Option to the user, to execute certain custom logic before processing

the message (this would be after receiving the message from UMS).

2. Support for Outbound Communication

1. JCA 2-way outbound interaction with message notification as request and response as a unique message id


5/47

8/12 Oacle Reie


received from UMS server after accepting the notification.

2. User optionally should be able to opt for JCA 1-way outbound interaction, when he is not interested in

getting the message id from UMS.

3. Adapter should be able to send messages/notifications to the external world through Email, IM, SMS and

Voice messaging channel.

4. Adapter should be able to send notifications/alerts with subject, body and one or more attachments

(multipart messages with different mime types) if available.

5. Adapter should give an option to send email as an attachment.

6. SSL support while sending emails. (This support is already available with UMS)

7. Adapter should be able to send notification to multiple recipients.

8. User should be able to add proprietary mail headers to an outgoing message.

9. User should be able to set message metadata (user preference based messaging support from UMS) for

outgoing messages.

3. Fault Handling/Error Hospital

1. Support for fault-policy/fault-bindings for inbound and outbound.

i. Message Rejection

1. For any errors in translation the adapter should use Rejection Mechanism.

2. Rejection Mechanism also should be used for bad messages; that is, incoming messages

which fail on Java Callout check. This will work as an error hospital for bad messages.

2. Outbound Retries

i. Support for retry logic for outbound interactions through fault-policies.

ii. Retry logic for outbound interactions through JCA retry mechanism.

3. Status reporting (get status information from the messaging gateways) and automatic retries, depending

on the status received.

4. Transaction Support

1. Adapter should be capable of taking part in the distributed transactions for both inbound and outbound

scenarios.

5. Translation Support

1. Adapter should be able to translate between XML and native forms of messages according the predefined

message s chema.

2. Translation support for only one body part of the message. For a Multipart/alternative message, it always

will be the first body part with inline disposition.

3.1 Functionality

3.1.1 Inbound Receive Notification (Email, SMS, IM) - Polling or through a Listener.

In this scenario, as part of inbound activation, UMS Adapter will register an access point on the UMS Server to

consume incoming notifications. Adapter will either poll or register a listener with UMS to get notifications. With a

notification received, adapter will pick up the message and will publish it to Adapter Binding Component (first inline

body part translated as per the schema defined), which will kick-s tart the composite scenario. This is a one-way

operation.

Designing this service involves two main parts

1 Configuration on the UMS Server side to setup access points for receiving notifications.

2 Designing the Adapter Service and BPEL process.

3.1.1.1 Email Driver Configuration on UMS side.

On the UMS side, administrator needs to configure the Email driver from Enterprise Manager (EM) Fusion Middleware

Console, as below.


6/47

8/12 Oacle Reie


Following are some of the custom email driver properties user needs to configure under Driver-Specific Configuration

for UMS.

1 IncomingMailServer - Host Name of incoming mail server - stbeehive.oracle.com

2 IncomingMailServerPort - Port Number of IMAP4

3 IncomingMailIDs - The e-mail addresses corresponding to the user names. - [email protected]

4 IncomingUserIDs - user names of the mail accounts the driver instance is polling from UserName

5 IncomingUserPasswords - passwords corresponding to the user names.

6 ReceiveFolder - The name of the folder drive should poll messages for INBOX Email Driver Configuration on

UMS side.

For details on configuring SMPP, XMPP driver, please check UMS Admin Guide.

3.1.1.2 Design Adapter Service and the BPEL Process.

38 User would be using UMS Adapter Configuration wizard under JDeveloper to design the inbound adapter service

as shown below.

1. User enters ReceiveNotification in the Service Name Field as shown below.


7/47

8/12 Oacle Reie


2. User enters the JNDI name for the UMS Adapter Connection.

3. Selects Inbound Receive Notificationas the operation type.

a. 39 Depending on how he wants receive messages from UMS, user selects either Polling Mode or

Listener Mode


8/47

8/12 Oacle Reie


b. Operation mode details like polling frequency would be displayed only when user selects inbound

operation.

c. Polling frequency units would be seconds, minutes, hours, days and weeks. Units other than seconds

will be converted into seconds by the UI wizard while setting value for the polling frequency activation

spec property value.

4. Configures the end point attributes after selecting the type of Notification as Email, SMS, Or IM. 40 For

instance, selecting Email, users enters other attribute details as one or more incoming mail addresses.

In case of SMS, recipient address would be a mobile number. User also can specify a mobile number

range, e.g. 16501230000, 16501234999 means all numbers from 16501230000 to 16501234999 (inclusive).

In case of IM, it would be instant messaging ids e.g. jabber| [email protected].


9/47

8/12 Oacle Reie


5. On the Messages Page, user enters message related details.

a. If user needs the message payload (first body part of a multipart message with inline disposition)

to be translated as per certain schema, user enters the schema details, which defines the incoming

notification body content, as shown below. He can use the Native Format builder to define the

Schema for native formats. Note that the message schema specified here just defines the body

content.

b. For simple text type payload, user can check the option Message is String type.

c. If message payload is opaque, user can opt for Message is Opaque (Base64Binary) option.

d. For above two options, user need not specify any schema details.


10/47

8/12 Oacle Reie


e. Unlike other adapters, UMS Adapter will use a predefined Message Schema to represent the

message. Check out the predefined message schema for UMS Adapter under Appendix section.

f. The schema defined by user according to his translation requirement (on the message page above,

for the message body content) would be imported into the predefined message schema used by the

UMS Adapter. Check out the schema snippet shown below where the user defined schema

singleString.xsd is imported and it refers to the element singleString, which is defined under

singleString.xsd.

Content Type defined under UMS.xsd

Singletring.xsd which defines native schema


11/47

8/12 Oacle Reie


g. If user opts for Message is opaque (Base64Binary) option, wizard will directly add an element of

type base64Binary (payload definition) to the static schema as shown below.Message is Opaque (Base4Binary)

h. If user opts for Message is String Type option, wizard will add an element of type xsd: string

(payload definition) to the static schema as shown below.

Message is String Type

6. 41 - 43 On the Filters page, user specifies filter expressions to filter out incoming messages. A Message

Filter contains a matching criterion and an action. User can register a series of message filters. They will be

applied in order against an incoming (received) message; if the criterion matches the message, the action is

taken. For example, user can use Message Filters to implement necessary blacklists, by rejecting all

messages from a given sender address. User can specify three different types of filters.

a. Blacklist Filter blacklist filters match against an incoming message's sender address, and rejects

the message if the sender address matches the given pattern. A pattern is a Java Pattern. (A regular

expression)


12/47

8/12 Oacle Reie


b. Whitelist Filter Whitelist filters match against an incoming message's sender address and

accepts the message if the sender address matches the given pattern (Java Pattern).

c. Message Filter A message filters matches against any of the given fields below with a given

pattern and accepts or rejects the messages depending upon the action specified by the user.

i. CONTENT

ii. HEADER

iii. 44 METADATA

iv. RECIPIENT

v. REPLYTO

vi. SENDER

vii. SUBJECT

d. There are only two types of Actions, ACCEPT or REJECT the message.

e. Message Filters are applied in the same order in which user defines them on the Message Filter

page, as shown below.

[Note: If field value is HEADER or METADATA, field name will determine which header or meta data entry

to match against. In case of HEADER, field name will be any of the header field name defined by RFC 5322

Internet Message Format. Please check Table I Message Headersfor exact header names. UI screen should

by default show all of these names in the Field Name combo box, if user selects field type as HEADER.

Now regarding METADATA, UMS allows sending facts (values) for various business terms as messagemetadata (Please check Chapter 64, "User Messaging Preferences." ). This metadata can be used to filter

out messages through message filters. Please check Table V - Message Metadatafor exact metadata names.

UI screen should by default show all of these names in the Field Name combo box, if user selects field type

as METADATA.

For example, METADATA field name is Customer Name value specified is ACME. This can be set while

sending out the message through UMS API as shown below.

message.setMetaData(Message.NAMESPACE_NOTIFICATION_PREFERENCES,Customer

Name,ACME);

f. Adapter UI wizard will try to compile the regular expression specified by user and will report any

errors immediately. This will provide early validation and help avoid later errors.


13/47

8/12 Oacle Reie


g. Message filters defined by user on Message Filter page above will be added as an activation

specification property, as explained below. While endpoint activation, adapter run-time will apply

these filters using UMS API.

Message Filters One or more message filters (message filters, blacklist or Whitelist, in the

same order in which user defined them) separate by a semicolon. Each message filter type,

FieldType, FieldName, Pattern and Action; these fields will be separated by a comma. In the

example below first message filter is to match the sub-string Purchase Order anywhere in the

SUBJECT field and accept the message if it finds one. Second message fi lter will match the 'From'

Email Header field to check if s tarting with 'foo'. If the header value starts with foo, action will

be REJECT.

7. On the Java Call 45 out page, user will be able to specify a Custom Java Class which will take the incoming

SDP message and process it to decide on whether to process the message or reject. One simple example

would be matching the sender address with one in the LDAP or some staging area recorded earlier. Interface

would look like as shown below.

I ICC {

(M );

Message being the Message class from UMS SDP Java API, well defined Java API given by UMS. Boolean value

returned would decide on whether to accept and process the message or reject the message.

User has to bundle this and other required custom classes as jar and place it in libdirectory, located under

domain directory. This will add this jar file to the Weblogic Server System Classpath when server starts up.

Check the example JavaCallout code snippet below.

Use Case A particular user with email id [email protected] through internet store website.

This user would be recorded under a staging area by creating a fi le name [email protected]. An

email is sent to him to verify his email id which asks him to reply to the sent email. Now if user replies to the


14/47

8/12 Oacle Reie


email, UMS Adapter will pick the email. Now we want to check if this user has registered already through the

website. This can be done very well through Java Callout way. Please check the code snippet below.

Java callout example code

..;

import..F;

import...M;

import......ICC;

UMSA_CC implementsICC{

@O

(M ){

S FA =.S()[0]

.V();

S N ="//OS//".

(FA).(".");

F =newF(N);

if(.()){

returntrue;

returnfalse;

8. 46 User clicks Finish on the final page to finish defining the Adapter Service.


15/47

8/12 Oacle Reie


The corresponding BPEL process would look like below.

Sample BPEL Process

3.1.1.3 Message Mapping

The following snippets illustrate the message mapping in context of WSDL operation and the schema definition.

Sample WSDL File


16/47

8/12 Oacle Reie


Message Schema

Native Schema defined by the user singleString.xsd


17/47

8/12 Oacle Reie


The following snippet shows sample activation binding configuration file.

Binding Configuration

3.1.1.4 Connection Factory Properties

Table below describes Connection Factory Properties for the UMS Adapter.

Property Name Description

XATransaction Specify it with value 'false' to disable XA Transaction

support on inbound. Default value is 'true'

3.1.1.5 Activation Specification Properties

Table below describes Activation Properties available for the UMS Adapter.


JavaCalloutImpl Name of the java class which defines custom logic for a message filtering or

any other check. It's a concrete implementation of ICustomCallout interface.

ConsumeMode Specifies how the adapter will receive messages from UMS. Set to poller forpolling mode Or set to listener for listener mode.

To Address from which to receive incoming messages. One or more comma

separated email address for delivery type Email or mobile number when

delivery type is SMS.

DeliveryType Specify the message channel to receive/send messages. Email, SMS, IM in

case of receiving. Email, SMS, IM , Voice for sending outgoing message.

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.


18/47

8/12 Oacle Reie


InboundThreadCount Specify the number of inbound poller or listener threads.

3.1.1.6 Endpoint Properties

Table below describes the endpoint properties for the UMS Adapter inbound scenario.


Jca.retry.count Indicates the maximum number of retries before rejection.

Jca.retry.interval Indicates the time interval between retries (measured in seconds).

Jca.retry.backoff Indicates the retry interval growth factor (positive integer).

Jca.retry.maxInterval Indicates the maximum value of retry interval; that is, a cap if back-off

is greater than 1.

3.1.1.7 Normalized Message Properties

UMS Adapter will expose all applicable internet messages headers (defined under RFC 5322) along with mime message

headers (defined by RFC 822) and mime part headers (within a multipart construct. Note that its applicable only for the first

body part that is adapter payload. Mime headers for attachment are stored along with attachment) as normalized message

properties which can be manipulated from within a BPEL process.

Table below describes all the applicable headers defined by internet message format along with mapping with correspondingadapter header.

Table I Message Headers

Header Field Name Min Occurrence Max 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.resent-date

Resent-From 0 unlimited jca.ums.resent-from

Resent-Sender 0 unlimited jca.ums.resent-sender

Resent-To 0 unlimited jca.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 1 jca.ums.date

From 1 1 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 jca.ums.bcc

Message-ID 0 1 jca.ums.message-id

In-Reply-To 0 1 jca.ums.in-reply-to


19/47

8/12 Oacle Reie


References 0 1 jca.ums.references

Subject 0 1 jca.ums.subject

Comments 0 unlimited jca.ums.comments

Keywords 0 unlimited jca.ums.keywords

Note: that some of the above headers might appear more than once in a single message, multiple values of which will be set

to the same adapter header property, only to separate them with CRLF character sequence.

Table below describes all applicable Mime message headers.

Table II MIME-message headers

Header Field Name Mapped Adapter Header Field Name Notes

MIME-Version jca.ums.mime-version

Content-Type jca.ums.msg.content-type

Content-Transfer-Encoding jca.ums.msg.content-transfer-

encoding

Content-ID jca.ums.msg.content-id

Content-Description jca.ums.msg.content-description

Content-Disposition jca.ums.msg.content-disposition

Content-Language jca.ums.msg.content-language

Mime-Extension-field jca.ums.msg.mime-extension-

headers

Any other mime header field (might be

added in future) which begins with

string Content-. User can add more

than one headers as Content-* : value

CRLF Content*- : value

CRLF - \r\n

Table below describes all applicable MIME part headers.

Table III MIME-part 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 jca.ums.part.content-

language

Mime-Extension-field jca.ums.part.mime-

extension-headers

Any other mime header field (might be

added in future) which begins with string

Content-. User can add more than one

headers as Content-* : value CRLF Content*-


20/47

8/12 Oacle Reie


: value

CRLF - \r\n

Adapter should allow user to add any proprietary headers. Table below describes the mechanism.

Table IV - Proprietary Headers

Header Name Notes

jca.ums.msg.proprietary-

headers

More than one proprietary header

can be added as

Header Name : value CRLF Header

Name : value

(Header Name s hould be like

ums.adapter.xxxxx

CRLF - \r\n)

3.1.1.8 Receive Mode Polling Vs Listener

UMS has given both poller and listener option for applications to retrieve messages and adapter will be providing the same.

Adapter allows choosing between polling or listener mode to receive inbound messages. Polling can be used to process

messages in a batch with defined wait period in-between each poll, while listener mode can be used to receive and process a

message as and when available.

3.1.1.9 Inbound Polling Semantics

UMS d 47 oes not provide any formal JTA transaction support on inbound but relies solely on reliable messaging

through message acknowledgments for synchronous receive or polling way of message retrieval. UMS Adapter will make use

of this reliable messaging feature to avoid any message loss.

1. UMS API provides a synchronous receive () call. 48 In a reliable mode, if application calls receive (), but

then fails to call acknowledge () (both methods in the UMS client API), then the message will be put back in

the JMS queue (UMS uses JMS underneath) for later redelivery.

2. Adapter will use parametrized synchronous receive to get one message at a time, process it and

acknowledge it duly, which will help avoid any message loss. Note: Parametrized synchronous receive call incase of synchronous receiving of messages from UMS. Note - A360 requirement 557688: Throttling to

control the number of inbound messages to be delivered.

3. User can specify more than one polling threads for an activation using InboundThreadCount activation spec

property, each one of them will receive one message at a time, will process and publish it and then will

acknowledge. Note that polling thread is same as the process ing thread. Default value for this property is

one.

4. 49 Adapter will keep receiving message until messages are available in the INBOX. When there are no

more messages, only then, adapter will sleep for the polling interval specified by the user. This will avoid

mounting up large number of messages in the inbox, under high incoming message volume scenarios.

5. Each endpoint will have one UMS Connection (Messaging client instance) and all threads will use the same

UMS Connection (Messaging Client Instance) to receive messages. An instance of Messaging Client is notthread-safe and adapter will synchronize the access .

3.1.1.10 Inbound Listener Semantics

For asynchronous receiving of messages, user will opt for the listener mode. UMS Adapter will register a message listener

object. When incoming message arrives at the specified access point address, UMS infrastructure will invoke listener's

onMessage callback. Below are some important points on listener semantics.

1. User can specify adapter listener thread count by specifying an activation property, InboundThreadCount,

same as in polling case. This property value will be used by the adapter to set the property

MessageListenerThreads on UMS side. This property controls the number of listener worker threads on

UMS server side. Default value is one. Specifying this property means multi-threaded asynchronous receiving

of messages and for this case adapter has to handle multi-threaded access to the listener object that is


21/47

8/12 Oacle Reie


simultaneous calls to onMessage on the same message listener.

2. UMS Infrastructure will deliver one message per listener event.

3. For asynchronous receiving via onMessage callback the UMS library takes care of the acknowledgment. The

default is client_acknowledge, which means, it will acknowledge only after completion of the onMessage ()

method. Any exception thrown during the callback results in no acknowledgment and message is redelivered

later. This is the reliable mode.

4. Listener thread will be the processing thread.

3.1.1.11 Transaction Semantics

UMS does not offer any XA support on inbound and there is little chance of getting it in 12g time frame.

One of the important requirements for the adapter is to participate in the global transactions. To achieve this, adapter will

make use of LRC kind of optimization provided by the Weblogic server under JCA Resource Adapter Transaction

Management. Important points are below.

1. No XA transaction support for inbound listener mode of receiving messages. XA is applicable only for polling

way of receives.

2. By default, for inbound, adapter will always work in XA mode. This although can be changed by setting the

Connection Factory property 'XATransaction' to false.

3. Adapter will make use of JCA Resource Adapter, transaction management contract, under which Weblogic

server allows one (and only one) local transaction resource to be part of a 2PC that is XA transaction protocol.

Here the Weblogic server Connector Container uses a Last Resource Commit Optimization whereby theoutcome of the transaction is governed by the resource adapters local transaction.

4. The connection factory for the resource adapter is configured to use local transaction, this will make

application server to start a local transaction when the connection is created.

5. Along with above connection factory setting, a connection factory property named XATransaction is

required to be set to true. By default value of XATransaction property is true. This ensures that adapter

will always use XA on inbound.

6. With each receive of a message from UMS; adapter will start a global transaction.

7. A local transaction is started by the application server automatically when the resource adapter connection

that is configured to use local transaction is created and used within the context of XA. When the XA

transaction completes and is ready to commit, prepare is firs t called on the XA resources that are part of the

XA transaction. Next the local transaction is committed.

8. If the commit fails on the local transaction, the XA transaction and all the XA resources are rolled back. If

the commit succeeds, all the XA resource for the XA transaction are committed. When the adapter closes the

connection, Weblogic s erver cleans the connection once the transaction has completed.

9. Sequence of events are as below

10. The sequence of events:

1. Adapter start JTA

2. Gets hold of the CCI connection from the connection factory

1. Application servers gets hold of the SPI local transaction from the managed connection (within the

CCI connection)

2. Regis ters a Synchronization for JTA completion

3. Calls begin on the local transaction

3. the adapter does its business

4. Calls close() on the CCI connection

1. The application server receives a Connection Close event from the adapter

2. Checks to see if there is a transaction (either local or JTA) in progress

3. If it is in progress, then it does not release the connection back to the pool

5. Adapter commits JTA


22/47

8/12 Oacle Reie


1. SPI local transaction is committed

2. Rest of the 2pc resources commit

3. The Synchronization gets the notification

1. Notifies the connection pool that the transaction has completed

2. The managed connection is released

11. Processing, publish of the message to the composite and removal of the message from UMS by will be part

of the transaction.

12. This is an asynchronous service entry and successful commit on the adapter side will only start thecomposite execution (Bpel/mediator use database for scheduling of composite execution).

13. In case somebody wants to use a synchronous way, there will be restriction of only one non-XA resource

imposed by the Transaction Manager. User should keep this in mind while designing his composite

application.

14. Considering XA and rejection handling, please note that the existing JTA transaction will always be marked

for the rollback before rejecting the message.

3.1.1.12 Inbound Error Handling

Rejection Handlers

UMS Adapter as all other technology adapters will use the default rejection handling mechanism on the inbound side for

rejecting bad messages. For example, any translation related error will result into rejecting the message. This will work as anError Hospital to analyze errors.

1 Inbound Retryable Error Conditions

With retriable error conditions and when retry related endpoint properties are specified, adapter will try re-

publishing the inbound message for configured number of retries before rejecting the message. In case of

XA, transaction will be set for the rollback.

2 Inbound Non-retryable Error Conditions

For non-retriable error conditions, the message will be immediately rejected, with transaction set for the

rollback in case of XA.

3.1.1.13 Attachment Handling

Adapter will use the Fabric Attachment Managerto store and retrieve attachments.

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

Message Schema for Attachment

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 etc. along with a stream object (attachment content).

On the inbound side, adapter will set all mime details before passing attachment to Attachment Manager, while on the

outbound; adapter will extract any mime details received along with attachment object and will use them while creating the

outgoing SDP message notification.


23/47

8/12 Oacle Reie


Fabric Attachment Manager will update the href attribute with a key after storing the attachment to the database. This key

later can be used to retrieve attachment content.

Please check below the sample Normalized Message payload map with XML structure having attachment element, passed from

UMS Adapter to BPEL service engine.

Sample XML Message with attachment element

This is a test mail.-Sagar

The snippet below shows how attachments can be retrieved in BPEL

Getting Attachment in BPEL

And the snippet below shows how attachments can be set in BPEL.

Setting Attachment in BPEL

3.1.2 Inbound Receive Notification in a Cluster (Polling or through a Listener)

The same scenario as in 3.1.1 only targeted to a cluster environment for deployment.

UMS Adapter should support high availability in an active-active setup.

UMS API supports an environment where UMS server along with clients is deployed in a cluster environment. Below are

configuration details for UMS Adapter to work properly in a cluster environment.

1. All UMS Adapter activations of same composite will use the same unique ApplicationName configuration

parameters. Adapter will synthesize the application name parameter from inbox addresses on which the

particular endpoint is supposed to listen. This will allow all activations of a particular composite in a cluster to

share all configuration and artifacts such as Access Points and Message Filters etc.

2. ApplicationInstanceName configuration parameter is synthesized automatically by UMS the API

implementation and adapter will depend on the same.

3. UMS Adapter API implementation guarantees that in a cluster environment no two applications will receive

the same message.

4. Listener and Polling semantics should be same even while using adapter in a cluster environment.

Note - UMS Adapter also should support active fail-over of inbound service that is active-pass ive setup in a

cluster environment. This can be enabled through a JCA service binding property (composite.xml), singleton,

set to true.

3.1.3 Inbound In with SSL to communicate with IMAP/POP3 server

In this scenario, the adapter would function the same way as Inbound Receive scenario, described under 3.1.1. Design part


24/47

8/12 Oacle Reie


for Adapter Service as well as BPEL would be same. There would just be only additional configuration effort on the UMS side.

Enabling SSL would be the configuration on the UMS Server side for the Email driver.

User need to set the IncomingMailServerSSLproperty on the email driver to true. IncomingMailServerPortproperty value

should be changed accordingly to use the correct port in case of SSL.

3.1.4 Outbound Send Notification (Email, SMS, IM, Voice)

A synchronous request response or one way invoke scenario, where adapter client would request to s end the

notification. The Underlying adapter prepares the message notification (message body translated as per the schema)

and sends it to UMS server using UMS API. UMS server will return a message identifier after accepting the send

request. Adapter will return back the same as a response in case of synchronous request reply case. User can opt to

receive the message id, which will make it a s ynchronous request response call or just one way invoke without any

kind of response from the adapter.

Designing this service involves two main parts

1. Configuration on the UMS Server side to send outbound notifications.

2. Designing the Adapter Service and BPEL process.

3.1.4.1 Email Driver Configuration on UMS side.

On the UMS Side, for outbound scenario following are some of the email driver properties administrator need to

configure from the Enterprise Manager Console.

OutgoingMailServer - The name of the SMTP server

OutgoingMailServerPort - The port number of SMTP server50 OutgoingUsername - The username used for SMTP authentication.

OutgoingPassword - The password used for SMTP authentication

For details on configuring SMPP, XMPP and VoiceXML driver, please check UMS Admin Guide.

3.1.4.2 Design the Adapter Service and BPEL Process.

User would be using UMS Adapter Configuration wizard under JDeveloper to design the outbound adapter reference as

shown below.

1. User enters the SendEmailin the Service Name field as shown below.


25/47

8/12 Oacle Reie


2. Selects Outbound Send Notificationas the operation type. 51 - 52 User also specifies the type of

notification that is Email, SMS, Instant Message or Voice (text to speech). If user is interested in the

receiving the message id from the UMS server (to check message delivery status information), he can choose

a synchronous request-reply operation by selecting the Receive message id as a reply check box. In other

case, it would be a one-way invoke operation, which will just send a message notification.

3. 53 Notification Details Page.

1 User configures the Notification Message Details after selecting the type of Notification as Email, SMS,

IM or Voice.

1.1 For instance, selecting Email as the notification type, users enters other details as one or more email:

From addresses, one or more email: To addresses, one or more email: CC & BCC addresses, one or

more email: BCC addresses.

1.2 User can specify a ReplyTo address.

1.3 User also can specify a failover address for any primary address like primary address: failover

address. For example

[email protected]:[email protected]

In case of email this would be applicable for to, cc and bcc addresses.

1.4 User can choose to browse identity service using 'Identity Look-up Dialog' to search and fill address

attributes.

1.5 For all of the messaging channels, user can opt to specify a user or a group instead of a device

address. For example, USER:weblogic Or GROUP:admins.


26/47

8/12 Oacle Reie


2 Screen below shows endpoint attributes for SMS type

3 Screen below shows endpoint attributes for IM type.


27/47

8/12 Oacle Reie


4 Screen below shows endpoint attributes for Voice type.

4. One the Message Page, User enters schema details, which defines the outgoing notification payload.


28/47

8/12 Oacle Reie


5. Finally user clicks Finish on the final page to finish adapter wizard.

The corresponding BPEL process would look like below.

Sample BPEL Process


29/47

8/12 Oacle Reie


3.1.4.3 Message MappingThe following snippet illustrates the message mapping in context of WSDL operation and the schema definition.

Sample WSDL File


30/47

8/12 Oacle Reie


Message Schema Definition


31/47

8/12 Oacle Reie


Native Schema defined by the user singleString.xsd

And the following snippet illustrates the sample interaction Specification Properties.Sample Interaction Specification Properties


32/47

8/12 Oacle Reie


3.1.4.4 Interaction Specification PropertiesTable below describes the interaction properties available for the UMS Adapter.


DeliveryType Specify the message channel to receive/send messages. Email, SMS,

IM in case of receiving. Email, SMS, IM, Voice for sending outgoing

message.

Subject Subject of outgoing message.

From Sender addresses of outgoing message

To One or more recipient addresses

ReplyTo Reply-To address

Cc One or more cc addresses for email delivery.

Bcc One or more bcc addresses for email delivery.

Failover Fail-over address for outgoing message.

SendEmailAsAttachment True to send email as an attachment.

3.1.4.5 Normalized Message Properties OutboundPlease check 3.1.1.7 aboveto see applicable normalized message properties in relation with MIME and Internet

Message Headers.

Message Metadata headers defined below are only applicable on the outbound side.

Message metadata that is keywords defined and used under user preference based messagingwill also be exposed by

the adapter as message headers. Table below describes adapter headers mapped with the metadata keywords.

Table V - Message Metadata

Business Term Mapped adapter header field name

Service Name jca.ums.metadata.service-name

Process Name jca.ums.metadata.process-name

System Code jca.ums.metadata.sysetm-code

Error Code jca.ums.metadata.error-code

Occurrence Count (*) jca.ums.metadata.occurence-count

Organization jca.ums.metadata.organization

Time (**) jca.ums.metadata.time

Priority jca.ums.metadata.priority

Application jca.ums.metadata.application

Application Type jca.ums.metadata.application-type

Expiration Date jca.ums.metadata.expiration-data

From jca.ums.metadata.from


33/47

8/12 Oacle Reie


To jca.ums.metadata.to

Customer Name jca.ums.metadata.customer-name

Customer Type jca.ums.metadata.customer-type

Status jca.ums.metadata.status

Amount (*) jca.ums.metadata.amount

Due Date jca.ums.metadata.due-date

Process Type jca.ums.metadata.process-type

Expense Type jca.ums.metadata.expense-type

Total Cost (*) jca.ums.metadata.total-cost

Processing Time (*) jca.ums.metadata.processing-time

Order Type jca.ums.metadata.order-type

Service Request Type jca.ums.metadata.service-request-type

Group Name jca.ums.metadata.group-name

Source jca.ums.metadata.source

Classification jca.ums.metadata.classification

Duration (*) jca.ums.metadata.duration

User jca.ums.metadata.user

Role jca.ums.metadata.role

(*) - A string representing a floating decimal point number with double precision.

(**) A s tring representing time in HHMM format. HH is in 24 hour format. MM minutes.

3.1.4.6 Endpoint PropertiesTable below describes the endpoint properties available for the UMS Adapter outbound scenario.


jca.retry.count Indicates the maximum number of retries before throwing retryable

error condition back to invoking service engine.

jca.retry.interval Indicates the time interval between retries (measured in seconds).

jca.retry.backoff Indicates the retry interval growth factor (positive integer).

jca.retry.maxInterval Indicates the maximum value of retry interval; that is, a cap if the

backoff is greater than 1.

jca.retry.maxPeriod Indicates the maximum total retry period. Retries do not occur longer

than the value specified in this parameter.

3.1.4.7 Connection Factory PropertiesNone defined for an outbound scenario.

3.1.4.8 Transaction Semantics on the Outbound

UMS would be providing XA capabilities on outbound for 12c release. A360 requirement 557827: Ability for UMS to

participate in an XA transaction.

Below are some important points about transaction semantics on outbound.

1. Outbound JCA interaction are scoped with the global JTA transaction(adapter does not control any


34/47

8/12 Oacle Reie


transaction boundaries but would just participate in one).

2. UMS makes use of JMS underneath. Given the transaction fails, outbound send message delivered to the

queue would be rolled back. This will ensure that no false notification/alert would be sent by UMS.

3. The adapter defines the type of transaction support by specifying the transaction-support element in the

weblogic-ra.xml file. It can be XA, local or No transaction.

4. In case of XA, all composite activities along with UMS adapter invocation would be part of a global

transaction. All activities are either committed or rolled back if an error occurs.

5. One example would be a BPEL process inserting data into more than one tables along with sending an email

through UMS Adapter invocation. When the BPEL process is about to finish the JTA transaction is committed.

Only at that point, database inserts and email send invocation would be committed. If any error occurs

during BPEL instance execution, all activities (including email send invocation) would be rolled back to the

last dehydration point.

6. Considering XA and fault policy, please note that it's not advisable to use fault policy with XA as fault policy

runs in its own transaction and does not participate in the global transaction. This means that fault policy will

commit any existing JTA transaction before it starts executing the reference to which fault policy is bound.

7. In case of Local Transaction (SPI Local Transaction management contract), application server will start a

local transaction with a connection request and will commit the local transaction when global transaction is

about to be committed. Any exception conditions in-between, will result in the rollback. Adapter will

implement ConnectionEventListener to notify transaction related events.

3.1.4.9 Outbound Error Handling

1. Retriable Exceptions (Exact error conditions : TBD)

UMS Adapter like all other adapters will throw PCRetriableResourceException for transient error

conditions or in other words recoverable error conditions. For example connection errors.

For retriable errors, user can use retry policy supported by adapter framework, that is setting binding

property jca.retry.count. If you do not set jca.retry.count property then the retry is carried out through

fault policy, if fault policy is defined for the composite.

2. Non-retriable Exceptions (Exact error conditions TBD)

Non-retriable connection errors for outbound interactions can be handled by defining a fault-policy. The

maximum number of reconnection attempts can be defined through fault-policy.xml

3. Data Errors translation errors

One of the key features of Adapters is to translate the data from Native representation to standard

XML format and back based on the metadata captured at design time. A translation error aka

ResourceException is thrown when there is an exception thrown while carrying out translation. A

corresponding Binding Fault would be thrown which need to be captured for error recovery and repair.

This behavior is common across all adapters.

3.1.4.10 Retry Mechanism for Failed Outgoing Notifications with status reporting

1. UMS Adapter will make use of existing infrastructure given UMS itself for retrying failed outgoing

notifications.

2. Currently UMS only supports viewing of failed notifications along with manual send from Enterprise

Manager. For 12c, UMS will be giving support to configure the number of automatic retries upon messagedelivery failure. (A360 requirement: 557822: Configurable automatic retries for message delivery - Ability to

configure the number of automatic retries upon message delivery failure for outbound messaging - this is a

domain-wide setting, applicable to all channels. On a per message basis, consumers should be able to

override the default setting. Upon manual resend of a mes sage by an administrator (an action which is

already supported today), the number of automatic retries should still be applicable for the resend)

3.1.5 Outbound Send with TLS (SSL) to communicate with the SMTP serverIn this scenario, the adapter would function the same way as described under 3.1.4. Design part for the Adapter

service along with BPEL part would be the same. There would be additional configuration effort on the UMS server

side.


35/47

8/12 Oacle Reie


User needs to set the OutgoingMailServerTLSproperty on the email driver to true(default is false). This will enable

TLS encryption to communicate with the SMTP server.

4 Client Interfaces

4.1 Task Analysis, Roles, and Use Cases

4.1.1 HP

HP has the JCA adapter to integrate with the UMS to allow business processes to subscribe to multiple delivery

channels e.g. Email (POP and IMAP), SMS, Voice, and IM etc.

- Key requirement is to kick a BPEL process through emails.

- They need SSL support: that is enabling SSL while connecting to the Email Server.

No Requirement Analysis Feasibility Release

1 Connect to Exchange mailbox via IMAP or POP3

on SSL port (preferably IMAP as it offers

greater capability for manipulating messages

across mailboxes)

UMS default email driver is compatible

with POP3 and IMAP4 protocol.

Microsoft Exchange 2003 has been

verified.

Yes 12c

2 Poll various mailboxes for incoming email on

various schedules both sequential and parallel.

Some emails may need to be processed in

order, while others can be processed in any

order

Using more than one polling threads

ensures parallel process ing while using

a single thread ensures sequential or

in order processing.

Yes 12c

3 From the time a message is received in a

mailbox to the time when it is visible in or to a

user task should not exceed 5 minutes on

average

This totally will depend on the input

volume of messages and cannot be

guaranteed. Although user can opt to

increase poller threads to reduce the

time lag.

Yes 12c

4 Allow for throttling to control the number of

messages to be processed from a given mailbox

with a given time period.

Adapter should provide this using

Polling mechanism along with polling

interval.

Yes 12c

5 Upon receiving an email,

1. Parse the email into component parts

(including attachments)2. Properly handle content in various languages

including Chinese, Japanese, and the various

European languages

3. Properly handle different content types

including text, HTML, rich text, etc.

Yes 12c

6 Determine if email received is correlated with

running composite instance (BPEL) - this would

determine whether the email is processed by a

running instance, or whether a new instance is

created to process the email message

Adapter should give user an option to

add proprietary mail headers for an

outgoing message.

Yes 12c

7 Deliver parsed and properly encoded email

component parts to a target which could be a

queue (AQ/JMS), or a SOAP target to invoke

the appropriate process

This should be possible with

Bpel/Mediator along with email

activation. See 5 above.

Yes 12c

8 The adapter should handle errors in a way that

allows for either automatic recovery or some

form of automated handling

More details required on the use case - -

9 The adapter should have optimizations built in

for large-fi le handling since we can't predict

what size of attachments customers might

send. Note that we would prefer not to handle

attachments in SOA at all. We have a separate

1. Attachment Store - In the current

design, adapter will save all attachment

under Fabric Attachment Store.

2. This support has to come from fabric

1. Yes

2. No

12c


36/47

8/12 Oacle Reie


document management asset based on HP Trim

which is where all documents are stored and

eventually archived. Ideally, we would like to

post all attachments to HP Trim, and only

include returned references from Trim into the

process payload. I recognize that this poses a

challenge, but I also recognize that attempting

to handle unpredictably large documents in the

SOA Suite is probably just as challenging if not

more so.

itself, plugging in external attachment

stores.

10 The adapter should expose some run time

configuration capabilities including, for

example:

1. Ability to update account/password to be

used for polling any specific mailbox

2. Ability to schedule a purge of a particular

mailbox folder for all mail beyond a particular

age, or above a particular size, or containing a

particular subject, or sent from a particular

email address

This might be just beyond adapters

usual functionality that is what adapter

is supposed to do. Moreover, UMS

Adapter never is directly dealing with

any particular mail box on the email

server so carrying out admin tasks

related to mail box are out of scope.

No -

4.1.2 Rabobank


1 Business case SMTP Vs POP

1. For inbound e-mail, POP as protocol is not

sufficient because it requires connections for

each separate e-mail address, whereas SMTP

can handle multiple e-mail addresses

simultaneously.

SMTP support is available with UMS Yes 12c

2 Mail Filtering

1. Adapter can filter incoming messagesbased on SMTP from and to addresses, e.g.

*.rabomail.nl

2. Adapter can filter incoming messages

based on e-mail to address, from address, cc

address, subject, and mail headers

(header/regexp)

3. Mails can be ignored based on mime to

address, from address, cc address, subject,

and mail headers (header/regexp).

4. Business case: identify bounced replies,

e.g. through proprietary mail headers that

were added to the originating outgoingmessage (such end-to-end functionality that

is based on proprietary headers cannot be

guaranteed for 110%. Nevertheless, it can be

expected that it will cover 90+ %)

5. The adapter can generate auto replies

6. The filter can also block messages, i.e.

ignore them or move them to error hospital

or forward them to another location

1/2/3 - UMS does allow specifying Java

patterns while adding message filters.

User should be able to specify complex

filters for selectively receiving mails.

4 Support for adding proprietary

headers to outgoing mails.

5 Adapter will not directly generate

auto replies. Although user can use

adapter with the workflow for auto

replies.

6 Java Callout option can be used tofilter and move bad messages to error

hospital.

Yes 12c

3 Mail Routing

1. The system will be an MTA. Incoming

Routing messages to an external SMTP

server user should be able to achieve

Yes 12c


37/47

8/12 Oacle Reie


messages that do not match a filter of an

SMTP adapter will be either relayed to an

external SMTP Server, or put into the error

hospital, or

2. Avoid implementing an 'open relay' - add

security

this us ing adapter and workflow

together.

4 Mail handling - attachment store

1. Incoming mails are received in an XML

structure that reflects the structure of the

multipart mime format: no information will

be lost

2. Incoming attachments are stored in the

attachment store; in the mail they are

replaced with identifiers

3. Attachment store based on fi le, DB,

WebDAV, Stellent

4. Access to the attachments through a

special xslt look-up function

5. Optionally, this attachment store could

also be used by outgoing adapters: specially

formatted identifiers are replaced with the

content in the attachment store.6. The attachment store implements the

claim-check pattern

Attachment Store The adapter should

save attachments under Fabric

Attachment Store. We do have XSLT

functions under BPEL/Mediator to access

attachment content.

Claim-check pattern????

Yes 12c

5 Error handling

1. Error handling: retry policies for outgoing

mails that cannot be sent

2. Error handling: policies on incoming mails,

combined with above fi lter functionalities,

combined with Workflow Hospital

As all other adapters under adapter

stack, UMS Adapter should be supporting

fault-bindings and fault-policies for

rejection handling and retries .

Yes 12c

4.1.3 B2B Requirements


1Do we have to work with the UMS API to

create message or it is going to be like

any other adapter for sending message?

User would not be dealing with UMS API

2If t here is an option to initiate email, like

invoking any other interaction is

available. We have few questions,

Can we send the content as body or

attachment and both?

We have a requirement to send even

simple single content as

attachment but not as body. Can

this be done?

Can we send multiple attachments?

Sending email as an attachment

requirement is added under outbound

functionality.

Yes 12c

3As part of our notification requirement, we

may need to notify customers over

EMAIL, SMS and pager message etc. Do

we have support for all these messaging

platforms?

54 Support for Email, SMS, IM & Voice.

Currently no support for Pager.

Yes 12c

4We may need SSL support over EMAIL as

well.

Yes 12c


38/47

8/12 Oacle Reie


5 Need an option on the adapter side to

configure all UMS related metadata. This

would help us to capture endpoint details

in B2B console itself and

Initiate the adapter with required

information to send notification over

Email and/or other supported channels.

This support has to be given by UMS Team

first. The requirement has been given to

UMS by B2B team, but still hasnt received

any commitment for the same. If UMS

agrees to give it, adapter will give support.

Not

decided.

12c

5 Other Design Considerations

5.1 Scalability/Availability1. Adapter should be designed to use multi-threading/multiplexing wherever possible.

2. Should support Horizontal Scalability by distributing load across various nodes deployed.

3. Adapter should support dynamic fail over by seamlessly failing over to other available node in case one particular

node goes down.

4. UMS API supports an environment where UMS server along with client applications is deployed in a clustered

environment. More details are under functionality above.

5.2 Deployment and Life CycleJ2EE applications are expected to follow the standard J2EE deployment model and its life cycle. Some projects may

involve components or sub-components with a different life cycle, e.g. BPEL business processes.

If there is a deployment step involved, describe what needs to be done at that stage and what tools or user interfaces

support it.

Describe the run time configuration of the product after deployment, e.g. the processes that will run and the data

stores or services that will be accessed.

5.3 API & Libraries1. UMS API SDP libraries

2. Java Mail API

3. Oracle XDK

5.4 ExtensibilityS/MIME support There are plans to support S/MIME by UMS.

Support for Fax & Pager UMS does not support this right now, but user can opt for writing custom drivers for the

same.


39/47

8/12 Oacle Reie


Subject Author Status Assignee Modified Priorit

1

This section

seems to be

ver...

Siqun Li (siqli, s iqun. [email protected]) OpenSagar Shirguppi (sshirgup,

[email protected])

Mar 21,

2011

10:13:42

AM

0

Siqun Li (siqli, [email protected]): This section seems to be very much UI driven. There should be f unctions section desc ribes the

adapter inbound functionalities. The information I'd like to see in this section are: 1. Ac tivation Spec Properties definition. 2. Inbound Message

mapping from UMS to Normalized Message for each messaging type Email, SMS, IM. Simply referring to predefined schema in the appendix is

not enough. You indicated polling is a synchronous receive. What is the message pattern for polling? What would be the expected reply? 3.

How is attachment handled. Is Fabric attachment store required? Can attachment be s treamed to adapter inbound endpoints like OSB proxy.

4. Semantics f or applying Filters. 5. Semantics f or Listener mode. How many listener thread w ill each endpoint have? How many message

does each listener event deliver? Will the listener thread be the process ing thread? 6. Semantics f or polling mode should be moved to this

section as w ell for inbound functions. Will poller thread be proc essing thread? 6. What is the semantics in cluster? Is it a singleton? Is it

deployed as active/passive or active/active? How does listener and polling mode w ork in a cluster? 7. Comparison betw een listener and

polling mode, advantage and disadvantage? Why w ould a user choose one vs. the other. This w ill be very useful information. This w ill

answ er my question on w hy w e need tw o different mode for inbound. 8. Is there any binding properties? 9. Is there any Normalized

Message Properties? 10. (Feb 22, 2011 11:57:43 AM)

Sagar Shirguppi (sshirgup, [email protected]): 1. I have removed ActivationSpec properties f rom the end of the document

and added it under Inbound Receive Notification f unctionality. (Mar 10, 2011 4:48:58 AM)

Sagar Shirguppi (sshirgup, [email protected]): 2. Are you asking message pattern betw een adapter and Service

Engine(BPEL/Mediator) or betw een UMS server and UMS Adapter? synchronous receive, I mentioned is betw een UMS and adapter. It's a

synchronous call and returns a message(oracle.sdp.messaging.Message) if available. (Mar 10, 2011 5:15:21 AM)

Sagar Shirguppi (sshirgup, [email protected]): 3. Can you pls elaborate a little on how OSB proxy is us ed to stream

attachments into an endpoint? I am not sure, but I am suspecting that this might not be feasible. (Mar 11, 2011 5:11:44 AM)

Sagar Shirguppi (sshirgup, [email protected]): 4. I have added details on how filters w ill be applied. (Mar 12, 2011 9:30:29

PM)

Sagar Shirguppi (sshirgup, [email protected]): 5. semantics for listener mode is added. (Mar 13, 2011 1:25:47 AM)

Sagar Shirguppi (sshirgup, [email protected]): 6. I have moved semantics for polling/listener mode and other details to the

first section. (Mar 13, 2011 1:26:22 AM)Sagar Shirguppi (sshirgup, [email protected]): 7. We have a requirement for polling mode f rom a customer, but there is

not any requirement yet for listener mode, though UMS supports these both modes of message retr ieval and it's better to support both modes

as there might be some special use case f or listener mode. (Mar 13, 2011 9:05:39 AM)

Sagar Shirguppi (sshirgup, [email protected]): 8. Retry related binding properties w hich are same for all adapters. I

already have added them to the spec. (Mar 13, 2011 9:08:32 AM)

Sagar Shirguppi (sshirgup, [email protected]): 9. I have added normalized message properties details. (Mar 13, 2011 7:04:54

PM)

Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 16, 2011 1:08:39 AM)

Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(Mar 16, 2011 1:08:39 AM)

Siqun Li (siqli, [email protected]): In general, w e should have UI feature separated f rom runtime feature in the spec. I'm looking for

message pattern for each operation between adapter and service engine. When you say a specif ic operation is sync request/reply or

request only, you w ould need to clearly specify the message pattern for these operations, otherw ise people w ould have no w ay of

knowing how the messages are mapped. This w ill be very important for customer as w ell as our QA, doc . Like I mentioned in the attachment

section comment, OSB receives attachment from JCA f ramew ork as part of the NormalizedMessage. In Normalized message, attachment is

presented as a map of contentID as key and JCA f ramew ork Attachment object as value w hich include attachment headers and attachment

InputStream. (Mar 21, 2011 9:52:42 AM)

Siqun Li (siqli, [email protected]):Assignee changed from 'siql i' to 'sshi rgup'(Mar 21, 2011 9:52:42 AM)

Siqun Li (siqli, [email protected]): Status changed from 'Fied' to 'Open'(Mar 21, 2011 10:13:42 AM)

2

Suggest w e use

the same term...Siqun Li (siqli, [email protected]) Fixed Siqun Li (siqli, [email protected])

Mar 21,

2011

7:15:44 AM

0

Siqun Li (siqli, [email protected]): Suggest w e use the s ame term for attachment attribute as SOAP Message w ith Attachment spec

to reduce c onfusion, e.g. ContentType instead of MimeType, ContentTransferEncoding instead of ContentEncoding. (Feb 28, 2011 1:31:51 PM)

Sagar Shirguppi (sshirgup, [email protected]): Let me see, w e can change ContentEncoding to

ContentTransferEncoding, but I feel MimeType should be kept as it is, as it's in accordance w ith Internet Mail Message vocab. (Mar 21, 2011

7:15:44 AM)



3

So w hat is the

transaction s...Siqun Li (siqli, [email protected]) Fixed Siqun Li (siqli, [email protected])

Mar 21,

2011

2:48:13 AM

0

Siqun Li (siqli, [email protected]): So w hat is the transaction semantics for inbound then? (Feb 22, 2011 2:54:56 PM)

Sagar Shirguppi (sshirgup, [email protected]): There is slight change in the transac tion semantics on inbound. I w ill add

details to the new v ersion. (Mar 14, 2011 8:34:09 PM)



4

Can you

elaborate on this

id...


[email protected])

Mar 21,

2011

10:22:49

AM

0

Siqun Li (siqli, [email protected]): Can you elaborate on this identity look-up? (Feb 22, 2011 2:36:51 PM)

Sagar Shirguppi (sshirgup, [email protected]): This is a identity look-up dialog available under jdeveloper w hich enables

lookup of users, roles etc. f rom an Identity Service. This w ill facilitate looking up users in the corporate directory and f ind out details such as


40/47

8/12 Oacle Reie


email/telephone/cell no. etc. Notification service already is us ing this dialog. You c an check it under JDeveloper 11g. (Mar 14, 2011 7:29:29 AM)


Siqun Li (siqli, [email protected]): Will be good to elaborate that. Especially for OSB dev, QA, doc people w ho are not f amiliar w ith

this feature. Thanks. (Mar 21, 2011 10:22:49 AM)


5

Does UMS

adapter support

lar...


[email protected])

Mar 21,

2011

9:27:22 AM

0

Siqun Li (siqli, [email protected]): Does UMS adapter support large message using SDOM? (Feb 22, 2011 11:15:19 AM)

Sagar Shirguppi (sshirgup, [email protected]): We have not receive any requirement for large payload support as of

now . As of now w e just have a requirement of large attachments, but attachments w ill be handled through fabric attachment store. I alw ays

have seen that there is a s ize restriction in case of emails, posed by email servers ...so I am not sure if w e should add large message using

SDOM. (Mar 9, 2011 10:08:52 PM)Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 14, 2011 6:29:28 AM)

Siqun Li (siqli, [email protected]): So w hat is the message size limit for the email servers w e support? If large message is not

supported, w e should have a s ection for Non-Feature to indicate this limitation. It w ould help to specify that size limit imposed by email

servers, and state that UMS adapter does not impose message payload size limit and it w ill not support the PayloadSizeTheshold property.

(Mar 21, 2011 9:27:22 AM)


6

If this is similar

to the "N...

SUJAY BANDYOPADHYAY (sbandyop,

[email protected])Fixed

SUJAY BANDYOPADHYAY

(sbandyop,

[email protected])

May 8,

2011

6:30:05 AM

0

SUJAY BANDYOPADHYAY (sbandop, suja.bandopadha@oracle .com): If this is s imilar to the "No native schema translation

required" checkbox on the adapter Schema Page, w e could use that instead of this. (Feb 22, 2011 9:17:39 AM)

Sagar Shirguppi (sshirgup, [email protected]): Yes. I w ill remove it from this screen so that there w ill be no confusion.

(Mar 14, 2011 7:35:06 AM)

Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'sbandop'(Mar 14, 2011 7:35:06 AM)

Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(May 8, 2011 6:30: 05 AM)

7

We need a

section here to

de...

Siqun Li (siqli, [email protected]) Fixed Siqun Li (siqli, [email protected])

Mar 14,

2011

6:29:42 AM

0

Siqun Li (siqli, [email protected]): We need a section here to describe how inbound works in cluster. (Feb 22, 2011 3:15:32 PM)

Sagar Shirguppi (sshirgup, [email protected]): section has been added. (Mar 9, 2011 9:55:02 PM)

Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(Mar 9, 2011 9:55:02 PM)

Sagar Shirguppi (sshirgup, [email protected]): I w ill publish the corrected version. (Mar 14, 2011 6:29:16 AM)


8

What if

outbound

invocation ...


[email protected])

Mar 21,

2011

10:26:26

AM

0

Siqun Li (siqli, [email protected]): What if outbound invocation is not in global transaction? What happens then? (Feb 22, 2011 2:57:14PM)

Sagar Shirguppi (sshirgup, [email protected]): Outbound XA mainly solves the problem of false notification. If any of the

participating party fails, the notification w hich is sent to the UMS server w ill be rolled back. Without transaction this w on't be possible. I w ill

add these details to the spec. (Mar 14, 2011 8:59:53 PM)

Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 14, 2011 8:59:53 PM)

Sagar Shirguppi (sshirgup, [email protected]): In case of BPEL at least, I believe it always star ts a transac tion if there is

not a JTA transaction existing and adapter just participates. Now if there is no tr ansaction and if user opts for XA on outbound, then it

should fail w hile enlisting the XAResource. (Mar 21, 2011 3:07:00 AM)

Siqun Li (siqli, [email protected]): I hope you have capture all this information in the transaction semantics sec tion. If not, please do in

the next ver sion. Thanks. (Mar 21, 2011 10:26:26 AM)


9

Please define

transaction bo...Siqun Li (siqli, s iqun. [email protected]) Fixed

Sagar Shirguppi (sshirgup,

[email protected])

Mar 14,

2011

8:56:25 PM

0

Siqun Li (siqli, [email protected]): Please def ine transaction boundaries. (Feb 22, 2011 2:56:20 PM)Sagar Shirguppi (sshirgup, [email protected]): Added to the new version of spec. (Mar 14, 2011 8:56:25 PM)


10

I think I had the

question o...Siqun Li (siqli, [email protected]) Open Siqun Li (siqli, [email protected])

Mar 14,

2011

7:34:14 AM

0

Siqun Li (siqli, [email protected]): I think I had the question of w hy payload is entered here. I'm not sure it w as addressed or not. (Feb

22, 2011 2:40:10 PM)

Siqun Li (siqli, [email protected]): A ttachment handling semantics should be clearly def ined. (Feb 22, 2011 2:40:46 PM)

Sagar Shirguppi (sshirgup, [email protected]): I w ill remove the payload part from this screen as now w e w ill alw ays be

using a schema to def ine the payload. Either user def ined or opaque as def ined on the Message page. I have added the attachment handling

part. I will post the update version of the spec. (Mar 14, 2011 7:34:14 AM)


Does attachmentMar 21,


41/47

8/12 Oacle Reie


11

make sense f ... Siqun Li (siqli, siqun.li@orac le.com) Open Siqun Li (siqli, s iqun.li@orac le.com) 2011

6:17:19 AM

0

Siqun Li (siqli, [email protected]): Does attachment make sense for IM, SMS, voice? (Feb 28, 2011 1:29:29 PM)

Sagar Shirguppi (sshirgup, [email protected]): It's adhering to the Internet Message Format, that used by the Java Mail

API and again by UMS. It might not make sense for some of the channels. (Mar 21, 2011 6:17:19 AM)


12

Need for details

about this ...



SUJAY BANDYOPADHYAY

(sbandyop,

[email protected])

May 8,

2011

6:29:52 AM

0

SUJAY BANDYOPADHYAY (sbandop, suja.bandopadha@oracle .com): Need for details about this lookup. (Feb 22, 2011 9:15:17 AM)

Sagar Shirguppi (sshirgup, [email protected]): I have seen this identity lookup w hile using Notificaiton Service under

JDeveloper. You can check it out and see if it's possible or not. (Mar 14, 2011 6:36:14 AM)Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'sbandop'(Mar 14, 2011 6:36:14 AM)

Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(May 8, 2011 6:29: 52 AM)

13

If attachment

can be text, t...Siqun Li (siqli, s iqun. [email protected]) Open


[email protected])

Mar 1, 2011

1:22:11 PM0

Siqun Li (siqli, [email protected]): If attachment can be text, then there w ill be charset parameter in content type. The

AttachmentType should accommodate that. (Mar 1, 2011 1:22:11 PM)

14

You mention

VoiceXML here,

b...

Siqun Li (siqli, s iqun. [email protected]) FixedSagar Shirguppi (sshirgup,

[email protected])

Mar 13,

2011

7:10:02 PM

0

Siqun Li (siqli, [email protected]): You mention VoiceXML here, but Voice is not one of the the supported inbound messaging types

as you specified in the title for 3.1.1. (Feb 22, 2011 11:23:57 AM)

Sagar Shirguppi (sshirgup, [email protected]): removed (Mar 13, 2011 7:09:21 PM)


15

Sagar, do w e

need to

capture...




[email protected])

May 7,

2011

11:16:19

PM

0

SUJAY BANDYOPADHYAY (sbandop, suja.bandopadha@oracle .com): Sagar, do we need to capture the nxsd schema path and

element as jca properties? Other jca adapters

Date post:	12-Feb-2018
Category:	Documents
Upload:	chaitra-nath
View:	228 times
Download:	0 times