How many times have you had to repeat the same sequence in the BPM workspace to map a Human Task payload attribute to a public Flex Field? Let's do a bit of re-cap:

1. login to the Workspace with administration permissions
2. go do Administration
3. go to Public Flex Fields
4. create all Labels

And then, for each human task:

1. search for the task
2. choose the payload attribute
3. search for the label to use (you can create them here as well)
4. repeat until you've mapped all the labels you need
5. save and move to the next

It seems like a lot of work to do and it is fair to say that our platform team was not very happy to do these tasks manually. Even when developing these mappings need to be re-created from time to time (more often than we wished). The whole process is furthermore error-prone, specially when moving from development to QA and to Production environments.

 Automating the creation and mapping of labels and payload atributes

Oracle BPM/SOA 11g and 12c expose an API for managing labels and mapping them as required. The oracle.bpel.services.workflow.runtimeconfig.IRuntimeConfigService interface provides a series of methods for creating and deleting labels, as well as creating oracle.bpel.services.workflow.runtimeconfig.model.PayloadMapping instances to map a label to a payload attribute.

By leveraging this API, all we need to do is use a simple format to describe our labels and how these are mapped to the corresponding payload attributes. For our tool we have chosen JSON for its simplicity. Below is an example of how a mapping file looks:

Let’s describe the file in more detail. First, we have an object called "options" which contains the "default-mapping" object, which allows us to define a mapping that can be referred to in the mapping object thus simplifying the overall configuration.

A mapping is declared as the Payload Attribute (i.e.: "employeeId") and its corresponding flex field, in this case the "employeeNumber", of type TextAttribute1.

Second, we have a delete object with a list of target flex fields. The create object lists all the flex field labels to be created, optionally with their format if needed, as shown in the above example for a Date attribute.

Finally, the map object describes how the Human Task payload attributes are mapped on to Flex Field labels. Now, because most of the time in our processes' Human Tasks we will want to map the exact same attributes, we can use the default-mapping instead of having to repeat the same for every task.

As you can see in the example, the last human task mapping uses the default mapping plus an additional one for the currentTaskId value.

Running the tool

To simplify the execution of the tool, we created a build.xml file that can either be invoked standalone or as part of a maven goal if you are using continuous integration. In our build file we have 3 targets: deleting, creating and mapping attributes to flex fields. The picture below shows a sample target for deleting existing labels:

In this case we are requesting the username and password when the build file is invoked, but these can be added to the config.properties file or passed as arguments.

Finally, the output of the tool for the sample mapping above is:

Conclusion

As shown above, automating the (re)creation and mapping of flex field labels can be quite beneficial in terms of time saving - after all, we always want to avoid doing repetitive tasks. By integrating the build file with Jenkins, for instance, you could have a project deployed and your labels created automatically in various environments.

In a future update, we will post the binaries and the instructions to run it. If you want to get your hands around the code, reach us from the contact page and we'll see what we can do!