feat(engine): variable and process definition queries for external tasks

engine-rest/engine-rest-openapi/src/main/templates/lib/commons/external-task-query-params.ftl

@@ -136,6 +136,72 @@
       location = "query"
       type = "integer"
       format = "int64"
-      last = last
       desc = "Only include jobs with a priority lower than or equal to the given value.
-              Value must be a valid `long` value." />
+              Value must be a valid `long` value." />
+
+  <@lib.parameter
+      name = "processDefinitionKey"
+      location = "query"
+      type = "string"
+      desc = "Restrict to tasks that belong to a process definition with the given key." />
+
+  <@lib.parameter
+      name = "processDefinitionKeyIn"
+      location = "query"
+      type = "string"
+      desc = "Restrict to tasks that belong to a process definition with one of the given keys. The
+              keys need to be in a comma-separated list." />
+
+  <@lib.parameter
+      name = "processDefinitionName"
+      location = "query"
+      type = "string"
+      desc = "Restrict to tasks that belong to a process definition with the given name." />
+
+  <@lib.parameter
+      name = "processDefinitionNameLike"
+      location = "query"
+      type = "string"
+      desc = "Restrict to tasks that have a process definition name that has the parameter value as
+              a substring." />
+
+  <@lib.parameter
+      name = "variableNamesIgnoreCase"
+      location = "query"
+      type = "boolean"
+      defaultValue = "false"
+      desc = "Match all variable names in this query case-insensitively. If set
+              `variableName` and `variablename` are treated as equal." />
+
+  <@lib.parameter
+      name = "variableValuesIgnoreCase"
+      location = "query"
+      type = "boolean"
+      defaultValue = "false"
+      desc = "Match all variable values in this query case-insensitively. If set
+              `variableValue` and `variablevalue` are treated as equal." />
+
+  <@lib.parameter
+      name = "processVariables"
+      location = "query"
+      type = "string"
+      last = last
+      desc = "Only include tasks that belong to process instances that have variables with certain
+              values. Variable filtering expressions are comma-separated and are structured as
+              follows:
+
+              A valid parameter value has the form `key_operator_value`. `key` is the variable name,
+              `operator` is the comparison operator to be used and `value` the variable value.
+
+              **Note**: Values are always treated as String objects on server side.
+
+              Valid `operator` values are:
+              `eq` - equal to;
+              `neq` - not equal to;
+              `gt` - greater than;
+              `gteq` - greater than or equal to;
+              `lt` - lower than;
+              `lteq` - lower than or equal to;
+              `like`;
+              `notLike`.
+              `key` and `value` may not contain underscore or comma characters." />

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/runtime/externaltask/ExternalTaskQueryDto.ftl

@@ -127,6 +127,64 @@
       desc = "Only include jobs with a priority lower than or equal to the given value.
               Value must be a valid `long` value." />
 
+  <@lib.property
+      name = "processDefinitionKey"
+      type = "string"
+      desc = "Restrict to tasks that belong to a process definition with the given key." />
+
+  <@lib.property
+      name = "processDefinitionKeyIn"
+      type = "array"
+      itemType = "string"
+      desc = "Restrict to tasks that belong to a process definition with one of the given keys. The
+                keys need to be in a comma-separated list." />
+
+  <@lib.property
+      name = "processDefinitionName"
+      type = "string"
+      desc = "Restrict to tasks that belong to a process definition with the given name." />
+
+  <@lib.property
+      name = "processDefinitionNameLike"
+      type = "string"
+      desc = "Restrict to tasks that have a process definition name that has the parameter value as
+                a substring." />
+
+  <@lib.property
+      name = "variableNamesIgnoreCase"
+      type = "boolean"
+      defaultValue = "false"
+      desc = "Match all variable names in this query case-insensitively. If set
+                `variableName` and `variablename` are treated as equal." />
+
+  <@lib.property
+      name = "variableValuesIgnoreCase"
+      type = "boolean"
+      defaultValue = "false"
+      desc = "Match all variable values in this query case-insensitively. If set
+                `variableValue` and `variablevalue` are treated as equal." />
+
+  <@lib.property
+      name = "processVariables"
+      type = "array"
+      dto = "VariableQueryParameterDto"
+      desc = "A JSON array to only include tasks that belong to a process instance with variables
+              with certain values. The array consists of JSON objects with three properties
+              `name`, `operator` and `value`. `name` is the variable name, `operator` is the
+              comparison operator to be used and `value` the variable value. `value` may be of
+              type `String`, `Number` or `Boolean`.
+
+              Valid `operator` values are:
+              `eq` - equal to;
+              `neq` - not equal to;
+              `gt` - greater than;
+              `gteq` - greater than or equal to;
+              `lt` - lower than;
+              `lteq` - lower than or equal to;
+              `like`;
+              `notLike`.
+              `key` and `value` may not contain underscore or comma characters." />
+
   "sorting": {
     "type": "array",
     "nullable": true,

engine-rest/engine-rest/src/main/java/org/camunda/bpm/engine/rest/dto/externaltask/ExternalTaskQueryDto.java

@@ -23,15 +23,15 @@
 import java.util.Set;
 import java.util.function.Consumer;
 import javax.ws.rs.core.MultivaluedMap;
+import javax.ws.rs.core.Response;
+
 import org.camunda.bpm.engine.ProcessEngine;
 import org.camunda.bpm.engine.externaltask.ExternalTaskQuery;
 import org.camunda.bpm.engine.rest.dto.AbstractQueryDto;
 import org.camunda.bpm.engine.rest.dto.CamundaQueryParam;
-import org.camunda.bpm.engine.rest.dto.converter.BooleanConverter;
-import org.camunda.bpm.engine.rest.dto.converter.DateConverter;
-import org.camunda.bpm.engine.rest.dto.converter.LongConverter;
-import org.camunda.bpm.engine.rest.dto.converter.StringListConverter;
-import org.camunda.bpm.engine.rest.dto.converter.StringSetConverter;
+import org.camunda.bpm.engine.rest.dto.VariableQueryParameterDto;
+import org.camunda.bpm.engine.rest.dto.converter.*;
+import org.camunda.bpm.engine.rest.exception.InvalidRequestException;
 
 /**
  * @author Thorben Lindhauer
@@ -62,7 +62,11 @@ public class ExternalTaskQueryDto extends AbstractQueryDto<ExternalTaskQuery> {
   protected String executionId;
   protected String processInstanceId;
   protected List<String> processInstanceIdIn;
+  protected String processDefinitionKey;
+  protected String[] processDefinitionKeyIn;
   protected String processDefinitionId;
+  protected String processDefinitionName;
+  protected String processDefinitionNameLike;
   protected Boolean active;
   protected Boolean suspended;
   protected Boolean withRetriesLeft;
@@ -71,6 +75,10 @@ public class ExternalTaskQueryDto extends AbstractQueryDto<ExternalTaskQuery> {
   protected List<String> tenantIds;
   protected Long priorityHigherThanOrEquals;
   protected Long priorityLowerThanOrEquals;
+  protected Boolean variableNamesIgnoreCase;
+  protected Boolean variableValuesIgnoreCase;
+
+  private List<VariableQueryParameterDto> processVariables;
 
   public ExternalTaskQueryDto() {
   }
@@ -143,11 +151,31 @@ public String getProcessDefinitionId() {
     return processDefinitionId;
   }
 
+  @CamundaQueryParam("processDefinitionKey")
+  public void setProcessDefinitionKey(String processDefinitionKey) {
+    this.processDefinitionKey = processDefinitionKey;
+  }
+
+  @CamundaQueryParam(value = "processDefinitionKeyIn", converter = StringArrayConverter.class)
+  public void setProcessDefinitionKeyIn(String[] processDefinitionKeyIn) {
+    this.processDefinitionKeyIn = processDefinitionKeyIn;
+  }
+
   @CamundaQueryParam("processDefinitionId")
   public void setProcessDefinitionId(String processDefinitionId) {
     this.processDefinitionId = processDefinitionId;
   }
 
+  @CamundaQueryParam("processDefinitionName")
+  public void setProcessDefinitionName(String processDefinitionName) {
+    this.processDefinitionName = processDefinitionName;
+  }
+
+  @CamundaQueryParam("processDefinitionNameLike")
+  public void setProcessDefinitionNameLike(String processDefinitionNameLike) {
+    this.processDefinitionNameLike = processDefinitionNameLike;
+  }
+
   @CamundaQueryParam(value = "active", converter = BooleanConverter.class)
   public void setActive(Boolean active) {
     this.active = active;
@@ -182,6 +210,21 @@ public void setPriorityHigherThanOrEquals(Long priorityHigherThanOrEquals) {
     this.priorityHigherThanOrEquals = priorityHigherThanOrEquals;
   }
 
+  @CamundaQueryParam(value = "variableNamesIgnoreCase", converter = BooleanConverter.class)
+  public void setVariableNamesIgnoreCase(Boolean variableNamesCaseInsensitive) {
+    this.variableNamesIgnoreCase = variableNamesCaseInsensitive;
+  }
+
+  @CamundaQueryParam(value ="variableValuesIgnoreCase", converter = BooleanConverter.class)
+  public void setVariableValuesIgnoreCase(Boolean variableValuesCaseInsensitive) {
+    this.variableValuesIgnoreCase = variableValuesCaseInsensitive;
+  }
+
+  @CamundaQueryParam(value = "processVariables", converter = VariableListConverter.class)
+  public void setProcessVariables(List<VariableQueryParameterDto> processVariables) {
+    this.processVariables = processVariables;
+  }
+
   @CamundaQueryParam(value="priorityLowerThanOrEquals", converter = LongConverter.class)
   public void setPriorityLowerThanOrEquals(Long priorityLowerThanOrEquals) {
     this.priorityLowerThanOrEquals = priorityLowerThanOrEquals;
@@ -235,9 +278,21 @@ protected void applyFilters(ExternalTaskQuery query) {
     if (processInstanceIdIn != null && !processInstanceIdIn.isEmpty()) {
       query.processInstanceIdIn(processInstanceIdIn.toArray(new String[0]));
     }
+    if (processDefinitionKey != null) {
+      query.processDefinitionKey(processDefinitionKey);
+    }
+    if (processDefinitionKeyIn != null && processDefinitionKeyIn.length > 0) {
+      query.processDefinitionKeyIn(processDefinitionKeyIn);
+    }
     if (processDefinitionId != null) {
       query.processDefinitionId(processDefinitionId);
     }
+    if (processDefinitionName != null) {
+      query.processDefinitionName(processDefinitionName);
+    }
+    if (processDefinitionNameLike != null) {
+      query.processDefinitionNameLike(processDefinitionNameLike);
+    }
     if (active != null && active) {
       query.active();
     }
@@ -256,6 +311,38 @@ protected void applyFilters(ExternalTaskQuery query) {
     if (noRetriesLeft != null && noRetriesLeft) {
       query.noRetriesLeft();
     }
+    if(variableValuesIgnoreCase != null && variableValuesIgnoreCase) {
+      query.matchVariableValuesIgnoreCase();
+    }
+    if(variableNamesIgnoreCase != null && variableNamesIgnoreCase) {
+      query.matchVariableNamesIgnoreCase();
+    }
+    if (processVariables != null) {
+      for (VariableQueryParameterDto variableQueryParam : processVariables) {
+        String variableName = variableQueryParam.getName();
+        String op = variableQueryParam.getOperator();
+        Object variableValue = variableQueryParam.resolveValue(objectMapper);
+        if (op.equals(VariableQueryParameterDto.EQUALS_OPERATOR_NAME)) {
+          query.processVariableValueEquals(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.NOT_EQUALS_OPERATOR_NAME)) {
+          query.processVariableValueNotEquals(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.GREATER_THAN_OPERATOR_NAME)) {
+          query.processVariableValueGreaterThan(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.GREATER_THAN_OR_EQUALS_OPERATOR_NAME)) {
+          query.processVariableValueGreaterThanOrEquals(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.LESS_THAN_OPERATOR_NAME)) {
+          query.processVariableValueLessThan(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.LESS_THAN_OR_EQUALS_OPERATOR_NAME)) {
+          query.processVariableValueLessThanOrEquals(variableName, variableValue);
+        } else if (op.equals(VariableQueryParameterDto.LIKE_OPERATOR_NAME)) {
+          query.processVariableValueLike(variableName, String.valueOf(variableValue));
+        } else if (op.equals(VariableQueryParameterDto.NOT_LIKE_OPERATOR_NAME)) {
+          query.processVariableValueNotLike(variableName, String.valueOf(variableValue));
+        } else {
+          throw new InvalidRequestException(Response.Status.BAD_REQUEST, "Invalid process variable comparator specified: " + op);
+        }
+      }
+    }
     if (workerId != null) {
       query.workerId(workerId);
     }