Skip to content
⚡ Node.js library to run and orchestrate background jobs with Zenaton Workflow Engine
Branch: master
Clone or download
Latest commit 97e8e5d Aug 9, 2019

Easy Asynchronous Jobs Manager for Developers
Explore the docs »
Website · Examples in Node · Tutorial in Node

NPM Version CircleCI License

Zenaton library for Node

Zenaton helps developers to easily run, monitor and orchestrate background jobs on your workers without managing a queuing system. In addition to this, a monitoring dashboard shows you in real-time tasks executions and helps you to handle errors.

The Zenaton library for Node lets you code and launch tasks using Zenaton platform, as well as write workflows as code. You can sign up for an account on Zenaton and go through the tutorial in Node.

Node Documentation

You can find all details on Zenaton's website.


Node 8 and later.

Table of contents

Getting started


Install the Zenaton Agent

To install the Zenaton agent, run the following command:

curl | sh

Install the library

To add the latest version of the library to your project, run the following command:

npm install zenaton --save

TypeScript typings

For Typescript developers:

npm install @types/zenaton --save-dev

Quick start

Client Initialization

To start, you need to initialize the client. To do this, you need your Application ID and API Token. You can find both on your Zenaton account.

Then, initialize your Zenaton client:

/* client.js */

const { Client } = require("zenaton");

  "YourApplicationEnv", // Use "dev" as default

Boot file

Next step is to have your Zenaton Agent listen to your application.

The Agent needs to be pointed to a boot file which will allow him to infer your programming language (here JavaScript) but also to figure out where your jobs are located when the time comes to run them.

/* boot.js */


// Import here your jobs as you go
// require("./tasks/HelloWorldTask");
// require("./workflows/MyFirstWorkflow");

To run the listen command:

zenaton listen --app_id=YourApplicationId --api_token=YourApiToken --app_env=YourApplicationEnv --boot=boot.js

Executing a background job

A background job in Zenaton is created through the Task function.

Let's start by implementing a first task printing something, and returning a value:

/* tasks/HelloWorldTask.js */

const { Task } = require("zenaton");

module.exports = Task("HelloWorldTask", async function handle() {
  console.log("Hello world!");

  return Math.floor(Math.random() * 10);

Now, when you want to run this task as a background job, you need to do the following:

/* launchHelloWorldTask.js */

// Don't forget to import it in the 'boot' file as well
const HelloWorldTask = require("./tasks/HelloWorldTask");

new HelloWorldTask().dispatch().catch((err) => {

That's all you need to get started. With this, you can run many background jobs. However, the real power of Zenaton is to be able to orchestrate these jobs. The next section will introduce you to job orchestration.

Orchestrating background jobs

Job orchestration is what allows you to write complex business workflows in a simple way. You can execute jobs sequentially, in parallel, conditionally based on the result of a previous job, and you can even use loops to repeat some tasks.

We wrote about some use-cases of job orchestration, you can take a look at these articles to see how people use job orchestration.

Using workflows

A workflow in Zenaton is created through the Workflow function.

We will implement a very simple workflow:

First, it will execute the HelloWorld task. The result of the first task will be used to make a condition using an if statement. When the returned value will be greater than 0, we will execute a second task named FinalTask. Otherwise, we won't do anything else.

One important thing to remember is that your workflow implementation must be idempotent. You can read more about that in our documentation.

The implementation looks like this:

/* workflows/MyFirstWorkflow.js */

const HelloWorldTask = require("../tasks/HelloWorldTask");
const FinalTask = require("../tasks/FinalTask");

const { Workflow } = require("zenaton");

module.exports = Workflow("MyFirstWorkflow", async function handle() {
  const number = await new HelloWorldTask().execute();

  if (number > 0) {
    await new FinalTask().execute();

Now that your workflow is implemented, you can execute it by calling the dispatch method:

/* launchMyFirstWorkflow.js */

// Don't forget to import it in the 'boot' file as well
const MyFirstWorkflow = require("./workflows/MyFirstWorkflow");

new MyFirstWorkflow().dispatch().catch((err) => {

If you really want to run this example, you will need to implement the FinalTask task.

There are many more features usable in workflows in order to get the orchestration done right. You can learn more in our documentation.

Getting help

Need help? Feel free to contact us by chat on Zenaton.

Found a bug? You can open a GitHub issue.

You can’t perform that action at this time.