feat(camunda8): retrieve user task form by user task key

fixes #340
camunda · Jan 29, 2025 · 99e40f7 · 99e40f7
1 parent fe2abfe
commit 99e40f7
Show file tree

Hide file tree

Showing 5 changed files with 170 additions and 0 deletions.
diff --git a/src/__tests__/c8/rest/getUserTaskForm.spec.ts b/src/__tests__/c8/rest/getUserTaskForm.spec.ts
@@ -0,0 +1,22 @@
+import { CamundaRestClient } from '../../../c8/lib/CamundaRestClient'
+
+const c8 = new CamundaRestClient()
+
+test('It can retrieve a linked user task form', async () => {
+	const res = await c8.deployResourcesFromFiles([
+		'./src/__tests__/testdata/test-form-retrieval.bpmn',
+	])
+	const key = res.processes[0].processDefinitionKey
+	const id = res.processes[0].processDefinitionId
+	const wfi = await c8.createProcessInstance({
+		processDefinitionId: id,
+		variables: {},
+	})
+	expect(wfi.processDefinitionKey).toBe(key)
+	// Search user tasks
+
+	// After deleting the process definition, we should not be able to start a new process instance.
+	await expect(
+		c8.createProcessInstance({ processDefinitionId: id, variables: {} })
+	).rejects.toThrow('404')
+})
diff --git a/src/__tests__/testdata/form/test-basic-form.form b/src/__tests__/testdata/form/test-basic-form.form
@@ -0,0 +1,66 @@
+{
+  "components": [
+    {
+      "text": "# Text",
+      "type": "text",
+      "layout": {
+        "row": "Row_17fixin",
+        "columns": null
+      },
+      "id": "Field_0md10mq",
+      "properties": {
+        "_bind": "processInstanceKey"
+      }
+    },
+    {
+      "label": "First name",
+      "type": "textfield",
+      "layout": {
+        "row": "Row_0ol9o23",
+        "columns": null
+      },
+      "id": "Field_1cbwwbj",
+      "key": "firstName"
+    },
+    {
+      "label": "Last name",
+      "type": "textfield",
+      "layout": {
+        "row": "Row_00f2lx1",
+        "columns": null
+      },
+      "id": "Field_1pezk22",
+      "key": "lastName"
+    },
+    {
+      "label": "Phone number",
+      "type": "textfield",
+      "layout": {
+        "row": "Row_1mlj0fj",
+        "columns": null
+      },
+      "id": "Field_0aa2j1d",
+      "key": "phoneNumber"
+    },
+    {
+      "label": "Submit",
+      "action": "submit",
+      "type": "button",
+      "layout": {
+        "row": "Row_1h7s4he",
+        "columns": null
+      },
+      "id": "Field_0exznfr"
+    }
+  ],
+  "type": "default",
+  "id": "test-basic-form",
+  "executionPlatform": "Camunda Cloud",
+  "executionPlatformVersion": "8.6.0",
+  "versionTag": "1",
+  "exporter": {
+    "name": "Camunda Modeler",
+    "version": "5.30.0"
+  },
+  "schemaVersion": 17
+}
diff --git a/src/__tests__/testdata/form/test-form-retrieval.bpmn b/src/__tests__/testdata/form/test-form-retrieval.bpmn
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:modeler="http://camunda.org/schema/modeler/1.0" id="Definitions_1ie1nz5" targetNamespace="http://bpmn.io/schema/bpmn" exporter="Camunda Modeler" exporterVersion="5.31.0" modeler:executionPlatform="Camunda Cloud" modeler:executionPlatformVersion="8.6.0">
+  <bpmn:process id="test-form-retrieval" name="Test Form Retrieval" isExecutable="true">
+    <bpmn:startEvent id="StartEvent_1" name="Start Form Retrieval Test">
+      <bpmn:outgoing>Flow_1m26kn9</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:sequenceFlow id="Flow_1m26kn9" sourceRef="StartEvent_1" targetRef="Activity_1nouls1" />
+    <bpmn:userTask id="Activity_1nouls1" name="Enter customer details">
+      <bpmn:extensionElements>
+        <zeebe:userTask />
+        <zeebe:formDefinition formId="test-basic-form" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>Flow_1m26kn9</bpmn:incoming>
+      <bpmn:outgoing>Flow_1kcig7z</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:endEvent id="Event_0thxonp" name="Form Retrieval Test completed">
+      <bpmn:incoming>Flow_1kcig7z</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow_1kcig7z" sourceRef="Activity_1nouls1" targetRef="Event_0thxonp" />
+  </bpmn:process>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="test-form-retrieval">
+      <bpmndi:BPMNShape id="StartEvent_1_di" bpmnElement="StartEvent_1">
+        <dc:Bounds x="182" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="167" y="145" width="67" height="27" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Activity_0xlsys1_di" bpmnElement="Activity_1nouls1">
+        <dc:Bounds x="270" y="80" width="100" height="80" />
+        <bpmndi:BPMNLabel />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="Event_0thxonp_di" bpmnElement="Event_0thxonp">
+        <dc:Bounds x="422" y="102" width="36" height="36" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="404" y="145" width="74" height="27" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="Flow_1m26kn9_di" bpmnElement="Flow_1m26kn9">
+        <di:waypoint x="218" y="120" />
+        <di:waypoint x="270" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="Flow_1kcig7z_di" bpmnElement="Flow_1kcig7z">
+        <di:waypoint x="370" y="120" />
+        <di:waypoint x="422" y="120" />
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>
diff --git a/src/c8/lib/C8Dto.ts b/src/c8/lib/C8Dto.ts
@@ -353,3 +353,16 @@ export interface RestJob<
 	 */
 	readonly tenantId: string
 }
+
+export interface UserTaskFormResponse {
+	/**T he tenant ID of the form. */
+	tenantId: string
+	/** The BPMN ID of the form. */
+	bpmnId: string
+	/** The form content. */
+	schema: object
+	/** The version of the the deployed form. */
+	version: number
+	/** The key of the form. */
+	formKey: string
+}
diff --git a/src/c8/lib/CamundaRestClient.ts b/src/c8/lib/CamundaRestClient.ts
@@ -55,6 +55,7 @@ import {
 	RestJob,
 	TaskChangeSet,
 	UpdateElementVariableRequest,
+	UserTaskFormResponse,
 } from './C8Dto'
 import { getLogger, Logger } from './C8Logger'
 import { CamundaJobWorker, CamundaJobWorkerConfig } from './CamundaJobWorker'
@@ -931,6 +932,25 @@ export class CamundaRestClient {
 		)
 	}
 
+	/**
+	 *
+	 * Get the form of a user task.
+	 *
+	 * Note that this endpoint will only return linked forms. This endpoint does not support embedded forms.
+	 *
+	 * Documentation: https://docs.camunda.io/docs/next/apis-tools/camunda-api-rest/specifications/get-user-task-form/
+	 * @since 8.7.0
+	 *
+	 */
+	public async getUserTaskForm(
+		userTaskKey: string
+	): Promise<UserTaskFormResponse> {
+		const headers = await this.getHeaders()
+		return this.rest.then((rest) =>
+			rest.get(`user-tasks/${userTaskKey}/form`, { headers }).json()
+		)
+	}
+
 	private addJobMethods = <Variables, CustomHeaders>(
 		job: RestJob<Variables, CustomHeaders>
 	): RestJob<Variables, CustomHeaders> &