Tasks
Schedule Task
Schedules actions to be run
Basic usage
The Schedule Task can be used to schedule actions to run at a future date. The schedule task works by setting triggers that fire at specific times, which then run the actions set to be run by the Schedule Task. For information on removing schedules click here.
Trigger Types
There are three types of triggers that can be set for a schedule:
- Cron Triggers - Expressed using a cron expression
- Once Triggers- Expressed using a SugarTime date and time
- Repeated Triggers- Similar to once triggers, but can fire multiple times
Example of how the task might look:
Parameters
schedule_name required string
The name of the schedule. There can only be one schedule on a stub with a specific name. If another schedule is set with the same name as a schedule that already exists on a stub, the newest schedule with that name will override the previous schedule.
description required string
The description of the schedule. The name and description of the schedule are shown in a comment on actions run by a schedule. Helps track the purpose of long-running schedules
remove_conditions optional array
An array of conditions, that when evaluated to true, will mark the schedule as completed. The remove conditions are evaluated before the schedule runs actions.
triggers required array
An array of trigger objects that will trigger the schedule to run actions. There are three different types of triggers: cron, once, and repeated. A trigger can only be of one type, but the trigger array can contain multiple triggers of different types.
Show child attributes
cron optional string
The cron expression for when the trigger is fired to run the schedule. Using this key will set the trigger to a cron trigger.
once optional string
A SugarTime date and time. The date and time can be relative, for example: 'in 5 hours', 'in 10 minutes'. The date and time can also be set to a specific date and time, for example: '2078-09-25 10:25' which will trigger at 10:25 on the 25th of September 2078. Using this key will set the trigger to a once schedule.
repeated optional string
A SugarTime date and time. The repeated takes the date and time in the same format as the once schedule. The only difference between a once and a repeated trigger is that a once only fires once whereas a repeated trigger can fire multiple times. The time and date for the next repeated to fire is based on the time and date that the previous repeated fired. For example: in 5 hours will fire the trigger 5 hours from the time it was created, the next repeated will then fire 5 hours after the first, etc.
expires_in optional string
A SugarTime date and time for when a trigger must expire and stop triggering the schedule. expires_in can be used for any type of trigger
run_count optional number
How many times the trigger must fire before it must stop triggering the schedule. run_count can be used with cron and repeated triggers.
actions required array
An array of actions that must be run when one of the triggers fires and activates the schedule.
Show child attributes
action_name required string
The name of the action to run.
data required object
The data to be passed to the action when it runs.
message required string
The stubpost message passed to the action when it runs.
stubref required string
The stubref where the action must be run.
Result
Properties
scheduleuuid
The scheduleuuid of the schedule to uniquely identify it.
schedule_name
The name of the schedule.
remove_conditions
The remove conditions of the schedule.
schedule_triggers
An array of the triggers of the schedule
Show child attributes
type
The type of the trigger either: cron, repeated or once
cron_expression
The cron expression of a cron trigger.
once_date
The date and time that the once trigger will fire.
repeat_date
The date and time that repeated trigger will first fire.
Remove Schedule
Schedules can be removed using either their schedule_name or their scheduleuuid. When a schedule is removed, it, as well as all of its triggers, are marked as completed.
Removing Schedule using schedule_name
It is possible to remove a schedule using the name of the schedule if done so on the stub that created the schedule. It is not possible to remove a schedule using the schedule_name of a schedule that was created on a different stub.
Removing Schedule using scheduleuuid
It is possible to remove a schedule using the schedule's scheduleuuid