Searching BPM tasks by payload content: Flex Fields (Mapped Attributes)

Searching BPM tasks by payload content: Flex Fields (Mapped Attributes)

By Pau Garcia on Jan 03, 2013

Overview

Currently in Oracle BPM version 11gR1, the Workflow Services Java API does not allow to perform searches of BPM tasks by its payload content. This post describes the procesdure to enable this by using Flex Fields.

Introduction to Flex Fields

The way to store searchable information within the task payload is by using Flex Fields (Mapped Attributes in Fusion Middleware 11gR1 PS4). Mapped flex field attributes allow payload values to be displayed as columns in the task Data Association component, rather than being hidden in the task details. Storing custom attributes in flex fields provides the following benefits:

· They can be displayed as a column in the task Data Association component

· They can be used to filter tasks in custom views and advanced searches

· They can be used for a keyword-based search (Workspace and API)

Only top-level simple type attributes in the payload can be promoted to a flex field. Complex attributes or simple types nested inside a complex attribute are not supported.

Flex fields are defined in the Business Process Workspace after the process is deployed. Only those instances generated after the flex fields were created will reflect the correct flex fields. Older instances of the business process do not reflect subsequent flex field changes.

There are two types of mapped attributes: Public and Protected. Public Flex Fields behavior is defined in Process Activities while Protected Flex Fields are defined in Human Tasks as mappings to other elements (task payload, i.e.).

Public and Protected Flex Fields have a very similar behavior: both types of fields can change during the life of the process and can have different assignments for each task. The main difference is how their values are assigned: Public Flex Fields values are assigned in the BPM Process Activity with data associations or transformations and Private Flex Fields are mapped in the SOA Human Task definition.

Flex fields are stored inside the element systemMessageAttributes. The following piece of Workflow Task payload shows how Flex Fields are stored:

<...>

<systemMessageAttributes>

<textAttribute1>1</textAttribute1>

<textAttribute2>11</textAttribute2>

<protectedTextAttribute1>111</protectedTextAttribute1>

<flexfieldMappings>

<attributeLabel>Salary</attributeLabel>

<flexfield>ProtectedTextAttribute1</flexfield>

<description/>

</flexfieldMappings>

<flexfieldMappings>

<attributeLabel>Country</attributeLabel>

<flexfield>TextAttribute2</flexfield>

<description/>

</flexfieldMappings>

<flexfieldMappings>

<attributeLabel>Manager</attributeLabel>

<flexfield>TextAttribute1</flexfield>

<description/>

</flexfieldMappings>

</systemMessageAttributes>

<...>

Public Flex Fields

 These mappings can be changed at any time, and must be re-created when a task component is redeployed. There exist the following attributes:

Name	Description
TextAttribute1 - TextAttribute20	Stores text data, up to 2000 characters. The content in these fields is checked during keyword searches in the Worklist Application and through the task-query service.
FormAttribute1 - FormAttribute10	Stores text data, up to 2000 characters. The content in these fields is not checked during keyword searches in the Worklist Application.
URLAttribute1 - URLAttribute10	Stores text data, up to 200 characters. The content in these fields is not checked during keyword searches in the Worklist Application.
DateAttribute1 - DateAttribute10	Stores date information.
NumberAttribute1 - NumberAttribute10	Stores number information.

Creating a public Flex Field

Following is the process to create a public flex field:

1. With JDeveloper, create a string parameter in the tasks where the flex field is needed.

2. Open the Business Process Workspace with administrator rights and select the Administration option. You will see the Flex Fields menu option as shown in the figure:

3.   Select Public Flex Fields and create a new one. Once created, assign it to the desired Human Tasks by selecting “Edit mappings by task type” and choosing the task:

4.  For each task, map the Flex Field to the corresponding string parameter of the human task:

5.  Check that the Flex Field has been mapped to the corresponding tasks by selecting it:

Protected Flex Fields

The main difference compared to public flex fields is that protected flex fields cannot be changed at run time, and they are deployed along with the task component.

The following attributes are available:

Name	Description
ProtectedTextAttribute1 - ProtectedTextAttribute20	Stores text data, up to 2000 characters. The content in these fields is checked during keyword searches in the Worklist Application and through the task-query service.
ProtectedFormAttribute1 - ProtectedFormAttribute10	Stores text data, up to 2000 characters. The content in these fields is not checked during keyword searches in the Worklist Application.
ProtectedURLAttribute1 - ProtectedURLAttribute10	Stores text data, up to 200 characters. The content in these fields is not checked during keyword searches in the Worklist Application.
ProtectedDateAttribute1 - ProtectedDateAttribute10	Stores date information.
ProtectedNumberAttribute1 - ProtectedNumberAttribute10	Stores number information.

Creating a Protected Flex Field

Following is the process to create a protected flex field:

1. Enter into the Business Process Workspace with administrator rights and select the Administration option. You will see the Flex Fields menu option as shown in the figure:

2. Select Protected Flex Fields and create a new one

3. Select the Human Task in JDeveloper

4. Add a new Mapped Attribute in the Data section and map it to the desired payload element:

Searching by Flex Fields with the Java API

Once the Flex Field is created we can proceed to write our Java Application to search by Flex Fields by using the Workflow Services Java API. A predicate must be created depending on the type of the Flex Field:

a) for Public Flex Fields:

          Predicate predicate = new Predicate(TableConstants.WFTASK_TEXTATTRIBUTE1_COLUMN,Predicate.OP_EQ,”<ValueX>”);

b) For Protected Flex Fields:

          Predicate predicate = new Predicate(TableConstants.WFTASK_PROTECTEDTEXTATTRIBUTE1_COLUMN,Predicate.OP_EQ, “<ValueX>”);

Then, this predicate must be added to the query:

          List tasks =

              querySvc.queryTasks(ctx, queryColumns, null, //Do not query additional info

                  ITaskQueryService.AssignmentFilter.ALL, null, predicate, null, 0, 0);

Once executed the code, the variable tasks will contain those tasks which match the predicate. It means, those which contain "<ValueX>" as the first Flex Field (TEXTATTRIBUTE1 orPROTECTEDTEXTATTRIBUTE1).

Category: BPMN

Tags: api attribute bpm fields flex java mapped protected 

Permanent link to this entry 

«  List all BPM Process... |  Main |  Oracle BPM 11g Excep... »

Comments:

Hi , 
We are using complex payload with simple string inside it for Human workflow . Is there a way we can have this payload based query work for simple types nested inside a complex attribute of payload.

Posted by guest on May 31, 2013 at 06:01 AM PDT #