How to start using Runnerty?

Runnerty is a “low code” technology that allows to integrate and automate online & offline applications, systems infrastructure and services with third parties in a simple, fast and secure way, creating workflows and offering a new way to develop.

Do you want to read it in Spanish ?

If you want to know a little more about why you should try it, here is this post 👀.

In this article we are going to see some basic concepts of Runnerty, how to create our first project and how to connect with Runnerty Platform.

1. Some basics
2. Creating our first Runnerty project
3. Project structure
4. Connecting with Runnerty Platform 🚀
5. Launch our first process
6. Extra ball: Add a second process and visualize it on the platform.

1. Basic concepts 📕

Chains or workflows

They are a grouping of processes that make sense in a certain context. This can be as diverse as you can create a chain to check that your website is online, create a chain to collect orders from your e-commerce and communicate them to the corresponding supplier or create ETL chains for your Data Warehouse. Runnerty provides many features that will make defining these workflows super agile and fully scalable, define dependencies between processes, pass values from one to another or even evaluate them to decide which “way to go” are just some of its possibilities.

Executors

Each of the processes of our chain will execute a specific action through these modules. We can use very generic executors, such as Shell, which allows you to execute any command through the console, or other very specific ones that allow us to perform very specific actions, such as communicating with a delivery company like MRW or Fedex.

Notifiers

As their name suggests, they will keep us informed at all times, when a chain or a specific process starts or finishes, if it is being reattempted(creo que reattempted es mejor que retried, pero no se, lo que quiero decir es reintentado ) or if it has failed. We can send an email, a sms or message via Telegram or connect it directly to our incident system.

Triggers

These modules are in charge of launching our workflows. It can be something planned, it can be when a file is received in an ftp …

Note 🔎: Executors, notifiers and triggers are modules, you can develop your own very easily so you can take Runnerty’s potential wherever you want.

2. I’m not telling you, I’m showing you 👩💻👨💻

The only thing we need before starting is to have the LTS version of NodeJS (V 14+) installed. If you don’t have it, you can download it here.

Runnerty-cli

Runnerty has a command line tool that will make things much easier. Just run the following command in a terminal and you’re done.

npx runnerty-cli new my-awesome-project

🎉 We already have our first Runnerty project!

3. Structure of our project 🔎

It is a very simple project, we are going to focus on the 2 basic Runnerty files:

• config.json
• plan.json

Config

In the config.json we are going to have 3 sections where we will be adding the configurations of our 3 types of modules (triggers, notifiers and executors). The ones you see in the example are just an identifier and a name to use in our workflows, in case the module needs some more data, this is where we would indicate it, for example an email account, a username and password, etc.

{
  "triggers": [
    {
      "id": "schedule_default",
      "type": "@runnerty-trigger-schedule"
    }
  ],
  "executors": [
    {
      "id": "shell_default",
      "type": "@runnerty-executor-shell"
    }
  ],
  "notifiers": [
    {
      "id": "console_default",
      "type": "@runnerty-notifier-console"
    }
  ]
}

Plan

In the plan is where we define our workflows 😎.

We can see several sections:

{
  "chains": [
    {
      "id": "CHAIN_ONE",
      "name": "Chain one sample",
      "triggers": [
        ...
      ],
      "notifications": {
        ...
      },
      "defaults_processes": {
        ...
      },
      "processes": [
        ...
      ]
    }
  ]
}

Chains

Inside each chain, besides a name and an identification, we will have 4 sections

1.Triggers, what triggers our workflow, in this case we have used the scheduler plugin and we have configured the process to run every minute.

...
"triggers": [
  {
    "id": "schedule_default",
    "schedule_interval": "*/1 * * * *"
  }
],
...

Note 🔎: This module uses standard cron nomenclature.

2. Notifiers, The notifications of our workflow, in this case we see that it is going to warn us when the chain starts, when it finishes and if it fails.

...
"notifications": {
  "on_start": [
    {
      "id": "console_default",
      "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') START OF THE CHAIN: @GV(CHAIN_ID)"
    }
  ],
  "on_end": [
    {
      "id": "console_default",
      "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') END OF THE CHAIN: @GV(CHAIN_ID)"
    }
  ],
  "on_fail": [
    {
      "id": "console_default",
      "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') FAIL OF THE CHAIN: @GV(CHAIN_ID)",
      "mode": "error"
    }
  ]
},
...

Note 🔎: We can already see some of Runnerty’s own functions, like GETDATE() that will return the date with the mask that we define or GV (get value) that in this case will return the string identifier. There are many more, here is a link to the documentation.

3. Defaults (optional). Many times it is very useful to define default values for all processes, that is why we have this section. All processes by default will have these notifications configured, although we can always overwrite them within the process itself.

"defaults_processes": {
  "notifications": {
    "on_start": [
      {
        "id": "console_default",
        "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') START: PROCESS @GV(PROCESS_ID)"
      }
    ],
    "on_fail": [
      {
        "id": "console_default",
        "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') ERROR: PROCESS @GV(PROCESS_ID): @GV(PROCESS_EXEC_ERR_OUTPUT)",
        "mode": "error"
      }
    ],
    "on_end": [
      {
        "id": "console_default",
        "message": "@GETDATE('YYYY-MM-DD HH:mm:ss') END: PROCESS @GV(PROCESS_ID)"
      }
    ]
  }
},

4. Processes

The most common properties that we can see inside a process (besides its name and identifier), are the following properties:

• exec
• output

...
"processes": [
  {
    "id": "PROCESS_ONE",
    "name": "Process One",
    "exec": {
      ...
    },
    "output": [
      ...
    ]
  },
  ...
]
...

4.1. The exec property where we are going to indicate which executor of our config.json we want to use and where we are going to indicate the necessary values for it to be executed. In this case, as we are going to use the Shell executor, we only need to indicate the command we want it to execute.

...
{
  "id": "PROCESS_ONE",
  "name": "Process One",
  "exec": {
    "id": "shell_default",
    "command": "echo Runnerty: hello world!"
  },
  "output": [
    ...
  ]
},
...

4.2. The output property, where we treat the output of the process. In this example we are going to write in a log file the result of the execution.

{
  "id": "PROCESS_ONE",
  "name": "Process One",
  "exec": {
    ...
  },
  "output": [
    {
      "file_name": "./@GETVALUE(PROCESS_ID).log",
      "write": [
        "EXECUTION @GV(PROCESS_ID) - AT @GETDATE('YYYY-MM-DD HH:mm:ss')\n @GV(PROCESS_EXEC_ERR_OUTPUT) @GV(PROCESS_EXEC_MSG_OUTPUT)"
      ],
      "concat": true,
      "maxsize": "10mb"
    }
  ]
},

Note 🔎: It is interesting to know that you can define the maximum size of your log file and avoid space problems.

4.3. As we commented before, we can also configure specific notifications for this process, for now we are going to leave this property empty because we have the default notifications configured.

4. Connecting to Runnerty Platform 🚀

Let’s connect our project with Runnerty Platform to make it easier to visualize and get the most out of Runnerty. This step is optional, but I recommend it, you will enjoy Runnerty much more 😊🔥.

1. We log in to the platform

2. Create the project, selecting the New project option.

3. We simply add the generated API Key to our config.json file

{
  "general": {
    "runnerty.io": {
      "apikey": "NUESTRO_TOKEN"
    }
  },
  "triggers": [...],
  "executors": [...],
  "notifiers": [...]
}

So simple 😊!

5. Start our chain!

Now we just need to run our chain and see what happens. As simple as executing the following command:

npm start

If everything is correct, why wouldn’t it be, we will see the following message in our console:

> runnerty
info: RUNNERTY v3.0.0 RUNNING - TIME...: Thu Jan 14 2021 10:29:23 GMT+0100 (hora estándar de Europa central)
info: Successful access to runnerty.io (websockets)

In this base project, we have configured that every minute our workflow is executed, which in this case only shows a message by console, and we will be able to see how the values have been replaced.

info: 2021-01-14 10:30:00 START OF THE CHAIN: CHAIN_ONE
info: 2021-01-14 10:30:00 START: PROCESS PROCESS_ONE
info: 2021-01-14 10:30:00 END: PROCESS PROCESS_ONE

But, let’s see it on the platform, no more endless logs…

We will see each of the executions of our workflow. We have many interesting options that we will explain on another occasion, such as relaunching our workflow from the platform at any time or see the details of the execution.

6. Extra ball: Add a second process and visualize it in the platform.

We create a second process (copy the first one and change the id and name and add the property depends_process to indicate that it depends on the previous process. It’s that easy…

...
"processes": [
  {
    "id": "PROCESS_ONE",
    "name": "Process One",
    "exec": {...},
    "output": [...]
  },
  {
    "id": "PROCESS_TWO",
    "name": "Process 2",
    "depends_process": ["PROCESS_ONE"],
    "exec": {
      "id": "shell_default",
      "command": "echo Runnerty: Process 2 depends on process 1!"
    },
    "output": [...]
  }
]
...

🎉 We have created our first workflow with dependency between processes!

Now, if you take a look at the visualization of the string in the platform, you will see that dependency

Obviously, we are not squeezing the potential of Runnerty in this very basic example, but we can make workflows as complex as you are able to design.

Start delegating processes of your ecosystem to Runnerty and make it scalable and secure 🔥.

I encourage you to take a look and let me know what you think.

You can give your feedback in twitter or github ⭐️

#enjoy