Zenaton white logo


Workflow Engine

Where do I install the Zenaton agent ?

You will need to install the Zenaton agent on the servers where you host your application and where tasks will be executed. These might be the same location but we encourage our users to have dedicated servers to run Zenaton tasks to avoid having all of the load on the same server.

The Zenaton Agent can be configured in two different modes:

  • worker mode: this the default mode and the agent will be configured to both send jobs to the engine from your sources and execute jobs.
  • client only: in this mode, the agent is only configured to send new jobs to the Zenaton engine queues. It will not execute jobs.

Note if you are running Zenaton on your local machine, you would only need one agent in worker mode.

Here is a visual overview of how the agent installed on your web app and workers communicates with the Zenaton workflow engine.

overview Zenaton

How are tasks executed?

The tasks and workflows are executed on your servers where the Zenaton agent is installed.
You may have only one server which is used both as an application and a worker.
You are responsible for managing your workers and can view their real-time activity on the dashboard.
Zenaton only has access to your input, output and task and workflow properties.
We do not have access to your sources or other data.

I cannot install Zenaton Agent on my computer, is there another way I can install Zenaton ?

You can use Docker, in the example repository of each language, we provide a Dockerfile.

You can also install it in the cloud, we provide some guides for Heroku ,AWS , Clever Cloud .

If you are not able to install the Zenaton agent to run your own jobs, you can still explore our Demo App on your Zenaton dashboard which shows examples of workflow and task executions.

If you have any issues with the installation of the agent, please contact us by email or chat on the website.

How do I update my agent ?

To update your agent, you simply have to re-install the agent by running the command:

curl https://install.zenaton.com | sh

How are tasks are distributed on my workers?

Tasks and workflows are horizontally distributed to connected workers. All workers need to have the Agent installed with the sources of workflows and tasks. You can also decide if a specific worker needs to execute specific tasks and workflows. To change the parameters on the Agent, the documentation explains it.

Tasks and Workflows

What are task and workflow properties ?

They are the attributes of your task/workflow classes.

You can find a full explanation in the documentation.

Does Zenaton have an API to display executions internally?

An internal API is on our product roadmap but not yet not yet released.

Does waiting for a date or time impact my server's performance?

No, the wait is handled on the Zenaton engine. So your worker won't consume any resources during those waits. Your server will either be idle if there is nothing more to do, or move on to the next task that needs to be executed.

It can be difficult to understand but when you use the wait method, we will not wait for the date or time indicated. Zenaton does not open any threads on your machine and the wait does not impact your server's performance or pricing. We will simply re-execute the class of the workflow on your server at the right time.

How can I execute a higher volume of tasks?

The easiest way would be to add more workers, or bigger workers (with more CPU and RAM).

But there are a few other options depending on your situation.

View the insights/metrics on your dashboard to review the execution history of workflows, and look at each step of each instance and see the details about your task duration, and how long they are waiting inside the queues.

Task execution timings

Then view metrics about resource usage in the agent's monitoring page, to get an idea of CPU and RAM current usage.

Agent monitoring list

So based on these metrics, here are a few suggestions to increase task volume:

Increase Concurrence: If you have a lot of tasks with a shorter execution time (such as tasks sending notifications) AND your CPU/RAM usage is low, you can raise the agent parameterZENATON_CONCURRENT_MAX so that more tasks can be run at the same time.
We encourage you to raise it to step by step and watch the CPU/RAM usage. Starting out with a value that is too high could be counterproductive.

Rate Limiting: Some of your tasks might be calling an API with rate-limiting so that some are failing. If you are retrying them automatically, you might need to add a longer delay between automatic retries.

Add more workers: If you are running tasks with a shorter execution time, but they are waiting in the queues, you might be feeding them more quickly than your workers can process them, so you would add more workers to be able to execute more jobs in parallel.

Prioritize tasks on workers: If you have a mix of heavy tasks that take a long time to execute mixed with with notification tasks that need to be executed quickly, take a look at the next question about how to prioritize tasks.

How can I prioritize tasks on my workers?

You cannot preordain the order of tasks on a server but you can dedicate one worker to executing a specific type of task. So if you have a type of task such as notifications that need to be executed quickly, you can change one or more of your worker's configuration to only execute these tasks - thereby allowing other workers to execute all other types of tasks.

You can do this by changing the agent configuration:

You will use a combination of two parameters ZENATON_HANDLE_ONLY and ZENATON_HANDLE_EXCEPT. here is the reference of the agent configuration.

A classic example, is when you want continue sending notifications as fast as possible, and run a few heavy jobs at the same time but with less priority.

You can dedicate some of your works to sending notification tasks with this settings:

On the worker(s) that handle only the notifications:


And the rest of the workers will process other jobs with this setting:


How can I update a workflow?

Zenaton lets you easily update a workflow with versioning but your modifications will apply only to new instances. Running instances will be completed with the initial workflow.

Everything is detailed in documentation.

How long can a workflow be in running state? Can I have a workflow that keeps running for days or months?

There is no limitation about the workflow duration.

Troubleshooting & Errors

Why isn’t my task running?

If you are trying to run a task and nothing is happening, there are a few places to check:

First, check the dashboard to see if the task has failed and view the stacktrace and error details.

If the task is not on your dashboard, check the agents tab to verify that your agents are connected.

If you are still having issues, please contact us by email or chat on the website.

Are the states of my tasks maintained in case of failures?

If your servers are down or Zenaton is unavailable, tasks, events and workflows will be stored in the queues. As soon as your workers are available again, the jobs will be processed.


Is Zenaton GDPR or PCI compliant ?

As tasks and workflows are executed on your servers, you manage your own data.

Zenaton has only access to input, output, and properties of tasks and workflows.
Consequently, you can decide to encrypt this data.

Which ports do I need to open ?

Two ports need to be open for the Agent. Traffic is always initiated by the Agent to Zenaton.

Ports are:

  • 443/tcp: port used by the Agent to send requests to Zenaton API
  • 5672/tcp: port used by the Agent to send and receive instructions

What kind of connection is done with Zenaton ?

There are HTTP and AMQP connections to the Zenaton engine.
Traffic is always initiated by the Agent to Zenaton