feat(openapi): add historic detail endpoints

Related to CAM-11560

engine-rest/engine-rest-openapi/src/main/templates/lib/commons/history-detail-query-params.ftl

@@ -0,0 +1,108 @@
+<#assign sortByValues = [
+  '"processInstanceId"',
+  '"variableName"',
+  '"variableType"',
+  '"variableRevision"',
+  '"formPropertyId"',
+  '"time"',
+  '"occurrence"',
+  '"tenantId"'
+]>
+
+<#assign dateFormatDescription = "Default [format](${docsUrl}/reference/rest/overview/date-format/)
+                                  `yyyy-MM-dd'T'HH:mm:ss.SSSZ`, e.g., 2013-01-23T14:42:45.000+0200."/>
+<#if requestMethod == "GET">
+    <#assign listType = "comma-separated">
+<#elseif requestMethod == "POST">
+    <#assign listType = "">
+</#if>
+
+<#assign params = {
+  "processInstanceId": {
+    "type": "string",
+    "desc": "Filter by process instance id."
+  },
+  "processInstanceIdIn": {
+    "type": "array",
+    "itemType": "string",
+    "desc": "Only include historic details which belong to one of the passed ${listType} process instance ids."
+  },
+  "executionId": {
+    "type": "string",
+    "desc": "Filter by execution id."
+  },
+  "taskId": {
+    "type": "string",
+    "desc": "Filter by task id."
+  },
+  "activityInstanceId": {
+    "type": "string",
+    "desc": "Filter by activity instance id."
+  },
+  "caseInstanceId": {
+    "type": "string",
+    "desc": "Filter by case instance id."
+  },
+  "caseExecutionId": {
+    "type": "string",
+    "desc": "Filter by case execution id."
+  },
+  "variableInstanceId": {
+    "type": "string",
+    "desc": "Filter by variable instance id."
+  },
+  "variableTypeIn": {
+    "type": "array",
+    "itemType": "string",
+    "desc": "Only include historic details where the variable updates belong to one of the passed ${listType}
+             list of variable types. A list of all supported variable types can be found
+             [here](${docsUrl}/user-guide/process-engine/variables/#supported-variable-values).
+             **Note:** All non-primitive variables are associated with the type `serializable`."
+  },
+  "tenantIdIn": {
+    "type": "array",
+    "itemType": "string",
+    "desc": "Filter by a ${listType} list of tenant ids."
+  },
+  "withoutTenantId": {
+    "type": "boolean",
+    "desc": "Only include historic details that belong to no tenant. Value may only be
+             `true`, as `false` is the default behavior."
+  },
+  "userOperationId": {
+    "type": "string",
+    "desc": "Filter by a user operation id."
+  },
+  "formFields": {
+    "type": "boolean",
+    "desc": "Only include `HistoricFormFields`. Value may only be `true`, as `false` is the default behavior."
+  },
+  "variableUpdates": {
+    "type": "boolean",
+    "desc": "Only include `HistoricVariableUpdates`. Value may only be `true`, as `false` is the default behavior."
+  },
+  "excludeTaskDetails": {
+    "type": "boolean",
+    "desc": "Excludes all task-related `HistoricDetails`, so only items which have no task id set will be selected.
+             When this parameter is used together with `taskId`, this call is ignored and task details are not excluded.
+             Value may only be `true`, as `false` is the default behavior."
+  },
+  "initial": {
+    "type": "boolean",
+    "desc": "Restrict to historic variable updates that contain only initial variable values.
+             Value may only be `true`, as `false` is the default behavior."
+  },
+  "occurredBefore": {
+    "type": "string",
+    "format": "date-time",
+    "desc": "Restrict to historic details that occured before the given date (including the date).
+             ${dateFormatDescription}"
+  },
+  "occurredAfter": {
+    "type": "string",
+    "format": "date-time",
+    "desc": "Restrict to historic details that occured after the given date (including the date).
+             ${dateFormatDescription}"
+  }
+}
+/>

engine-rest/engine-rest-openapi/src/main/templates/main.ftl

@@ -52,6 +52,7 @@
     {"name": "Historic Decision Definition"},
     {"name": "Historic Decision Instance"},
     {"name": "Historic Decision Requirements Definition"},
+    {"name": "Historic Detail"},
     {"name": "Historic External Task Log"},
     {"name": "Historic Incident"},
     {"name": "Historic Job Log"},

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/history/HistoricDetailDto.ftl

@@ -0,0 +1,216 @@
+<#macro dto_macro docsUrl="">
+  <@lib.dto >
+    <#assign
+        dateFormatDescription = "Default [format](${docsUrl}/reference/rest/overview/date-format/)
+                                 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`."
+    />
+    <#assign
+        noteHistoricFormFiled = "**Note:** This property is only set for a `HistoricVariableUpdate` historic details.
+                                 In these cases, the value of the `type` property is `formField`."
+    />
+    <#assign
+        noteHistoricVariableUpdate = "**Note:** This property is only set for a `HistoricVariableUpdate` historic details.
+                                 In these cases, the value of the `type` property is `variableUpdate`."
+    />
+
+    <@lib.property
+        name = "id"
+        type = "string"
+        desc = "The id of the historic detail."
+    />
+
+    <@lib.property
+        name = "type"
+        type = "string"
+        desc = "The type of the historic detail. Either `formField` for a submitted form field
+                value or `variableUpdate` for variable updates."
+    />
+
+    <@lib.property
+        name = "processDefinitionKey"
+        type = "string"
+        desc = "The key of the process definition that this historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "processDefinitionId"
+        type = "string"
+        desc = "The id of the process definition that this historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "processInstanceId"
+        type = "string"
+        desc = "The id of the process instance the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "activityInstanceId"
+        type = "string"
+        desc = "The id of the activity instance the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "executionId"
+        type = "string"
+        desc = "The id of the execution the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "caseDefinitionKey"
+        type = "string"
+        desc = "The key of the case definition that this historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "caseDefinitionId"
+        type = "string"
+        desc = "The id of the case definition that this historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "caseInstanceId"
+        type = "string"
+        desc = "The id of the case instance the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "caseExecutionId"
+        type = "string"
+        desc = "The id of the case execution the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "taskId"
+        type = "string"
+        desc = "The id of the task the historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "tenantId"
+        type = "string"
+        desc = "The id of the tenant that this historic detail belongs to."
+    />
+
+    <@lib.property
+        name = "userOperationId"
+        type = "string"
+        desc = "The id of user operation which links historic detail with
+                [user operation log](${docsUrl}/reference/rest/history/user-operation-log/)
+                entries."
+    />
+
+    <@lib.property
+        name = "time"
+        type = "string"
+        format = "date-time"
+        desc = "The time when this historic detail occurred. ${dateFormatDescription}"
+    />
+
+    <@lib.property
+        name = "removalTime"
+        type = "string"
+        format = "date-time"
+        desc = "The time after which the historic detail should be removed by the History Cleanup job.
+                ${dateFormatDescription}"
+    />
+
+    <@lib.property
+        name = "rootProcessInstanceId"
+        type = "string"
+        desc = "The process instance id of the root process instance that initiated the process
+                containing this historic detail."
+    />
+
+    <@lib.property
+        name = "fieldId"
+        type = "string"
+        desc = "The id of the form field.
+
+                ${noteHistoricFormFiled}"
+    />
+
+    <@lib.property
+        name = "fieldValue"
+        type = "object"
+        desc = "The submitted form field value. The value differs depending on the form field's type
+                and on the `deserializeValue` parameter.
+
+                ${noteHistoricFormFiled}"
+    />
+
+  <@lib.property
+      name = "variableName"
+      type = "string"
+      desc = "The name of the variable which has been updated.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "variableInstanceId"
+      type = "string"
+      desc = "The id of the associated variable instance.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "variableType"
+      type = "string"
+      desc = "The value type of the variable.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "value"
+      type = "object"
+      desc = "The variable's value. Value differs depending on the variable's type
+              and on the deserializeValues parameter.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "valueInfo"
+      type = "object"
+      addProperty = "\"additionalProperties\": true"
+      desc = "A JSON object containing additional, value-type-dependent properties.
+              For variables of type `Object`, the following properties are returned:
+
+              * `objectTypeName`: A string representation of the object's type name.
+              * `serializationDataFormat`: The serialization format used to store the variable.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "initial"
+      type = "boolean"
+      desc = "Returns `true` for variable updates that contains the initial values of the variables.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "revision"
+      type = "integer"
+      format = "int32"
+      desc = "The revision of the historic variable update.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+  <@lib.property
+      name = "errorMessage"
+      type = "string"
+      last = true
+      desc = "An error message in case a Java Serialized Object
+              could not be de-serialized.
+
+              ${noteHistoricVariableUpdate}"
+  />
+
+</@lib.dto>
+</#macro>

engine-rest/engine-rest-openapi/src/main/templates/models/org/camunda/bpm/engine/rest/dto/history/HistoricDetailQueryDto.ftl

@@ -0,0 +1,20 @@
+<#macro dto_macro docsUrl="">
+<@lib.dto
+    desc = "A historic detail query which defines a group of historic details." >
+
+  <#assign requestMethod="POST"/>
+  <#include "/lib/commons/history-detail-query-params.ftl" >
+  <@lib.properties params />
+  "sorting": {
+    "type": "array",
+    "description": "A JSON array of criteria to sort the result by. Each element of the array is
+                    a JSON object that specifies one ordering. The position in the array
+                    identifies the rank of an ordering, i.e., whether it is primary, secondary,
+                    etc. Does not have an effect for the `count` endpoint.",
+    "items":
+      <#assign last = true>
+      <#include "/lib/commons/sort-props.ftl">
+  }
+
+</@lib.dto>
+</#macro>