How to create a Heron job

Step by step, create the first job and run it
iot heron tech

How to create your first Heron job

Let’s take a practical approach; fire up the following command:

heron -e

You will get the following prompt. You can follow the example step by step.

heron -e
Insert job name:
FirstJob

-------------
x to exit
a to add task
a

Insert task name:
FirstTask

Insert task type:
listDirectory

-------------
x to exit
a to add param
a
Insert Parameter Name:
mydir

Insert Parameter Value:
/tmp


-------------
x to exit
a to add param
x

-------------
x to exit
a to add task
x

From this dialogue, you have created a definition for the job

FirstJob

that is composed by one task of type:

listDirectory

You also gave a name to the task (FirstTask) that should be descriptive of what you want to achieve with the task in the current job definition.

The task that we have here as a type should either exist, or should be created. In our example, we will create the task, in order to show how easy it can be. Let’s remember that our task is expecting a single parameter called:

mydir

The task is made up by a shell script named as the task type and ubicated in the following directory:

$HOME/.heron/tasks

You can create it if it does not exist yet. Going on with our example let’s have the task defined as such:

cat $HOME/.eron/tasks/listDirectory
#! /bin/bash

echo "Start task"
ls __mydir__

As you can see, it is just a shell script with arbitrary commands. The parameters that the heron job is passing to the task will be expanded so that, in our case

 __mydir__ 

will be replaced by:

/tmp

That is true for any number of parameters defined in the main job, and as many times as needed by the task definition.

Ok, while the tasks are somewhat obvious at this point (they are just shell scripts templates that get preprocessed and get the parameters expansion). We can take a look at what the Job actually looks like.

When we edited the job throug

heron -e

we just created the definition of the job in a local database that helps us to keep track of the operations that we do. The “rule of the game” is that a job is a json file containing the sequence of the tasks and the actual parameters.

In order to create our first job from the definition that we edited so far, we can do like that:

heron -O FirstJob

and it will output to the screen what follows:

{"name": "FirstJob", "tasks": [{"name": "FirstTask", "type": "listDirectory", "params": {"mydir": "/tmp"}} ]}

The json format is easy enough to manipulate, that it should be possible to edit and create by hand. Of course, there are tools provided to create it, and you can integrate it with some other tool of your own, not a big issue.

Let’s save this job definition on a file:

heron -O FirstJob > /tmp/my-first-job.json

we can now execute the job by issuing the command:

heron -X /tmp/my-first-job.json

That’ll give you some noisy output like:

Retrieving task [listDirectory]
Task [listDirectory] already present
Input file is: [/tmp/my-first-job.json]
FSM name: [FirstJob]
param:mydir value:/tmp
workdir:[/tmp/6e35c81a-a972-11e8-8172-f48c5092b6ca]
START task: [listDirectory]
STOP task: [listDirectory]

If you want to see what has happened for real, you can go to the declared workdir:

cd /tmp/6e35c81a-a972-11e8-8172-f48c5092b6ca

and see the content of the script that has been launched :

cat ./0000_listDirectory.sh
cat 0000_listDirectory.sh 
#! /bin/bash

echo "Start task"
ls /tmp

Under the log subdir you will find log files named after each of the task that you run. For our simple example it look like this:

./log/0000_listDirectory.sh.log