Execute Custom queries in Activiti

(This will probably end up in the user guide of the Activiti 5.15 release, but I wanted to share it already)

The Activiti API allows for interacting with the database using a high level API. For example, for retrieving data the Query API and the Native Query API are powerful in its usage. However, for some use cases they might not be flexible enough. The following section described how a completely custom SQL statement (select, insert, updated and deletes are possible) can be executed against the Activiti data store, but completely within the configured Process Engine (and thus levering the transaction setup for example).

To define custom SQL statements, the Activiti engine leverages the capabilities of its underlying framework, MyBatis. The first thing to do when using custom SQL, is to create a MyBatis mapper class. More info can be read in the MyBatis user guide. For example, suppose that for some use case not the whole task data is needed, but only a small subset of it. A Mapper that could do this, looks as follows:

public interface MyTestMapper {

  @Select("SELECT ID_ as id, NAME_ as name, CREATE_TIME_ as createTime FROM ACT_RU_TASK")
  List<Map<String, Object>> selectTasks();


This mapper must be provided to the Process Engine configuration as follows:

<property name="customMybatisMappers">

Notice that this is an interface. The underlying MyBatis framework will make an instance of it that can be used at runtime. Also notice that the return value of the method is not typed, but a list of maps (which corresponds to the list of rows with column values). Typing is possible with the MyBatis mappers if wanted.

To execute the query above, the managementService.executeCustomSql method must be used. This method takes in a CustomSqlExecution instance. This is a wrapper that hides the internal bits of the engine otherwise needed to make it work.

Unfortunately, Java generics make it a bit less readable than it could have been. The two generic types below are the mapper class and the return type class. However, the actual logic is simply to call the mapper method and return its results (if applicable).

CustomSqlExecution<MyTestMapper, List<Map<String, Object>>> customSqlExecution =
    new AbstractCustomSqlExecution<MyTestMapper, List<Map<String, Object>>>(MyTestMapper.class) {

  public List<Map<String, Object>> execute(MyTestMapper customMapper) {
    return customMapper.selectTasks();


List<Map<String, Object>> results = managementService.executeCustomSql(customSqlExecution);

The Map entries in the list above will only contain id, name and create time in this case and not the full task object.

Any SQL is possible when using the approach above. Another more complex example:

    "SELECT task.ID_ as taskId, variable.LONG_ as variableValue FROM ACT_RU_VARIABLE variable",
    "inner join ACT_RU_TASK task on variable.TASK_ID_ = task.ID_",
    "where variable.NAME_ = #{variableName}"
  List<Map<String, Object>> selectTaskWithSpecificVariable(String variableName);

Using this method, the task table will be joined with the variables table. Only where the variable has a certain name is retained, and the task id and the corresponding numerical value is returned.

This will be possible in Activiti 5.15. However, the code (and more specifically the Command implementation and the wrapper interface) can be used in any older version of Activiti.


  1. Hugo Robayo February 25, 2014

    Dear Joram.

    I am using the Identity link feature for control purposes (auto asign of task), but the problem rises when i try to delete a identity link from Process Instance, I read in the forum (http://forums.activiti.org/content/no-delete-user-identity-link-runtime-service) that could be easily implemented but, if it possible to guide me how to do a delete of indentitylin by hand, I have activiti 5.14, and I found de class IdentityLinkManager.delete(…), how to get the reference for IdentityLinkManager and delete a row….

    Tanks in advandce for your help.



  2. Joram Barrez February 26, 2014

    Hi Hugo,

    I saw your jira issue. But the post you are referring to is for LDAP, not for the database version.

    However, you can easily create your own Activiti Command and get a reference to the identityLinkManager through the Context.

  3. Phil Mittleman August 16, 2014

    In the last example (List<Map> selectTaskWithSpecificVariable(String variableName);), how do you pass the parameter (variableName) into the execute method of the AbstractCustomSqlExecution?

  4. Anonymous August 19, 2014

    How do you mean? You can just reference java variables and pass them into the anonymous class method (if you make them final)

  5. Anonymous December 16, 2014


  6. Prvoslav Obrad Savic February 9, 2015

    Hello Joram,
    thank you for this nice tutorial on how to execute custom queries. It works great!


Leave a Reply

Your email address will not be published.