29.07.2021. | Autor: Maximilian Kamenicky

Ruby external task worker

“The value of a system is often defined by how well it integrates with other systems”

The best software is limited if you cannot integrate it with existing frameworks. In the case of Camunda, this fact is all the more true. Imagine a workflow automation engine without a way to interact with the existing software.

That is why Camunda created external service tasks, enabling us to create a client in any programming language. With that, we can interact with camunda from virtually every existing software application.

In the following blog, we show you how this is achieved in Ruby on Rails. We will guide you on how to create your own Ruby Worker.

Please note that the installation will be done on Windows using JetBrains IntelliJ as an IDE.

Further, we will use an integration gem for Camunda called
Camunda-Workflow created here:

If you intend to use another gem, please note that some steps will differ.

Installation of Ruby

  • Please download the most recent ruby installer from here:
  • We recommend that you download the installer labelled Ruby+Devkit + version
  • Ruby has issues with spaces in the file path. So please take care of that when choosing the installation directory
  • Install all dev tools of the installer
  • To verify that you have everything installed correctly, you should be able to run the following:
    1 ruby --version

Installation of Node.js

  • Please follow the installation guide for node
  • To verify that you have everything installed correctly, you should be able to run the following:
    1 node --version

Installation of yarn

Installation rails

  • To install Rails, use the gem install command provided by RubyGems:
    1 $ gem install rails
  • To verify that you have everything installed correctly, you should be able to run the following:
    1 $ rails --version

Configuration of IntelliJ

  • please install the correct ruby plugin
  • Configure the installed ruby SDK in IntelliJ

Creation of Project

After that, we can jump into the creation of an external task client in IntelliJ. For that follow the following steps:

  1. 1. Create a new project

2. Choose ruby on rails

  • Click next and finish
  • A new ruby project will be generated and will have the following folder structure:

1│ ├───app
2│ ├───assets
3│ │ ├───config
4│ │ ├───images
5│ │ └───stylesheets
6│ ├───channels
7│ │ └───application_cable
8│ ├───controllers
9│ │ └───concerns
10│ ├───helpers
11│ ├───javascript
12│ │ ├───channels
13│ │ └───packs
14│ ├───jobs
15│ ├───mailers
16│ ├───models
17│ │ └───concerns
18│ └───views
19│ └───layouts
22│ ├───environments
23│ ├───initializers
24│ ├───locales
25│ └───webpack
28│ ├───assets
29│ └───tasks
35│ ├───channels
36│ │ └───application_cable
37│ ├───controllers
38│ ├───fixtures
39│ │ └───files
40│ ├───helpers
41│ ├───integration
42│ ├───mailers
43│ ├───models
44│ └───system

Configuration of the Project

  • In the GemFile we will now add an existing camunda gem for external tasks called ‚camunda-workflow‘. For this please add the following lines to the GemFile.

    1 #camunda workflow
    2 gem 'camunda-workflow', '~> 0.2.3'
  • We now need to install the gems like this:

    1 bundle install
  • With this, we can use the gem in our application.
  • We will now create the initializer as described in

    1 # filename config/initializers/camunda.rb
    2 Camunda::Workflow.configure do |config|
    3 config.engine_route_prefix = 'engine-rest'
    4 end
  • This configuration defines the endpoint specifics for the rest engine.

Creation of worker

  • For the creation of the worker we start by creating the job interface for all the external task jobs in the directory:
    app > job > create camunda_job.rb

    1 class ApplicationJob < ActiveJob::Base ## this is the base class for ruby jobs
    2 end
    4 class CamundaJob < ApplicationJob #this is the base class for all camundaJobs
    5 include Camunda::ExternalTaskJob #must include the camunda-workflow interface for ExternalTaskJob
    6 end
  • The camunda_job.rb is what allows us to use the camunda gem in our application. With that, we tell the program to rely on Camunda::ExternalTaskJob for the class camunda_job.rb
  • Now let’s create an external task job for the process (in our case a simple process posting on Twitter) in the directory: app > bpmn > create twitter_qa_process.rb

    1 module TwitterQaProcess #process-definition-key (needs to be snake-case for ruby)
    2 class ActivityInformUser < CamundaJob #the external task task-id extending our camundaJob interface
    3 def bpmn_perform(variables) #this method is part of the CamundaJob interface
    4 # A hash returned will become variables in the Camunda BPMN process instance
    5 end
    6 end
    7 end
  • The file twitter_qa_process.rb is the responsible file for one process.
  • The defined class ActivityInformUser is the direct relation to the external Task ID.
  • With that, all steps are completed. To now run the jobs please open the terminal and run:

    1 rails console
    3 Loading development environment (Rails 6.1.1)
    4 irb(main):001:0>
    6 Camunda::Poller.fetch_and_queue %w[TOPICNAME]

Afterwards, it will poll and complete tasks as long as one with the topic exists.

Useful Links:

More about JIT and Workflow Automation
More about Service Tasks: Official Documentation

Written by Maximilian Kamenicky
Developer at J-IT IT-Dienstleistungs Gesmbh

Photo by Michael Dziedzic on Unsplash

Weitere Blog


Maler oder Macher sein

Autor: Mirko Pawlak

Digitale Transformation ohne Grenzen. Ich bin Prozessmacher. Ich hocke tief drinnen im Maschinenraum und schau mir an, was das Unternehmen einzigartig macht. Ich tu das gern, denn jeder Prozess ist lebendig und einzigartig. Es gibt einen Anfang, dann passiert etwas und am Ende ist es vorbei. Wie geht man am besten mit seinen Prozessen um? […]

Blog lesen

How to deploy a Camunda Spring Boot application to a shared application server

Autor: Maximilian Kamenicky

Context Do you still remember our Blog: How to deploy a Camunda Spring Boot application to an external application server? In that blog, my colleague Gerardo Manzano Garcia explained the steps necessary to run a spring boot application on a dedicated application server i.e. an external Tomcat. In other words, run the spring boot application […]

Blog lesen

Ways to integrate Kafka with Databases

Autor: Denis Savenko

Kafka is a great instrument. It is widely used in event-driven architectures, and it does the job perfectly fine. However, this is not the only use-case for it. Kafka is also very well suitable for data replication and ingestion use-cases, as well as for building modern ETL or ELT pipelines. The most noteworthy reasons for […]

Blog lesen