TaskManager

TaskManagers are used for all the scripted functionality in dcafs. The language chosen for this is XML given that the syntax based on nodes corresponds well to the nature of the script.

Glossary

• task: a single action to execute, once or an (un)limited amount of times
• taskset: an amount of tasks grouped together
• state: the way to describe the current situation of an object for example schip:sea, ship:harbor, ship:docked
• flag: similar to a state but only has two options, a flag can be raised or lowered
• XML
  • node: structure <node>value </node>
  • attribute:

Usage

Telnet

Global commands

• tm,addblank,id Create an empty taskmanager and script
• tm:reloadall Reload all the taskmanagers
• tm:stopall Stop all the taskmanagers
• tm:list Get a list of currently active TaskManagers
• tm:remove,x Remove the manager with id x
• tm:x,y Send command y to manager x, options for y:
  • reload/reloadtasks -> reload the associated xml file
  • listtasks -> give a listing of all the loaded tasks
  • listsets -> give a listing of all the loaded tasksets
  • states -> get a listing of all the current states
  • stop -> cancel all active and scheduled tasks.";

Creating a script

The general structure of a script is as follows:

<tasklist> 
      <tasksets>
            <!-- add sets of tasks here -->
      </tasksets>
      <tasks>      
            <!-- add single tasks here -->
      </tasks>
</tasklist>

Taskset

Multiple tasks can be grouped together to form a set. At the moment there are two ways iterating through the set, namely oneshot and step. The first one means that all the tasks in the set will be started at the same time, the second one that execution of one task will initiate the following.

The minimum format of a taskset is as follows:

<taskset info="Longer descriptive name for the set" id="taskset_id" >
	<task></task> 
</taskset>

Possible attributes

• name : descriptive name for the taskset, used in telnet for representation
• id : the reference to use in other tasks to execute it
• run : how the taskset should be executed, options:
  • oneshot -> default, all planned at once
  • step -> step by step, if a step fails the taskset is stopped
  • no -> meaning it's a collection of tasks not used to run as a set
• repeat: how many time the taskset should be executed, default is 1, -1 means infinite.
• failure: only usable when run="step", this will run another taskset if this one failed

Task

A task is a single XML node with multiple attribute options, and a value that depends on those attributes.

Short summary of the attributes.

The standard attributes:

• output: where should the result of the task go
  • stream: to a device eg. output="stream:SBE38" this must match the title given to it in the settings file
  • email: to an email address/ref eg.output="email:admin" (requires a EmailWorker to be active)
  • sms: to an cellphone number eg. output="sms:admin" (requires a DigiWorker to be active)
  • manager: to run a command that affects the manager that runs this task
  • system: to run a telnet command
  • log: to write the result to the logs eg. output="log:info"
  • file: to write the result to a given file
• trigger: what should be the trigger for this task to be run
  • time: at which UTC time and day(s) should the task run eg. trigger="time:14:00,mo" is monday at 14:00
  • localtime: at which local time should the task run
  • delay: amount of time to run after the task is called eg. trigger="delay:2m10s" after 2 minutes and 10 seconds
  • interval: run continuously at a set interval with optional initial delay eg. trigger="interval:10s,5s" run every 10s after 5s initial delay (default is initial delay=interval)
  • retry: try to run (requirement must be met) at a set interval and amount of max attempts eg. trigger="retry:10s,5"
  • while:

The optional attributes:

• req: a requirement that must be fullfilled before a task is executed
• check: a check that is run to verify that the task was executed properly
• reply: when the output is a device, this reply is expected
• attachment: used when the output is email, this defines a file to attach
• state: this task will only be run if the given state is active
• id: give an id to this task, only used for the link attribute
• link: links this task with another one eg. link="nottoday,taskid"
  • nottoday : the given task can't be triggered today
  • disable24h : the given task can't be triggered in the next 24 hours
  • donow : the given task will be triggered now
  • skipone : the next trigger for the given task will be ignored, but subsequent ones will be executed

<!-- some simple examples -->
<task output="system" trigger="delay:5s" >command</task>
<task output="email:admin" >The header of the email;the body</task>

The value

In the earlier examples, 'command' and 'The header of the email;the body' are considered the value of the task. How this should be constructed depends on the output but for the outputs system, stream, email there are a couple of macro's (meaning these words will be replaced at runtime).

• {localtime} -> replaced with the localtime in HH:mm format
• {utcstamp} -> replaced with the utc time in format dd/MM/YY HH:mm:ss
• {localstamp} -> replaced with the local time in format dd/MM/YY HH:mm:ss
• {ipv4:interface} -> replaced with the ipv4 address of the given interface
• {ipv6:interface} -> replaced with the ipv6 address of the given interface
• {mac:interface} -> replaced with the mac address of the given interface
• {rand6},{rand20},{rand100} -> replaced with a random number in the given range

Attributes in detail

Some of the attributes need a bit more information.

Output

As the name implies this element determines what should be done with the result of the task. This element can be further split up in: email, file, SMS, system, stream and log.

Stream

Allows the value of the task to be streamed to the chosen device. The specified channel must match the title of the stream. Furthermore, if multiple items need to be send these can be given separated with ;. If no reply is given, these will be send with an interval of 3 seconds otherwise as soon as the reply is received.

This looks for the attribute reply to see what should be the reply given by the device. How the reply works:

• the data is send and the handler informed about the expected reply
• the handler expects a the reply within five seconds by default
• if no reply is received within those five seconds a resend is done
• after five resends the tasks stops trying and is considered failed

Note: The data send can be requested in the reply by putting **. So if 'GO 1' is send to the device and the reply is 'Go 1:ok' then use reply="**:ok".

So when combining the above, if you send Go 1;Go 2;Go 3 and set reply to **:ok this will result in the following:

1. Send 'Go 1' wait up to five seconds for 'Go 1:ok'. If received go to 2 else try again (up to five times).
2. Send 'Go 2' wait up to five seconds for 'Go 1:ok'. If received go to 3 else try again (up to five times).
3. Send 'Go 3' wait up to five seconds for 'Go 1:ok'. If received go to next task else try again (up to five times).

Note: The 'go to next task' is only if inside a taskset with the runtype 'step', mor info on this in the taskset part of the manual.

Email

The email address or reference to send to, a reference needs to be defined in the emailbook node of the settings.xml (see related topic).

As an extra attribute attachment can be specified. This is the filename of the attachment to add to the email. Standard datetime elements can be used between [ and ] brackets to add current datetime to the filename. So attachment="log_[ddMMyy].log" will send the file with todays date. If the attachment is missing, this will be noted in the email. By default, these follow the same zip rules as regular emails.

The value should be consisting of two parts separated with ;. The first half is the title of the email, while the second one is either the body or a (telnet) command which result will be the body.

SMS

The cellphone number or reference to send to, a reference needs to be defined in the smsbook node of the settings.xml (see related topic). The value isn't split into multiple messages, so the user needs to take care of this.

Manager

Commands that affect the TaskManager itself, for now this is limited to mainly setting and removing flags. These flags are stored in the same structure as the states. So a list can be requested by sending tasks:states command.

Commands

• raiseflag:flagname: set a flag with the given name, this can be used in the req attribute;
• lowerflag:flagname: remove the flag with the given name.
• start:tasksetid: start the taskset with the given short.
• stop:tasksetid: stop the taskset with the given short.
• tasksetid:taskid: Start a task in a taskset.

System

Allows all the commands available in the telnet interface to be executed from the TaskManager.

Log

Allows the value to be written to the logger.

Options are:

• info : Logged to the info.log, nothing else is done
• warn : Logged to the warn.log but nothing else
• error : Logged to the error.log and an email is send to admin

File

The file to which the result of the value should be written to. The value can, in addition to the @ options (see below), contain [EOL] as a means to add the system specific end of line characters.

Trigger

As the name implies this element determines when the task should be executed. This element can be further split up in: time, interval/retry, travel and delay.

Time

This allows tasks to be executed at a specific time (based on the PC clock as timebase) in 24h notation.

• time or utctime: The task will be executed at the specified UTC time
• localtime: The task will be executed ate the specified local time

By default, tasks are only executed on weekdays. If execution is required on a specific day, then this needs to be appended.

• Append the first two letters of the day(s) to the trigger
• Append the full day to the trigger

Examples:

• trigger="time:08:00" -> the task will run every weekday at 08:00 UTC
• trigger="localtime:08:00" -> the task will run every weekday at 08:00 localtime
• trigger="time:08:00,motu" -> the task will run on monday and tuesday at 08:00 UTC
• trigger="time:08:00,monday" -> the task will run on monday at 08:00 UTC

Interval

This allows tasks to be continuously executed based on a specified interval and after an initial delay. The format of both periods can be specified in any timebase of atleast a second.

For example, to execute an action every 70minutes you could use either 70m or 1h10m or even 4200s. This also applies to the initial delay.

Examples:

• trigger="interval:10s,5m" -> the task will run after 10s and then every following 5 minutes
• trigger="interval:5m" -> the task will run 'now' and then every following 5 minutes
• trigger="interval:1h2m15s" -> the task will run 'now' and then every following 1 hour 2 minutes and 15 seconds

Delay

Mainly used for tasksets, this causes a single execution of the task after the delay has passed since the initialization. Delay can be specified in following formats: 5min,5sec,5m10s,3h5m4s etc

Examples:

• trigger="delay:0s" -> the task will run 'now', this is the default if no trigger was given
• trigger="delay:10s" -> the task will run after a 10 seconds delay

Travel

In the settings.xml, travel to/from a waypoint can be determined. This movement can also be used as a trigger.

Example:

• trigger="travel:leavedock" -> the task will run if this travel occurred

Retry

Variant of the 'interval' trigger, difference being that the repetitions can be limited. Just as 'interval' the task is tried on a set interval but stopped once it is executed (meaning requirements were fulfilled). The first variable defines the interval and the second one the retries, the latter can be -1 for infinite, 0 for once (no retries) or any higher number for the attempts made. If the max repetitions were made and the req is still not fulfilled, the takset will be considered failed.

Examples:

• trigger="retry:10s,-1" -> the task will be tried every 10 seconds till execution
• trigger="retry:10s,5" -> the task will be tried every 10 seconds till execution or five attempts were made

While

If a situation requires something to be true for a certain amount of time before doing something and only if then. Just like retry an interval and a run count should be provided. So this trigger has a really specific use case and is better explained with an example.

Below is the TaskSet for a solenoid that can't be on for longer than 40 minutes (those things heat up). The TaskSet is part of the alarms script, so the execution is based on source code.

<taskset name="solenoid 1 on" run="step" id="sols.sol1:start">
  <!-- A task with the while-trigger doesn't need an output nor a  value -->
	<task trigger="while:4m,10" req="issue:sols.sol1 equals 1"></task><!-- Check every 4 minutes if the solenoid is on and do this 10 times -->
  <!-- If we get to this point, this means the solenoid was on during the full 40 minutes -->
  <!-- If the solenoid was turned off earlier, we never reach this point -->		
	<task output="stream:solenoid Control" reply="**:OK">C1</task> <!-- Send C1 turns to controller to turn solenoid 1 off -->
</taskset>

Req

Short for requirement, this can check up to two realtime values, flags or issues. If the requirement is not met, the task is not executed (but will be rescheduled if it is time based).

Possible values for req depends on the usage of RealtimeValues.

Possible operations

A maximum of two checks can be combined with the logical operators 'and' (&&) or 'or' (||).

These checks can be either a logical or mathematical operation. Logical

• above (>)
• below (<)
• equal (==)

Mathematical

• plus
• minus
• diff (minus and drop the sign)

Example:

• The task requires that there's a flow of more than 0,5l and the temperature from sensor1 (S1temp) and sensor2 (S2temp) are within 0.4° of eachother.
  • Attribute: req="S1temp diff S2temp below 0.4 and waterflow above 0.5"
  • In java code: Math.abs( S1temp – S2temp) < 0,4 && waterflow > 0.5

Check

Same as req except that the verification is done after the task has run. Meaning you could have the task do something and then check if this has actually been executed. Do note, that for now, there is no time delay between execution and verification. This means that it is likely that the task will be executed twice if retry trigger is used.

Link

When the id of a task is known, it can be controlled through another task when the controlling task is executed. The ways of controlling a task are for now limited to the execution of it.

• nottoday : the task can't be triggered today
• disable24h : the task can't be triggered in the next 24 hours
• donow : the task will be triggered now
• skipone : the next trigger will be ignored, but subsequent ones will be executed

Example:

• <task output="log:info" id="task1" link="nottoday:task2" trigger="time:08:00" req="temperature below 10">It's cold</task> If the temperature is below 10°C at 08:00 don't execute task2 today.

Note: the controlled task doesn't have to be another task, this can also be used to have a task that might trigger twice in a day limited to only once.