10 Understanding Workflow Agents

This section contains the following topics:

10.1 Business Process Management

Business Process Management (BPM) technology is a framework for applications that can effectively track and orchestrate business processes. BPM solutions can automatically manage processes and process flow, yet also allow for manual intervention when necessary.

For example, BPM might coordinate the extraction of customer information from a database or manage a new customer information transaction. BPM could generate transactions in multiple related systems or support complete through processing automatically, without human intervention. BPM allows you to automate tasks involving information from multiple systems with rules to define the sequence in which the tasks are performed, as well as responsibilities, conditions and other aspects of the process. BPM not only allows a business process to be executed more efficiently, it also provides the tools to allow you to measure performance and identify opportunities for improvement. A benefit of BPM is that changes can be easily made in processes or flow by adding, removing or updating a process.

To best take advantage of BPM, the software application components of an Oracle process follow a Service-Oriented Architecture (SOA). These components are published as web services for reuse and ease of integration using BPEL.

10.2 Business Process Execution Language (BPEL)

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 workflow server.

To integrate a workflow process with I/PM, you must complete the following steps:

  1. Create a workflow connection (see Section 7.2, "Creating a Workflow Connection").

  2. Create an application with a workflow process defined within it (see Section 4.2, "Creating An Application").

  3. Configure workflow properties, which is part of the process to create an application in the Oracle I/PM user interface (see Section 10.2.1, "Configuring Workflow Properties").

10.2.1 Configuring Workflow Properties

A workflow process can be added to an application when the application is created, or by modifying an existing application. Adding a workflow process begins with the Application Workflow Configuration Page. Before configuring an application to use a workflow, you must ensure that a connection to a workflow server has been created and the required workflow component is available on the server. The workflow server connection must include a name, protocol, server, and port (for example, name=t3://sta00319:7001). Then when creating an application, select the workflow connection on the Workflow Server Properties Page. Oracle I/PM must authenticate with the server to discover the deployed workflow components.

Once a server connection is selected for the application, a list of workflow components is identified. A workflow component can provide many different services, so you must identify the service you want to use on the Workflow 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 the workflow. 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. A workflow 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 Workflow Payload Properties Page, the payload type and a list of allowed values are displayed which are called mapping functions. Workflow 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. Workflow Payload Mapping Functions

The Workflow Payload Properties Page is used to map Oracle I/PM application metadata fields to elements within a workflow process service payload. Predefined mapping functions are associated with simple typed elements in the payload. At runtime, when a document is created and the workflow agent is triggered to create a workflow 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 BPEL schema types and their compatible mapping functions:

BPEL Schema Types Mapping Function
string, normalizedString, token All Functions

All Field Values

anyType All Functions

All Field Values

anyUri DocUrl


Format Value










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





Format Value

Number Field Values




Create Date

Modify Date

Volume Date

Format Value

DateField Values

Boolean True


Boolean Field Values

Supporting Content Format Value
All other schema types Format Value

The following table lists the available specific payload BPM schema types and their compatible mapping functions:

BPM Argument BPM Schema Types Mapping Function
String string All Functions

All Field Values

Int int

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





Format Value

Number Field Values

Bool boolean True


Boolean Field Values

Real double Format Value
Decimal decimal Format Value

Decimal Field Values

Time dateTime Create Date

Modify Date

Volume Date

Format Value

DateField Values

Interval duration Format Value
Binary base64binary 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 workflow 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. Required Payload Element (MinOccurs) Handling

Workflow 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 Workflow 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 workflow 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 workflow 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 workflow 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.


In the workflow payload, Oracle I/PM does not support types where the minOccurs or maxOccurs attributes are greater than one. Date Field Format

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). Doc Property Functions

Document property functions assign the value of a system property of the document to a payload element. Document Id, Application Name, Create Date, etc. Field Value Functions

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 Workflow 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 Function

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 Workflow Payload Properties Page by 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 at the top provides the available mapping functions, which can 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 workflow 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] Supporting Content Function

The Supporting Content function maps supporting content data associated with a document to a workflow process payload element. Supporting content can be mapped to any complex node within the process payload. When the supporting content function is mapped, a supporting content key and XPath parameter are both required. The supporting content key is used to associate the XML content with the document and is limited to 30 characters. The XPath expression identifies the node within the XML content to be mapped to the payload element and is limited to 224 characters.

When mapping to a complex payload element at runtime, the supporting content is treated as a mapping of elements into the payload complex element rather than just copying the supporting content element in verbatim. Each element in the payload element is processed one by one. For each element, a matching element sought in the supporting content, starting at the node identified by the XPath parameter. If a match is found, the value of the matching element in the XML is assigned to payload element. Processing the supporting content avoids namespace conflict issues between the supporting content XML and the payload XML.

Supporting content can also be assigned to an anyType node in the payload. When mapped this way, the supporting content identified by the XPath is copied into the anyType element. When used this way, namespace prefixes should be avoided in the supporting content because the namespaces may not be defined correctly in the payload.

10.2.2 Payload Limitations

In general, the workflow payload mapping can handle payloads containing nesting of complex types. However, there are of number of standard XSD constructs that it cannot handle. Workflow process service payload definitions containing 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 (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.

10.2.3 Mapping Secure Workflow Services

When the Workflow 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 workflow configuration such that the client-side policy is also used. These additional configuration parameters are provided on the Workflow Payload Properties Page with the normal workflow 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 with the policy name. 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 Configuring Message Protection Policies

When configuring message protection policies, the proper credentials and certificates must also be configured to support encryption of the message. In default installations, the exact keys required are defined in the jps-config.xml file located in the $DOMAIN_HOME/config/fmwconfig directory. This file also defines the location of the default keystore file. The jps-config.xml file is generally configured to look for this file in the fmwconfig directory with the file name default-keystore.jks. However, this file does not exist by default and must be provided. The default jps-config.xml file defines the following:

Description Policies
keystore-csf-key Provides the credentials for opening the keystore file. Only the password portion of the credential is used.
enc-csf-key Provides the credentials for accessing the encryption certificate within the keystore used to encrypt the message.
sign-csf-key Provides the credentials for accessing the certificate used to sign the message. Note that the jps-config.xml file may be configured to use the enc-csf-key for both encryption and signing. In such a case the sign-csf-key is not necessary but does not cause a problem if defined.

For more information on setting up keystores, CSF keys and aliases for Oracle Web Services Manager, see Oracle Web Services Manager Administrator's Guide. Configuring SAML Policies

The user used to connect to a workflow for a SAML policy is provided by the "basic.credential" CSF key value. In order for the server to be allowed to authenticate as the user provided by the CSF key, the following policy grant must be issued from WebLogic Scripting Tool (WLST), where MW_HOME is the correct path to the installations Oracle Fusion Middleware Home directory:


10.2.4 Changing WebLogic Server Work Manager Settings

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 workflow agents and for increasing or decreasing their load on the system. On a new installation, the workflow agent is assigned 20 threads. You can reconfigure how many threads WebLogic server (WLS) should provide to the input and workflow agents by changing the default settings of the WLS work managers WorkflowAgentMaxThreadsConstraint (default 20) to match your system needs. The number of maximum threads should be adjusted equally on all systems to avoid one machine falling behind and creating a backlog. A value of -1 or 0 disables the constraint. Values above 1 constrain the number of threads to the specified number.

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.

  1. Open the WebLogic Server console and click Deployments.

  2. Select the Imaging deployment to display the details for Oracle I/PM.

  3. Click the Configuration tab and then the Workload tab to display the Work Manager list.

  4. Select the agent you want to adjust, such as WorkflowAgent.

  5. Select the Max Threads Constraint.

  6. Update the count to the new maximum thread count and click Save.

  7. Restart the managed server or servers and the new thread count will be in effect.

10.2.5 Using a Workflow Connection CSF Credential

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 Section 7.2.2, "Configuring a Workflow Connection CSF Credential."

10.2.6 Workflow Agent Retry Sequence

If the workflow agent cannot connect to the workflow 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 workflow 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.

10.2.7 Configuring the Workflow Faults Table

Workflow 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 workflow diagnostic commands are available using WLST:

  • sumIPMWorkflowFaults: Counts processing failures during workflow agent processing, grouped by choice of date, application ID, or batch ID.

  • clearIPMWorkflowFaults: Clears processing failures that occurred during workflow agent processing.

  • listIPMWorkflowFaults: Provides details of processing failures that occurred during workflow agent processing.

  • repairIPMWorkflowFaults: Repairs processing failures that occurred during workflow agent processing.

Details about use and syntax of these faults can be found in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

10.2.8 Initiating a Workflow Process Instance

Once a user has configured all of the workflow properties, they are ready to be used to initiate workflow processes. When a document is uploaded to Oracle I/PM, a message is sent to the workflow agent indicating new content. The workflow agent monitors these messages, and when it receives a message that the document's application has been configured to use workflow, it uses the configuration to build a payload of values for that specific document and then calls the service to initiate a workflow process.

The workflow 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 workflow 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 workflow 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.


A document can be resubmitted to a workflow using WebLogic Scripting Tools by calling the submitIPMToWorkflow() WLST command. A confirmation message is displayed stating that the document has been submitted, however if the document is stored in an application that is not configured with a workflow, no action is taken.