Scheduled task templates (CRON jobs)

Tasks can be scheduled. These regular jobs (CRON) can follow any pattern: every Monday at 13:12, MON - WED, every 3 minutes, etc.

Schedules are setup via API. You find details here:

https://apps.babelforce.com/developer-hub/task-automation-task-schedule-api/

POST a new scheduled task

These are the parameters that should be set to schedule a reoccurring task:

cron: defines the algorithm which will be explained with examples and a table below
name: any name for scheduled task
task: if no template is referenced, add the task here. If a template is referenced, leave empty.
template_id: use name of the template that should be scheduled if you didn't define a task.
template_style: leave it as "hierarchy"
timezone: if left empty, the time zone will be UTC. Summer and winter time will not be considered. Otherwise, select a "TZ identifier", such as "Africa/Bamako". Find the list here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

How to set the CRON expression

For the syntax of CRON expressions, babelforce refers to the Quartz documentation. For a detailed understanding, we suggest to read the documentation carefully. In this article, we can only give a brief introduction.

A Quartz CRON expression needs 6 elements and may optionally have a 7th element (see example 3 in the table below).

Be aware, you can only use either ‘Day of month’ or ‘Day of week’ in an expression, not both. The one not used must be represented as ‘?’.

#	Description	Second	Minute	Hour	[Day of month]	Week	[Day of week]	(Year)
1	Every 10 seconds	*/10	*	*	*	*	?
2	At the 30th second of every 5 minutes	30	*/5	*	?	*	*
3	Every second of the 12th hour of the day of 1970	*	*	*/12	?	*	*	1970
4	Every first day of the month at 10am	0	0	10	1	*	?
5	Every working day MON to FRI at noon	0	0	12	*	*	MON-FRI
6	Last day of the year at 23:59:59	59	59	23	31	52,53	?
7	Every Sunday at noon	0	0	12	?	*	1
8	Only on the third Friday of the month at 17:30	0	30	17	?	*	6#3

As example 1 above shows, using a * is representing "always". If Minute = *, the task will run every minute. */10 on the other hand means every 10 seconds.

A very common example is number 5: Once per day, in this example at 12:00 (noon), Monday through Friday, a task is scheduled.

Be careful when scheduling a CRON job. Make sure to monitor after setting it up to ensure it indeed runs as expected. It will not stop automatically unless you schedule it in a specific year. Please use the Task usage overview to check that the scheduled task behaves as expected. Unexpected behavior might be seen if tasks are running too often/ too fast.

Finding the template id

In the babelforce manager, go to Automations > Task Automations and select the template that should be scheduled. in the header, you find the template id. In the example below it is sync.agent.

Example of a repeated task

In the example below, we schedule a task, every day at 17:00 in the time zone of Bangkok. For the name of the task we decided to take the same as for the teamplate_id.

curl -X 'POST' \
  'https://{env}.babelforce.com/api/v3/tasks/schedules' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "cron": "0 0 17 * * ?",
  "name": "sync.agents",
  "task": {},
  "template_id": "sync.agent",
  "template_style": "hierarchy",
  "timezone": "Asia/Bangkok"
}'

Retrieving, editing and deleting tasks

Below, you see the CURL for retrieving all reoccurring scheduled tasks in your account:

curl -X 'GET' \
  'https://{env}.babelforce.com/api/v3/tasks/schedules' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}'

Be aware: you cannot edit a scheduled task. You have to delete and re-schedule it. This is how to delete a task:

curl -X 'DELETE' \
  'https://{token}.babelforce.com/api/v3/tasks/schedules/sync.agent' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer{token}'

Related to

task automation