sympa-community.github.io

Incubating the new Sympa documentation site

Tasks

Definition

A task is a sequence of simple actions which realize a complex routine. It is executed in the background by the task manager daemon and allows listmasters to automate the processing of recurring tasks. For example, a task sends to a list’s subscribers a message to remind them of their subscription on a yearly basis.

A task is created with a task model. It is a text file which describes a sequence of simple actions. It may have different versions (for instance reminding subscribers every year or semester). A task model file name has the following format: <model name>.<model version>.task. For instance remind.annual.task or remind.semestrial.task.

Sympa provides several task models stored in the $DEFAULTDIR/tasks directory. Others can be designed by listmasters.

A task can be either global or related to a list.


Note:


Basics

Though you can freely modify the content of any model task and create as much versions of each model as you need, there is no simple way to add a new model name.

This is due to the fact that, in order to use a task (whatever its focus is, global or list related), you must:

Both the model name and the parameter are hard-coded in Sympa for each task model. Consequently, if you want to create a brand new task model (and not a new version of an existing model), you must modify Sympa to add this new task and its associated parameter.

Note: confusing denominations

Two different objects used by the task manager can have the same name;

These are two completely different things but for historical reasons some have exactly the same name. For example there is a model name called sync_include AND a command called sync_include(). You can call the sync_include() command inside the sync_include model but you don’t have to.

Paradoxically, you can perfectly create a task model called sync_include which will never call the sync_include() command. For your own good, though, you shouldn’t.

Creating tasks

As stated above, tasks can be either global or list-related. Both these focus have their own tasks models. We will present here, for each one, the location of the task model files, the name of the model to be used as well as their common signification, and the parameters defining which version of the model will be used.

List task creation

List model paths

You define in the list configuration file the model and the version you want to use. Then the task manager daemon will automatically create the task by looking for the appropriate model file in different directories in the following order:


Note:


List model names

You can use two model names in your list task model files :

List model version definition parameters

List tasks are defined through specific parameters in the config file. As of this writing, the following parameters are available :

Global task creation

Global model paths

The task manager daemon checks if a version of a global task model exists in different directories in the following order:


Note:


Global model names

You can use the following model names for global tasks. The description below corresponds to the default action of these tasks. By modifying these files, you will alter the actions performed:

See the synonyms commands below. These models are usually employed to apply these commands.

Global model version definition parameters

The version of a global model to be used is specified in sympa.conf. These are the parameters you can set in this configuration file:

The sync_include model is an exception, as it doesn’t have a single dedicated configuration parameter.

The sync_include task

An exception in the realm of tasks in Sympa, the sync_include task accepts one and only one model : sync_include.ttl.task. It’s useless to try and create other versions of this task, they will be ignored. There exist a configuration parameter related to sync_include, though, but it doesn’t set the model used. It is the ttl parameter. It will just set the length of time between two synchronizations.

Model files constitution

This section describes what you can write in your model files and how to define the action processed during tasks implementation.

Model file format

Model files are composed of comments, labels, references, variables, date values and commands. All those syntactical elements are composed of alphanumerics (0-9a-zA-Z) and underscores (_).

Here is the list of the currently available commands:

Model files may have a scenario-like title line at the beginning.

When you change a configuration file by hand, and a task parameter is created or modified, it is up to you to remove existing task files in the task/ spool if needed. Task file names have the following format:

<date>.<label>.<model name>.<list name | global> where:

Model file examples

You will find plenty of examples in the $DEFAULTDIR/tasks directory. Such examples look like:

title reminder message sent to subscribers weekly

/INIT
next([execution_date] + 1w, EXEC)

/EXEC
@selection = select_subs (older([execution_date]))
send_msg (@selection, remind)
next([execution_date] + 1w, EXEC)

CC BY-SA 4.0 Unless otherwise specified, the contents of this document are licensed under the Creative Commons - Attribution - ShareAlike license. For more details see LICENSE and AUTHORS.

Theme originally designed by orderedlist