Ums adapter
-
Upload
chaitra-nath -
Category
Documents
-
view
229 -
download
0
Transcript of 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
-
7/23/2019 Ums adapter
2/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
3/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
4/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
5/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
6/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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/23/2019 Ums adapter
7/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
8/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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].
-
7/23/2019 Ums adapter
9/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
10/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
11/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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)
-
7/23/2019 Ums adapter
12/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
13/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
14/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
15/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
16/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
Message Schema
Native Schema defined by the user singleString.xsd
-
7/23/2019 Ums adapter
17/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
Property Name Description
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.
-
7/23/2019 Ums adapter
18/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
Property Name Description
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
-
7/23/2019 Ums adapter
19/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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*-
-
7/23/2019 Ums adapter
20/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
: 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
-
7/23/2019 Ums adapter
21/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
22/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
23/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
24/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
25/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
26/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
2 Screen below shows endpoint attributes for SMS type
3 Screen below shows endpoint attributes for IM type.
-
7/23/2019 Ums adapter
27/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
4 Screen below shows endpoint attributes for Voice type.
4. One the Message Page, User enters schema details, which defines the outgoing notification payload.
-
7/23/2019 Ums adapter
28/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
5. Finally user clicks Finish on the final page to finish adapter wizard.
The corresponding BPEL process would look like below.
Sample BPEL Process
-
7/23/2019 Ums adapter
29/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
3.1.4.3 Message MappingThe following snippet illustrates the message mapping in context of WSDL operation and the schema definition.
Sample WSDL File
-
7/23/2019 Ums adapter
30/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
Message Schema Definition
-
7/23/2019 Ums adapter
31/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
Native Schema defined by the user singleString.xsd
And the following snippet illustrates the sample interaction Specification Properties.Sample Interaction Specification Properties
-
7/23/2019 Ums adapter
32/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
3.1.4.4 Interaction Specification PropertiesTable below describes the interaction properties available for the UMS Adapter.
Property Name Description
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
-
7/23/2019 Ums adapter
33/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
Property Name Description
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
-
7/23/2019 Ums adapter
34/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
35/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
-
7/23/2019 Ums adapter
36/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
No Requirement Analysis Feasibility Release
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
-
7/23/2019 Ums adapter
37/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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
No Requirement Analysis Feasibility Release
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
-
7/23/2019 Ums adapter
38/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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.
-
7/23/2019 Ums adapter
39/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
Subject Author Status Assignee Modified Priorit
1
This section
seems to be
ver...
Siqun Li (siqli, s iqun. [email protected]) OpenSagar Shirguppi (sshirgup,
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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 21, 2011 7:15:44 AM)
Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 21, 2011 2:48:13 AM)
Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(Mar 21, 2011 2:48:13 AM)
4
Can you
elaborate on this
id...
Siqun Li (siqli, s iqun. [email protected]) OpenSagar Shirguppi (sshirgup,
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
-
7/23/2019 Ums adapter
40/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(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)
Siqun Li (siqli, [email protected]):Assignee changed from 'siql i' to 'sshi rgup'(Mar 21, 2011 10:22:49 AM)
5
Does UMS
adapter support
lar...
Siqun Li (siqli, s iqun. [email protected]) OpenSagar Shirguppi (sshirgup,
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)
Siqun Li (siqli, [email protected]):Assignee changed from 'siql i' to 'sshi rgup'(Mar 21, 2011 9:27:22 AM)
6
If this is similar
to the "N...
SUJAY BANDYOPADHYAY (sbandyop,
[email protected])Fixed
SUJAY BANDYOPADHYAY
(sbandyop,
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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 14, 2011 6:29:16 AM)
8
What if
outbound
invocation ...
Siqun Li (siqli, s iqun. [email protected]) OpenSagar Shirguppi (sshirgup,
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)
Siqun Li (siqli, [email protected]):Assignee changed from 'siql i' to 'sshi rgup'(Mar 21, 2011 10:26:26 AM)
9
Please define
transaction bo...Siqun Li (siqli, s iqun. [email protected]) Fixed
Sagar Shirguppi (sshirgup,
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)
Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 14, 2011 7:34:14 AM)
Does attachmentMar 21,
-
7/23/2019 Ums adapter
41/47
8/12 Oacle Reie
ie..oacle.com/eie/pinable-ie.do
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)
Sagar Shirguppi (sshirgup, [email protected]):Assignee changed from 'sshi rgup' to 'siqli '(Mar 21, 2011 6:17:19 AM)
12
Need for details
about this ...
SUJAY BANDYOPADHYAY (sbandyop,
[email protected])Fixed
SUJAY BANDYOPADHYAY
(sbandyop,
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
Sagar Shirguppi (sshirgup,
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,
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)
Sagar Shirguppi (sshirgup, [email protected]): Status changed from 'Open' to 'Fied'(Mar 13, 2011 7:10:02 PM)
15
Sagar, do w e
need to
capture...
SUJAY BANDYOPADHYAY (sbandyop,
[email protected])Fixed
Sagar Shirguppi (sshirgup,
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