Create Human Workflow Rules using the Java API

The worklist application is the out of the box user interface of the human workflow engine. It allows users to view their pending tasks and work on them with the help of custom ADF Views. One important additional feature of the worklist application is the possibility to define rules that change automatically the task assignment if some conditions are met.

There are some cases in which it is better to create these rules automatically without user interaction because they are too complex or the worklist application has been replaced by a custom user interface. For these scenarios it is possible to use the User Metadata Java API that Oracle provides. In these Blog I am going to show how to use this API to define rules.

1. Setting up the project.

Accessing and using the User Metadata API requires some additional Java libraries. The following picture shows which one are needed in JDeveloper 12.2.1

2. Using the Java API

The User Metadata API usage is very similar to the TaskServer API and the TaskQuery Service API. Following steps are required in order to create a rule:

  • Get UserMetadata reference
  • Authenticate WorkflowServiceClient
  • Create JAXB objects
  • Create rule basic information
  • Create rule owner
  • Create target user (Optional)
  • Create the rule condition

2.1 Getting a reference to the UserMetadata

The UserMetadata Object is accessed through the WorkflowService Factory:

2.2 Authenticate the WorkflowServiceClient

Only authenticated users are allowed to create rules through the WorkflowService client. Therefore it is necessary to authenticate the IWorkflowServiceClient client form step 2.1 in order to obtain a secure context.

2.3 Create JAXB Objects

The UserMetadata rules are created using JAXB objects. These objects have to be instantiated using a JAXB Object Factory ( The ‘new’ keyword cannot be used to instatiate these objects.

2.4 Create the rule basic information

The rule contains basic information like the name, description and the dates in which it is valid

2.5 Create rule owner

Rules cannot exist alone. They have to belong to a user (or a group). The user will be the rule’s owner, and his rules will always be evaluated every time a task is assigned to him.

2.6 Create target user (Optional)

You will need to create a target user if you want to create a reassign/delegate rule. The target user is the one that will get the task if the conditions of the rule are met. NOOP rules don’t need a target; they just override the rules with lower priority. (

2.7 Create the rule condition

The last step involves creating the rule conditions. These conditions determine when the rule should be fired. In this case I will evaluate if the textAttribute19 has the value ‚Confidential‘ assign to it. Other attributes like the title, description and creation date can be used in combination with logical operations such as AND, OR and NOT.


The steps described above show how to create a UserMetadata rule programmatically. This steps can be applied to both  SOA 12c and 11g installations. The HumanWorkflow also provides a Webservice (http://host:port/integration/services/UserMetadataService/UserMetadataService?WSDL) interface for non-java clients where they can create these rules.