29.07.2021. | Author: 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

More Blog articles


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

Author: 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 […]

read more

Ways to integrate Kafka with Databases

Author: 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 […]

read more

BPMN Error Handling Mechanism – Dealing with many errors in a process

Author: JIT

Errors are inherently part of software development. They can happen because of several reasons. One common definition of a software error is a mismatch between the program and its specification. In other words, we can say, a program has an error when the program does not do what the end-user expects. In this blog post, […]

read more