Runnerty logo

Introducing Runnerty

Runnerty is an open source process orchestrator written in nodejs. It allows us to plan and configure workflows easily, providing a big amount of features.

In this article I am going to explain how it works and why it can helps you.

What is a process and a workflow?

First thing we have to understand is what is a process and a workflow. A process is an action or operation and a workflow is a serie of processes conected and directed to some end.

These are some examples of typical workflows in every system:

• Automatic backups
• Mailing
• Database operations
• Files operations
• ETL (Extract, transform, load)

Based in four concepts

Runnerty is based in four concepts; Chains, executors, notifiers and triggers. To start configuring and planing our workflows we will have to understand how runnerty use this four components.

Chains:

A chain is just a set of processes. The place where we are going to configure or processes, establishing dependencies between them, sharing data from one process to the others, etc.

Executors:

The executors are runnerty plugins that allows us to do different opperations with our processes without writing a single line of code.

For example, we could execute an instruction in our Mysql database just configuring the Mysql Runnerty executor. Or send an email with the mail executor just indicating who and the text of the message.

There are a lot of executors already developed that you can use just installing them with npm.

Some of the existing executors

It is important to say that we are not obligated to use the runnerty executors, we could use any process that we already have developed, so runnerty is completely compatible with your actual system. Furthermore, Runnerty is language agnostic, it can run any process writen in any language (javascript, php, python, bash, etc)

Notifiers:

Another awesome feature of runnerty is the possibility to get notified when an event occurs in our chain or processes. For example, we would like to know when a process of our chain fails.

As the executors, the notifiers are plugins which Runnerty use for this end. we can get notified via telegram, slack, etc, in different events of the processes or chain, (start, end, fail, retry, etc).

Some of the notifiers already developed

Triggers:

Once we know that we can config a chain with our processes using the runnerty executors to execute operations and notifiers to know when something happen in our processes, it just left to know how we can indicate when out chain has to start.

Ad hoc, runnerty provides another kind of plugins called triggers. The triggers fires our chains and can do that in several ways. For example every hour, or in an specific date, or when a file is left in a directory, or when a new user is inserted in a Firebase database.

Some of the existing triggers

Hands on code

Do you find interesting what runnerty can do? Let’s follow the quick-start they have to get in touch with the code.

Installing runnerty and cloning the repo:

To install runnerty in our system all we need is to have node v8.9.4

npm install runnerty -g

Now we can clone the quick-start repo and go into the project:

git clone https://github.com/runnerty/runnerty-quick-start
cd runnerty-quick-start

This repo contains a simple chain with just one process, this process only executes an echo using the shell executor. The chain is fired every minute using the scheduler trigger:

Let’s have a look at the files:

package.json. Here we can see the runnerty modules installed as dependencies, if we want to add more executors, triggers or notifiers we just have to install them via npm.

"dependencies": {
    "@runnerty/trigger-schedule": "latest",
    "@runnerty/executor-shell": "latest"
  }

config.json. In this file is where we are going to add the configurations for our executors, notifiers and triggers:

{
  "triggers": [
    {
      "id":"schedule_dafault",
      "type":"@runnerty-trigger-schedule"
    }
  ],
  "executors": [
    {
      "id": "shell_default",
      "type": "@runnerty-executor-shell"
    }
  ]
}

As we can see in the file there are only two configurations, for the shedule trigger and for the shell executor.

plan.json. Finnally in this file is where our chain and processes are:

{
  "chains":[
    {
      "id":"CHAIN_ONE",
      "name":"Chain one sample",
      "triggers":[
        {
          "id":"schedule_dafault",
          "schedule_interval":"*/1 * * * *"
        }
      ],
      "processes":[
      ]
    }
  ]
}

At the first level of the chain we have the general data of the chain (name and id) and in the triggers section we find the usage of the shcheduler trigger. In this case the interval given indicates that the chain is going to be executed every minute.

Below we find the processes array, in this section is where all the processes are configured:

"processes": [
  {
    "id": "PROCESS_ONE",
    "name": "Proccess One",
    "exec": {
      "id": "shell_default",
      "command": "echo Runnerty: hello world!"
    },
    "chain_action_on_fail": {
      "action": "end"
    },
    "output": [
      {
        "file_name": "./test.log",
        "write": [
          "EXECUTION @GETVALUE(PROCESS_ID) - AT @GETDATE('YYYY-MM-DD                     HH:mm:ss')\n @GETVALUE(PROCESS_EXEC_MSG_OUTPUT)"
        ],
        "concat": true,
        "maxsize": "10mb"
      }
    ]
  }
]

As we can see there is only one process planed, it uses the shell executor executing an echo.

Having a look at the output property it is indicating to write the output of ther process in a file.

To executes this chain we just have to run runnerty in the project directory. And in the next minute will see how the test.log file is created with to output of the process.

runnerty

What’s next?

This is the easiest example of runnerty usage, it only shows a minimal part of its potential. Runnerty is a very powerful tool which provides awesome features to create and manage workflows:

• A large amount of executor, notifier and triggers to develop processes without writing code and connect them with several servicies and platforms.
• Notifications on events to always know what is happening.
• Simple and advanced dependencies between processes and chains.
• Params and credential centralization.
• Auto-gestioned logs.
• Historification.
• Language independence.
• Easy scalable
• …

I really encourage you to have a look at the runnerty documentation (http://docs.runnerty.io) and find more information and tutorials.