| Oracle® Fusion Middleware Administrator's Guide for Imaging and Process Management 11g Release 1 (11.1.1) E12782-01 |
|
 Previous |
 Next |
Home > Administrator's Guid... > Working with BPEL > Business Process Execution ...
| Oracle® Fusion Middleware Administrator's Guide for Imaging and Process Management 11g Release 1 (11.1.1) E12782-01 |
|
Previous |
Next |
Home > Administrator's Guid... > Working with BPEL > Business Process Execution ...
Business Process Execution Language (BPEL) is an executable language for specifying interactions with web services. It extends and enables the web services interaction model to support business transactions and human interaction. BPEL is emerging as the clear standard for composing multiple synchronous and asynchronous services into collaborative and transactional process flows. BPEL is to business process management what SQL is to data management.
You can use BPEL to define services that can be used by other applications. You define all aspects of a process, from the definitions of data required to start a process to the available forms for human interaction with a process. These components are bundled into a composite and deployed to an SOA server.
To integrate a BPEL process with I/PM, you must complete the following steps:
Ensure that the AgentUser configuration MBean is defined (see "Configuring the AgentUser and GDFontPath MBeans".
Create a BPEL connection (see "Creating a BPEL Connection").
Create an application with a BPEL process defined within it (see "Creating An Application".
Configure BPEL properties, which is part of the process to create an application in the Oracle I/PM user interface (see "Configuring BPEL Properties").
The BPEL process can be added to an application when the application is created, or by modifying an existing application. Adding a BPEL process begins with the Application BPEL Configuration Page. When you configure an application to use BPEL, you must ensure that a connection to a BPEL server has been created and select the BPEL connection on the BPEL Server Properties Page. The BPEL Server connection must include a name, protocol, server, and port (for example, name=t3://sta00319:7001). Oracle I/PM must authenticate with the server to discover the deployed BPEL components.
Once connected to the server, a list of BPEL components is identified. A BPEL component can provide many different services, so you must identify the service you want to use on the BPEL Component Properties Page. Services can be invoked in multiple ways, so you must also identify the operation used to start a process.
This operation is assumed to be asynchronous; it is a one-way communication into BPEL. Oracle I/PM uses it to initiate a process instance and does not wait for a response. A business process may take hours or days to complete. Once the operation is selected, Oracle I/PM knows which data has to be provided to start the process. This is called the payload.
BPEL uses web services so the payload reflects the data contained in the Web Services Description Language (WSDL) that defines the service. This data is represented as a schema with defined data types. On the BPEL Payload Properties Page, the payload type and a list of allowed values are displayed which are called mapping functions. BPEL Payload Mapping Functions return a value of a given type: text, number, date, and so on. If the payload value can accept a date, mapping functions that return a date are shown. If a text function cannot properly evaluate to a date, it is excluded from the list of available functions. If the payload value can accept a string, then all mapping functions are allowed since they can all be represented as text.
The BPEL Payload Properties is used to map IPM application metadata fields to elements within a BPEL process service payload. Predefined mapping functions are associated with simple typed elements in the payload. At runtime, when a document is created and the BPEL agent is triggered to create a BPEL process instance for the document, the mapping function for each element is evaluated to transform metadata from the document into payload element values. The mapping functions that are available may provide the raw metadata of the document, including system properties and application defined field values. A special mapping function named Format Value is also provided, allowing mapping of any value. The format is custom concatenation of constant values as well as values from other mapping functions.
Mapping functions are typically specific to type and must match the schema type of the payload element. This means that numeric, decimal, and date types in the payload may only map be mapped with mapping functions that return these types. String types in the payload can typically be mapped with any mapping function. Also, the Format Value mapping function can be mapped to any payload element. However, The Format Values return type is technically a string, and care must be taken to ensure that the return value is a valid string representation of the payload schema type.
The following table lists the available specific payload schema types and their compatible mapping functions:
| Schema Types | Mapping Function |
|---|---|
| string, normalizedString, token | All Functions
All Field Values |
| anyType | All Functions
All Field Values |
| anyUri | DocUrl
DocUrlRoot Format Value |
| byte
unsignedByte integer positiveInteger negativeInteger long unsignedLong short unsignedShort Note: I/PM uses integer bounded types to store numbers. Mapping to schema elements with lower bounds is allowed but may result in errors or loss of data during mapping execution |
AppId
BatchId DocSize Version Format Value Number Field Values |
| time
date dateTime |
Create Date
Modify Date Volume Date Format Value DateField Values |
| Boolean | True
False Boolean Field Values |
| All other schema types | Format Value |
Format Values for types other than string-based types must return valid string representation of the schema type. Also, there are many other valid payload schema XSD types that may be present in a payload. Format Value is the only mapping function supporting types other than those specifically listed in the table above. As with other Format Value usages, it is up to the application and BPEL process implementer to ensure that the format string returns a compatible type. Because the actual value returned is only known at runtime, I/PM cannot do any validation on such a configuration. It is recommended that payloads use the known types listed in the above table whenever possible.
BPEL payload elements annotated with minOccurs are defined as being required when mapping I/PM application fields. These elements are designated with a (*) symbol on the BPEL Payload Properties Page of the I/PM user interface.
Payload elements with a minOccurs=1 are interpreted as being required and I/PM requires a mapping for them. In this case, required means that the element must be supplied in the payload, but does not need a value. It is possible for a field value mapped to a payload element to be null even when mapped to a minOccurs=1 payload element. In this case, an empty element will be passed. In cases where the BPEL process wants required to mean that a value must be supplied, the application field value mapped to the element can be marked as required in the application definition to ensure that it has a value. The BPEL payload mapping does not enforce this.
Payload elements with a minOccurs=0 are interpreted as being optional and need not be supplied in the payload if there is no mapping for the element. This means that providing a mapping is optional as well. If no mapping is provided, the node will not be included in the payload sent to the BPEL server. If a mapping is provided, however, the node will always be included, even if the value returned by the mapping function is empty. In this case, an empty element node is passed.
|
Note: In the BPEL payload, Oracle I/PM does not support types where the minOccurs or maxOccurs attributes are greater than one. |
For mapping functions that map to a payload schema date or time based type (time, date, dateTime), values are encoded to ISO 8601 compliant formats as follows:
| Schema Type | Format | Example |
|---|---|---|
| time | hh:mm:ss±tz | 12:45:15-05:00 |
| date | yyyy-MM-dd | 2009-11-09 |
| datetime | yyyy-MM-ddThh:mm:ss±tz | 2009-11-09T12:45:15-05:00 |
As indicated, types that include a time use the positive/negative time zone designator as an offset in hours and minutes (hh:mm).
Document property functions assign the value of a system property of the document to a payload element. Document Id, Application Name, Create Date, etc.
The Field Value function assigns application field values from a document to a payload element. Although “Field Value” is technically the name of the function, with the name of the field as a parameter, the BPEL Payload Properties page presents each of an application's field definitions as a item in the mapping function selection box listed by the field's name. As with all mapping functions, the field definition type is used to determine whether or not it is compatible with the payload element schema type. Only compatible field values are listed as options next to any particular payload element.
Format value is a special mapping function that allows assigning any string value to a payload element. The format value can also embed multiple other mapping function values in the format string value as variables that will be supplied at runtime.
A format value is assigned to a payload item on the BPEL Payload Properties page be selecting Format Value as the mapping function and then clicking the Edit Format Value button that appears next to selection box. On the “Edit Format Value” dialog that appears, the format value is entered at the bottom. A selection list a top provides available mapping function scan be inserted into the edit box. (Items append to the end of any currently entered text.)
When creating a format value string manually, mapping function variables are encoded in the value using the mapping function name surround by square brackets (e.g., “[DocUrl]”). Field Values are coded by include the mapping function (Field Value), a colon, and then the desired field name, all within square brackets.
For an example, suppose that the BPEL process includes a data variable that is expected to contain custom URL. The custom URL must include a customerId, which is available in the metadata of the document, and the document's unique identifier. The root of the URL is hard coded. This example might be coded in a format value as follows:
http://example.com/svc.jspx?custId=[FieldValue:custId]&docId=[DocId]
In general, the BPEL payload mapping can handle payloads containing nesting of complex types. However, there are of number of standard XSD constructs that it cannot handle. BPEL process service payload definitions contained any of the following cannot be used:
Hierarchical depth greater than 10
Choice element types
List elements with minOccurs greater than 1
Payload definitions containing list like structures with (maxOccurs is greater than 1 or unbounded) with a minOccurs equal 0 or 1 can be used, but only support mapping to a single element in the array.
When the BPEL Process service has server-side Oracle Web Services Manger (OWSM) policies applied to it, additional parameters need to be supplied in the imaging application's BPEL configuration such that the client-side policy is also used. These additional configuration parameters are provided on the BPEL Payload Properties Page with the normal BPEL process instance payload mappings. If the service has a OWSM policy applied, Oracle I/PM detects this policy and provides an additional payload mapping section labeled as “”. The full set of keys that are possible for all OWSM policies is provided by the OWSM API in the class oracle.wsm.security.util.SecurityConstants. Oracle I/PM however filters out the full set and lists only those parameters relevant to the server policy in use. Currently, only parameters are provided for wss_username_token and wss11_username_token_with_message_protection policies.
The following parameters are possible:
| Parameter | Description | Policies |
|---|---|---|
| csf.key | Provides the username and password for the policy. | wss_username_token
wss11_username_token_with_message_protection policies |
| recipient.key.alias | Provides the key store alias for encrypting the sent message. | wss11_username_token_with_message_protection policies |
For more information on setting up keystores, CSF keys and aliases for Oracle Web Services Manager, see Oracle Web Services Manager Administrator's Guide.
A work manager is a WebLogic server concept for controlling how many threads are assigned to a process. In Oracle I/PM, they are used to control how many threads are assigned to the input and BPEL agents and for increasing or decreasing their load on the system. On a new installation, the BPEL agent is assigned 20 threads. You can reconfigure how many threads WebLogic server (WLS) should provide to the input and BPEL agents by changing the default settings of the WLS work managers BpelMaxThreadConstraint (default 20) to match your system needs.
To update thread settings, complete the following steps from the WLS administration console.For more information about the WebLogic server, see Weblogic Web Services Reference for Oracle Weblogic Server.
Open the WebLogic Server console and click Deployments.
Select the Imaging deployment to display the details for Oracle I/PM.
Click the Configuration tab and then the Workload tab to display the Work Manager list.
Select the agent you want to adjust, either BpelAgent.
Select the Max Threads Constraint.
Update the count to the new maximum thread count and click Save.
Restart the managed server or servers and the new thread count will be in effect.
A credential store framework (CSF) credential is a username/password pair that is keyed by an alias and stored inside a named map in the CSF. Because of its integration with Oracle Web Services Manager (OWSM), Oracle I/PM leverages the standard OWSM CSF map named oracle.wsm.security.
A credential can be created through Enterprise Manger (EM) or through WebLogic Scripting Tool (WLST). For details, see "Configuring a BPEL Connection CSF Credential".
If the BPEL agent cannot connect to the BPEL server, there will be three immediate attempts at connection. If all three attempts fail, the message is returned to the JMS queue for deployed process. The BPELInjectorQueue JMS queue is configured for a five minute retry delay. Each subsequent retry attempt to process the message is again manually retried three times. Like the manual retry mechanism, the message is returned to the queue two times (for three process attempts). After the third message processing attempt fails, the document details are written to a BPEL agent faults table, including the exception message from the last exception received, and the message is not returned to the queue. This provides nine retries over a time period of 10 minutes. Note: If for any reason the attempt to record the document details to the fault table fails, the message is returned to the queue to avoid dropping the request.
BPEL agent processing faults that are recorded to the faults table are managed using a set of WebLogic Scripting Tool (WLST) diagnostic commands. To access these commands, you must execute WLST from the Enterprise Content Management $ORACLE_HOME/common/bin directory. Also, when connecting to WLST, you must connect to an Oracle I/PM managed server instance, not the admin server. These commands are only available when the Oracle I/PM managed server is online.
The following BPEL diagnostic commands are available using WLST:
sumIPMBpelFaults: Counts processing failures during BPEL agent processing, grouped by choice of date, application ID, or batch ID.
clearIPMBpelFaults: Clears processing failures that occurred during BPEL agent processing.
listIPMBpelFaults: Provides details of processing failures that occurred during BPEL agent processing.
repairIPMBpelFaults: Repairs processing failures that occurred during BPEL agent processing.
Details about use and syntax of these faults can be found in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Once a user has configured all of the BPEL properties, they are ready to be used to initiate BPEL processes. When a document is uploaded to Oracle I/PM, a message is sent to the BPEL agent indicating new content. The BPEL agent monitors these messages, and when it receives a message that the document's application has been configured to use BPEL, it uses the configuration to build a payload of values for that specific document and then calls the service to initiate a BPEL process.
The BPEL process must be designed in such a way that if a user needs to look at a document from Oracle I/PM, it has the necessary information needed to launch the viewer. This can be accomplished by defining a payload value to hold the viewer URL. It is up to the BPEL designer to create a form that includes a button or link to open the target of the viewer URL property. If the business process must update information in Oracle I/PM, it can do so by using the Oracle I/PM API. For more information about APIs, see Oracle® Fusion Middleware Developer's Guide for Imaging and Process Management. The Oracle I/PM API is exposed as a web service which can easily be added to any BPEL process by a process designer. Again, the designer needs to ensure that he or she has collected enough information at the start of the process to communicate updated data for the document. For example, the document ID and application field names would be necessary.
