feat(openapi): add history cleanup endpoints

* Add all of the History Cleanup endpoints; * Add the OpenAPI `deprecated` flag, so that we can deprecate specific endpoints. Related to CAM-11564
tmetzke · May 4, 2021 · cdf7d95 · cdf7d95
1 parent c1a130e
commit cdf7d95
Show file tree

Hide file tree

Showing 8 changed files with 268 additions and 3 deletions.
diff --git a/engine-rest/engine-rest-openapi/src/main/templates/lib/utils.ftl b/engine-rest/engine-rest-openapi/src/main/templates/lib/utils.ftl
@@ -387,12 +387,19 @@
         id
         tag
         desc
+        deprecated = false
         summary = "" >
+
+    <#if deprecated>
+      "deprecated": true,
+    </#if>
+
     "operationId": "${id}",
     "tags": [
       "${tag}"
     ],
 
+
     <#if summary?has_content>
       "summary": "${summary}",
     </#if>

diff --git a/engine-rest/engine-rest-openapi/src/main/templates/main.ftl b/engine-rest/engine-rest-openapi/src/main/templates/main.ftl
@@ -55,6 +55,7 @@
     {"name": "Historic Job Log"},
     {"name": "Historic Process Instance"},
     {"name": "Historic Task Instance"},
+    {"name": "History Cleanup"},
     {"name": "Identity"},
     {"name": "Incident"},
     {"name": "Job"},

diff --git a/...mplates/models/org/camunda/bpm/engine/rest/dto/history/HistoryCleanupConfigurationDto.ftl b/...mplates/models/org/camunda/bpm/engine/rest/dto/history/HistoryCleanupConfigurationDto.ftl
@@ -0,0 +1,35 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/history/history-cleanup/get-cleanup-configuration/index.html -->
+<#macro dto_macro docsUrl="">
+<@lib.dto >
+    <#assign dateFormatDescription="By [default](${docsUrl}/reference/rest/overview/date-format/),
+                                    the date must have the format `yyyy-MM-dd'T'HH:mm:ss.SSSZ`,
+                                    e.g., `2013-01-23T14:42:45.000+0200`."
+    />
+    <@lib.property
+        name = "batchWindowStartTime"
+        type = "string"
+        format = "date-time"
+        desc = "Start time of the current or next batch window. ${dateFormatDescription}"
+    />
+
+    <@lib.property
+        name = "batchWindowEndTime"
+        type = "string"
+        format = "date-time"
+        desc = "End time of the current or next batch window. ${dateFormatDescription}"
+    />
+
+    <@lib.property
+        name = "enabled"
+        type = "boolean"
+        desc = "Indicates whether the engine node participates in history cleanup or
+                not. The default is `true`. Participation can be disabled via
+                [Process Engine Configuration](${docsUrl}/reference/deployment-descriptors/tags/process-engine/#history-cleanup-enabled).
+
+                For more details, see
+                [Cleanup Execution Participation per Node](${docsUrl}/user-guide/process-engine/history/#cleanup-execution-participation-per-node)."
+        last = true
+    />
+
+</@lib.dto>
+</#macro>
diff --git a/...e-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/configuration/get.ftl b/...e-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/configuration/get.ftl
@@ -0,0 +1,33 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/history/history-cleanup/get-cleanup-configuration/index.html -->
+<#macro endpoint_macro docsUrl="">
+{
+  <@lib.endpointInfo
+      id = "getHistoryCleanupConfiguration"
+      tag = "History Cleanup"
+      summary = "Get History Cleanup Configuration"
+      desc = "Retrieves history cleanup batch window configuration (See
+              [History cleanup](${docsUrl}/user-guide/process-engine/history/#history-cleanup))."
+  />
+
+  "responses": {
+
+    <@lib.response
+        code = "200"
+        dto = "HistoryCleanupConfigurationDto"
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/history/cleanup/configuration`",
+                       "description": "GET `/history/cleanup/configuration`",
+                       "value": {
+                         "batchWindowStartTime": "2017-09-11T23:59:00.000+0200",
+                         "batchWindowEndTime": "2017-09-12T02:00:00.000+0200",
+                         "enabled": "true"
+                       }
+                     }']
+        last = true
+    />
+
+  }
+
+}
+</#macro>
diff --git a/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/job/get.ftl b/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/job/get.ftl
@@ -0,0 +1,52 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/history/history-cleanup/get-history-cleanup-job/index.html -->
+<#macro endpoint_macro docsUrl="">
+{
+  <@lib.endpointInfo
+      id = "findCleanupJob"
+      tag = "History Cleanup"
+      deprecated = true
+      summary = "Find clean up history job (GET)"
+      desc = "**Deprecated!** Use `GET /history/cleanup/jobs` instead.
+
+              Finds history cleanup job (See
+              [History cleanup](${docsUrl}/user-guide/process-engine/history/#history-cleanup))."
+  />
+
+  "responses": {
+
+    <@lib.response
+        code = "200"
+        dto = "JobDto"
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/history/cleanup/job`",
+                       "description": "GET `/history/cleanup/job`",
+                       "value": {
+                         "id": "074bd92a-1a95-11e7-8ceb-34f39ab71d4e",
+                         "jobDefinitionId": null,
+                         "processInstanceId": null,
+                         "processDefinitionId": null,
+                         "processDefinitionKey": null,
+                         "executionId": null,
+                         "exceptionMessage": null,
+                         "retries": 3,
+                         "dueDate": "2017-04-06T13:57:45.000+0200",
+                         "suspended": false,
+                         "priority": 0,
+                         "tenantId": null,
+                         "createTime": "2017-05-05T17:00:00+0200"
+                       }
+                     }']
+    />
+
+    <@lib.response
+        code = "404"
+        dto = "ExceptionDto"
+        desc = "History clean up job does not exist."
+        last = true
+    />
+
+  }
+
+}
+</#macro>
diff --git a/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/jobs/get.ftl b/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/jobs/get.ftl
@@ -0,0 +1,67 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/history/history-cleanup/get-history-cleanup-jobs/index.html -->
+<#macro endpoint_macro docsUrl="">
+{
+  <@lib.endpointInfo
+      id = "findCleanupJobs"
+      tag = "History Cleanup"
+      summary = "Find clean up history jobs (GET)"
+      desc = "Finds history cleanup jobs (See
+              [History cleanup](${docsUrl}/user-guide/process-engine/history/#history-cleanup))."
+  />
+
+  "responses": {
+
+    <@lib.response
+        code = "200"
+        dto = "JobDto"
+        array = true
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "GET `/history/cleanup/jobs`",
+                       "description": "GET `/history/cleanup/jobs`",
+                       "value": [
+                         {
+                           "id": "aJobId",
+                           "jobDefinitionId": null,
+                           "processInstanceId": null,
+                           "processDefinitionId": null,
+                           "processDefinitionKey": null,
+                           "executionId": null,
+                           "exceptionMessage": null,
+                           "retries": 3,
+                           "dueDate": "aDueDate",
+                           "suspended": false,
+                           "priority": 0,
+                           "tenantId": null,
+                           "createTime": "2018-05-05T17:00:00+0200"
+                         },
+                         {
+                           "id": "anotherJobId",
+                           "jobDefinitionId": null,
+                           "processInstanceId": null,
+                           "processDefinitionId": null,
+                           "processDefinitionKey": null,
+                           "executionId": null,
+                           "exceptionMessage": null,
+                           "retries": 3,
+                           "dueDate": "anotherDueDate",
+                           "suspended": false,
+                           "priority": 0,
+                           "tenantId": null,
+                           "createTime": "2018-05-05T17:00:00+0200"
+                         }
+                       ]
+                     }']
+    />
+
+    <@lib.response
+        code = "404"
+        dto = "ExceptionDto"
+        desc = "History clean up jobs are empty."
+        last = true
+    />
+
+  }
+
+}
+</#macro>
diff --git a/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/post.ftl b/engine-rest/engine-rest-openapi/src/main/templates/paths/history/cleanup/post.ftl
@@ -0,0 +1,70 @@
+<#-- Generated From File: camunda-docs-manual/public/reference/rest/history/history-cleanup/post-history-cleanup/index.html -->
+<#macro endpoint_macro docsUrl="">
+{
+  <@lib.endpointInfo
+      id = "cleanupAsync"
+      tag = "History Cleanup"
+      summary = "Clean up history (POST)"
+      desc = "Schedules asynchronous history cleanup (See
+              [History cleanup](${docsUrl}/user-guide/process-engine/history/#history-cleanup)).
+
+              **Note:** This endpoint will return at most a single history cleanup job.
+              Since version `7.9.0` it is possible to configure multiple
+              [parallel history cleanup jobs](${docsUrl}/user-guide/process-engine/history/#parallel-execution). Use
+              [`GET /history/cleanup/jobs`](${docsUrl}/reference/rest/history/history-cleanup/get-history-cleanup-jobs)
+              to find all the available history cleanup jobs."
+  />
+
+  "parameters" : [
+
+      <@lib.parameter
+          name = "immediatelyDue"
+          location = "query"
+          type = "boolean"
+          desc = "When true the job will be scheduled for nearest future. When `false`, the job will be
+                  scheduled for next batch window start time. Default is `true`."
+          last = true
+      />
+
+  ],
+
+  "responses": {
+
+    <@lib.response
+        code = "200"
+        dto = "JobDto"
+        desc = "Request successful."
+        examples = ['"example-1": {
+                       "summary": "POST `/history/cleanup?immediatelyDue=false`",
+                       "description": "POST `/history/cleanup?immediatelyDue=false`",
+                       "value": {
+                         "id": "074bd92a-1a95-11e7-8ceb-34f39ab71d4e",
+                         "jobDefinitionId": null,
+                         "processInstanceId": null,
+                         "processDefinitionId": null,
+                         "processDefinitionKey": null,
+                         "executionId": null,
+                         "exceptionMessage": null,
+                         "retries": 3,
+                         "dueDate": "2017-04-06T13:57:45.000+0200",
+                         "suspended": false,
+                         "priority": 0,
+                         "tenantId": null,
+                         "createTime": "2017-04-01T09:45:15.039+0100"
+                       }
+                     }']
+    />
+
+    <@lib.response
+        code = "400"
+        dto = "ExceptionDto"
+        desc = "Returned if some of the query parameters are invalid or the engine
+                does not participate in history cleanup. See
+                [Cleanup Execution Participation per Node](${docsUrl}/user-guide/process-engine/history/#cleanup-execution-participation-per-node)."
+        last = true
+    />
+
+  }
+
+}
+</#macro>
diff --git a/engine/src/main/java/org/camunda/bpm/engine/HistoryService.java b/engine/src/main/java/org/camunda/bpm/engine/HistoryService.java
@@ -349,14 +349,14 @@ public interface HistoryService {
   /**
    * Finds history cleanup job, if present.
    * @deprecated As of v. 7.9.0, because there can be more than one history cleanup job at once, use {@link #findHistoryCleanupJobs} instead.
-   * @return job entity
+   * @return history cleanup job entity
    */
   @Deprecated
   Job findHistoryCleanupJob();
 
   /**
-   * Finds history cleanup job if present.
-   * @return job entity
+   * Finds history cleanup jobs if present.
+   * @return history cleanup job entities
    */
   List<Job> findHistoryCleanupJobs();