{"id":1879,"date":"2018-08-30T00:00:00","date_gmt":"2018-08-29T22:00:00","guid":{"rendered":"https:\/\/wwwneu.strehle.de\/tim\/weblog\/archives\/2018\/08\/30\/1638-2\/"},"modified":"2025-07-31T21:37:07","modified_gmt":"2025-07-31T19:37:07","slug":"1638-2","status":"publish","type":"post","link":"https:\/\/www.strehle.de\/tim\/weblog\/archives\/2018\/08\/30\/1638-2\/","title":{"rendered":"Playing with the Camunda workflow engine (and PHP)"},"content":{"rendered":"\n

A generic workflow engine, configured via a graphical diagram editor on top of an XML syntax \u2013 that\u2019s what I tried and failed to develop more than 15 years ago. I did help build three generations of a simple \u201cworkflow\u201d component<\/a> integrated in our DAM product to drive asset ingestion and export, kept reading (see The State of Workflow<\/a> and Decoupling Application Logic<\/a>) and writing (Workflow awareness of DAM systems<\/a>) about workflows \u2013 and hoping that one day, a powerful and beautiful workflow management system would make my work easier.<\/p>\n\n\n\n

Camunda<\/h3>\n\n\n\n

That\u2019s why I was thrilled to discover Camunda<\/a>, a workflow engine with an open source, free community edition. It is standards-based, written in Java, and comes with a Web UI, REST API and graphical process diagram modeler. Here\u2019s a screenshot of Camunda Modeler<\/a>:<\/p>\n\n\n\n

\"Camunda<\/a><\/figure>\n\n\n\n

<\/p>\n\n\n\n

Camunda typically \u201cdrives\u201d a workflow process by actively executing your Java code when there\u2019s a task to perform. But you can also use external tasks<\/a> (see \u201cImplementation: External\u201d and \u201cTopic\u201d in the screenshot above) to turn a task into a queue to be handled by external workers via the Camunda REST API<\/a>. That pattern is useful for PHP developers like me, but also especially suited to service orchestration<\/a>. The workflow engine sits there passively, taking only care of workflow definitions, instances, their flow and state. (More on that in the External Tasks for Service Orchestration<\/a> webinar video.)<\/p>\n\n\n\n

While Camunda is trivial to install<\/a> and extensively documented, it took me a while to grasp the basic concepts \u2013 process definitions, process instances, tasks, gateways, variables \u2013 and I\u2019m only scratching the surface so far.<\/p>\n\n\n\n

Using Camunda from PHP<\/h3>\n\n\n\n

My example workflow is a minimal \u201casset processing pipeline\u201d, extracting metadata from an asset file (using ExifTool) and rendering a thumbnail preview image (using ImageMagick) for images. This isn\u2019t \u201cservice orchestration\u201d, but a good enough test case to help me get to know Camunda.<\/p>\n\n\n\n

First, I drew the above diagram in Camunda Modeler and deployed it to the server. Now I could start a new process instance using curl:<\/p>\n\n\n\n

$ curl -X POST \\\n  http:\/\/localhost:8080\/engine-rest\/process-definition\/key\/asset-ingestion\/start \\\n  -H 'Content-Type: application\/json' \\\n  -d '{\"variables\":{\"path\":{\"value\":\"\/tmp\/img.jpg\"}}}'\n<\/code><\/pre>\n\n\n\n
I used the camunda-rest-client<\/a> PHP library (not an official library) to implement a simple worker process that fetches and locks an open task, calls ExifTool or ImageMagick and marks the task as completed. Asset and thumbnail filenames are stored in process instance variables.<\/p>\n\n\n\n
You can find all of my PHP code on Github<\/a>, along with the process definition XML. Here\u2019s some interesting code snippets:<\/p>\n\n\n\n
Fetching the next open task<\/strong>, and locking it for exclusive processing by the current worker process:<\/p>\n\n\n\n
$externalTaskService = new ExternalTaskService($camundaUrl);\n\n$externalTaskQueryRequest = (new ExternalTaskRequest())\n    ->set('topics', [['topicName' => $topicName, 'lockDuration' => $lockDuration]])\n    ->set('workerId', $workerId)\n    ->set('maxTasks', 1);\n\n\/\/ Returns an array of task objects\n$externalTasks = $externalTaskService->fetchAndLock($externalTaskQueryRequest);\n<\/code><\/pre>\n\n\n\n
Reading process instance variables:<\/strong><\/p>\n\n\n\n
$assetFilePath = $externalTask->variables->path->value;\n<\/code><\/pre>\n\n\n\n
Telling Camunda that the task is completed<\/strong> when the worker is done (so Camunda can automatically move on to the next workflow task), adding task results to the process instance using variables:<\/p>\n\n\n\n
$externalTaskRequest = (new ExternalTaskRequest())\n    ->set('variables', $updateVariables)\n    ->set('workerId', $workerId);\n\n$externalTaskService->complete($externalTask->id, $externalTaskRequest);\n<\/code><\/pre>\n\n\n\n
Notifying Camunda that the task failed<\/strong> (which makes Camunda report an \u201cincident\u201d):<\/p>\n\n\n\n
$externalTaskRequest = (new ExternalTaskRequest())\n    ->set('errorMessage', $errorMessage)\n    ->set('retries', $retries)\n    ->set('retryTimeout', $retryTimeout)\n    ->set('workerId', $workerId);\n\n$this->externalTaskService->handleFailure($externalTask->id, $externalTaskRequest);\n<\/code><\/pre>\n\n\n\n
In my example, I need to instantiate at least one worker process per task \u201ctopic\u201d. Multiple instances would automatically process open tasks in parallel. Running a worker<\/strong> looks like this:<\/p>\n\n\n\n
$ php worker.php \\\n  --camunda-url=\"http:\/\/localhost:8080\/engine-rest\" \\\n  --task-topic=\"asset-extract-metadata\"\nFetched and locked <asset-extract-metadata> task <00a74f0a-abcd-11e8-afcc-02422b22e161> \n  of <asset-ingestion> process instance <00a664a4-abcd-11e8-afcc-02422b22e161>.\nCompleted task <00a74f0a-abcd-11e8-afcc-02422b22e161>\n<\/code><\/pre>\n\n\n\n
Batteries included<\/h3>\n\n\n\n
I love it when software developers care for transparency and visualization. Camunda Cockpit<\/a> lets you peek into currently-running processes by showing how many of them are in which state, and letting you inspect and even change their variables:<\/p>\n\n\n\n
\"Camunda<\/a><\/figure>\n\n\n\n
<\/p>\n\n\n\n
It\u2019s pretty amazing that a simple diagram plus a single 300-line PHP file get me a separation of process flow and task implementation, queues, parallel worker processes, error handling, and insights into executions.<\/p>\n\n\n\n
I will definitely keep playing with Camunda. If you\u2019re already using it in production, I\u2019m happy to hear from you!<\/p>\n","protected":false},"excerpt":{"rendered":"
A generic workflow engine, configured via a graphical diagram editor on top of an XML syntax \u2013 that\u2019s what I tried and failed to develop more than 15 years ago. I did help build three generations of a simple \u201cworkflow\u201d component integrated in our DAM product to drive asset ingestion and export, kept reading (see […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":"","_share_on_mastodon":"0"},"categories":[1],"tags":[],"class_list":["post-1879","post","type-post","status-publish","format-standard","hentry","category-weblog"],"share_on_mastodon":{"url":"","error":""},"_links":{"self":[{"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/posts\/1879","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/comments?post=1879"}],"version-history":[{"count":1,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/posts\/1879\/revisions"}],"predecessor-version":[{"id":1893,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/posts\/1879\/revisions\/1893"}],"wp:attachment":[{"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/media?parent=1879"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/categories?post=1879"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.strehle.de\/tim\/wp-json\/wp\/v2\/tags?post=1879"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}