Reflect latest changes to Java API in the REST API

[zambrovski]

User Story

After updating to 7.22 I noticed that some new methods appeared in the Java API (Great! 👍). The same changes should be available via REST API.

org.camunda.bpm.engine.task.Task got additional methods:

• to read Task state
• write Task state

Workarounds

• For retrieval of the task state there is no workaround available.

[joaquinfelici]

Hello @zambrovski ,

Thank you for raising this. I understand that you would like to retrieve the taskState of a given task via the rest-api.
This is already possible through the Task Api, as seen is the documentation. In the response example, you can see the following json which contains the field taskState:

GET /task/anId Response

{
  "id": "anId",
  "name": "aName",
  "assignee": "anAssignee",
  "created": "2013-01-23T13:42:42.000+0200",
  "due": "2013-01-23T13:49:42.576+0200",
  "followUp": "2013-01-23T13:44:42.437+0200",
  "delegationState": "RESOLVED",
  "description": "aDescription",
  "executionId": "anExecution",
  "owner": "anOwner",
  "parentTaskId": "aParentId",
  "priority": 42,
  "processDefinitionId": "aProcDefId",
  "processInstanceId": "aProcInstId",
  "caseDefinitionId": "aCaseDefId",
  "caseInstanceId": "aCaseInstId",
  "caseExecutionId": "aCaseExecution",
  "taskDefinitionKey": "aTaskDefinitionKey",
  "suspended": false,
  "formKey": "aFormKey",
  "camundaFormRef": {
    "key": "aCamundaFormKey",
    "binding": "version",
    "version": 2
  },
  "tenantId": "aTenantId",
  "taskState": "aTaskState"
}

Same behavior exists for the Get List endpoint, both in GET and POST mode.

Please let me know if this is not what you meant and if you think this feature request is still required.

[zambrovski]

Hi @joaquinfelici,

If you look at the documentation carefully, you will notice that in the example the taskState is present, but in the actual response schema it is missing. Even worth, it is not only missing in the description, but is also not part of the official OpenAPI specification.

And this is exactly the bug. You pretend in the example it is there, but it is not in the specification. If you look on the class you are using to return the task (

camunda-bpm-platform/engine-rest/engine-rest/src/main/java/org/camunda/bpm/engine/rest/dto/task/TaskDto.java

Line 56 in 1e80065

private String taskState;

) you will see in in the DTO. So analyzing the cause, it has been added to the DTO and the example has been modified, but it is not a part of the OpenAPI Specification describing the response for the single/list operations of task retrieval.

Cheers,

Simon

[zambrovski]

And this is serious, because we use the official Camunda OpenAPI specification as input for the code generation of the client, capable to use that API. So there is only a limited value of having it in the implementation, but not having in in the Open API Spec.

[zambrovski]

Since you have a pretty complex procedure to generate the OpenAPI spec, I'll give you the relevant content part extracted from the published JAR:

      "TaskDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "nullable": true,
            "description": "The task id."
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "The task name."
          },
          "assignee": {
            "type": "string",
            "nullable": true,
            "description": "The assignee\u0027s id."
          },
          "owner": {
            "type": "string",
            "nullable": true,
            "description": "The owner\u0027s id."
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date the task was created on.\n[Default format](https://docs.camunda.org/manual/7.22/reference/rest/overview/date-format/)\n`yyyy-MM-dd\u0027T\u0027HH:mm:ss.SSSZ`."
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The date the task was last updated. Every action that fires a [task update event](https://docs.camunda.org/manual/7.22/user-guide/process-engine/delegation-code/#task-listener-event-lifecycle) will update this property.\n[Default format](https://docs.camunda.org/manual/7.22/reference/rest/overview/date-format/)\n`yyyy-MM-dd\u0027T\u0027HH:mm:ss.SSSZ`."
          },
          "due": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The task\u0027s due date.\n[Default format](https://docs.camunda.org/manual/7.22/reference/rest/overview/date-format/)\n`yyyy-MM-dd\u0027T\u0027HH:mm:ss.SSSZ`."
          },
          "followUp": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The follow-up date for the task.\n[Default format](https://docs.camunda.org/manual/7.22/reference/rest/overview/date-format/)\n`yyyy-MM-dd\u0027T\u0027HH:mm:ss.SSSZ`."
          },
          "delegationState": {
            "type": "string",
            "nullable": true,
            "enum": [
              "PENDING",
              "RESOLVED"
            ],
            "description": "The task\u0027s delegation state. Possible values are `PENDING` and `RESOLVED`."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The task\u0027s description."
          },
          "executionId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the execution the task belongs to."
          },
          "parentTaskId": {
            "type": "string",
            "nullable": true,
            "description": "The id the parent task, if this task is a subtask."
          },
          "priority": {
            "type": "integer",
            "format": "int32",
            "nullable": true,
            "description": "The task\u0027s priority."
          },
          "processDefinitionId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the process definition the task belongs to."
          },
          "processInstanceId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the process instance the task belongs to."
          },
          "caseExecutionId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the case execution the task belongs to."
          },
          "caseDefinitionId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the case definition the task belongs to."
          },
          "caseInstanceId": {
            "type": "string",
            "nullable": true,
            "description": "The id of the case instance the task belongs to."
          },
          "taskDefinitionKey": {
            "type": "string",
            "nullable": true,
            "description": "The task\u0027s key."
          },
          "suspended": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the task belongs to a process instance that is suspended."
          },
          "formKey": {
            "type": "string",
            "nullable": true,
            "description": "If not `null`, the form key for the task."
          },
          "camundaFormRef": {
            "$ref": "#/components/schemas/CamundaFormRef"
          },
          "tenantId": {
            "type": "string",
            "nullable": true,
            "description": "If not `null`, the tenant id of the task."
          }
        }
      },

[joaquinfelici]

Hello @zambrovski, thanks for the clarification, this field is indeed missing from the response specification. Would you be interested in raising a pull request to fix it?

[joaquinfelici]

Hello @zambrovski, following-up on this. Please let me know whether you might be interested in contributing to get this fixed when you have the chance. Thanks in advance.