The new and shiny query API

Many people will agree with me that starting with jBPM3 was hard at some points. The operations offered by the engine could cover every use case, but it tended to grow cumbersome. Power-users quickly switched to writing complex Hibernate queries to get the job done quickly. However this led to several problems:

• One had to know the complete jBPM data model to write these queries. Learning curve++.
• It was hard for the jBPM team to introduce new features that broke compatibility, since many (important) customers relied on their custom queries.
• jBPM was regarded by some as too low-level and thus rejected.

But, grief no more.

The new API has been enhanced with a query system that will cover most of the queries you can think of. Developers who have to write company-specific query can still rely on Hibernate. But for most people out there, the query API will be more then suffice.

Queries can be written in a unified way on all major jBPM concepts: Process Instances, Tasks, Deployments, Historical processes, … For example:

List<ProcessInstance> results = executionService.createProcessInstanceQuery()
.processDefinitionId(“my_process_definition”)
.notSuspended()
.page(0, 50)
.list();

Gives all the process instances of the given process definition which are not suspended. Oh yeah, the result is also paged. Pretty neat, isn’t it? Querying tasks is done in completely the same way:

List<Task> myTasks = taskService.createTaskQuery()
.processInstanceId(piId)
.assignee(“Joram”)
.page(100, 120)
.orderDesc(TaskQuery.PROPERTY_DUEDATE)
.list();

This query will give me all the tasks for a given process instance assigned to me, paged of course, in a descending order based on the duedate.

Conclusion: Those unreadable and unmaintainable Hibernate queries can be forever banished to the nighmare realm. The query API is powerful and easy to understand. The steep learning curve of jBPM3 has been lowered significantly by this new API component. And we can now change the datamodel internally, without breaking the queries. What’s there not to like?