Contents
Introduction
This page describes how Tachyon instructions can be set up to execute on the schedule.
You should also read Issue an instruction, track its progress and retrieve responses page, which covers tracking instruction's progress, retrieving responses and the like, because here we will only focus on the scheduling aspect.
The C# examples assume you’re using Tachyon Consumer SDK and you already have a correctly instantiated instance of Tachyon connector class in an object called connector.
All SDK methods return the same class called ApiCallResponse. Inside the object of ApiCallResponse you'll find a property called ReceivedObject. That object is the actual data received from the API. In the following examples this detail is left out, stating that the returned object contains the data. For example, when we say that XYZ object contains certain data, this means the ReceivedObject contains that data, since that's always true.
What is a "scheduled instruction"
A "scheduled instruction" is a regular Tachyon instruction definition that has been configured to execute periodicaly on a specific schedule.
When a schedule is set up, you define the instruction as you would normally (see Issue an instruction, track its progress and retrieve responses), with parameters, scope etc. and add information about the schedule.
When the time comes to execute the schedule, Tachyon will issue a new copy of the instruction. This will be a carbon copy of the instruction that was scheduled - all fields will be copied, including auxiliary ones like Comments and ConsumerCustomData. This means that each copy of the instruction issued on a schedule will have the same parameters, the same scope or target devices etc.
Creating a schedule
To create a schedule you have to provide the template for the instruction that will be issued when the schedule is triggered and information about the schedule itself.
It is worth noting that creating a schedule will not result in an instruction being issued immediatelly. This is because instructions are issued only when a schedule is triggered.
A schedule should be created with care as it is possible to create one that will flood the system with requests. It is not advised to create a schedule where a new instruction is issued before the previous' ones instruction ttl expires.
Because Tachyon's scheduling mechanism is relatively simple, if you require features like variation in instruction parameters or targeting between instructions triggered on a schedule, you might want to look at implementing scheduling yourself and issuing regular instructions instead.
Core of the scheduled instruction
The core of the scheduled instruction is much the same as a regular instruction, as seen in Issue an instruction, track its progress and retrieve responses.
Each instruction issued on the schedule will be a copy of the instruction provided when a schedule is created.
Scheduling properties
Schedule properties with the exception of ScheduleEnabled are based on Microsoft SQL Server system schedules as described in details here: https://docs.microsoft.com/en-us/sql/relational-databases/system-tables/dbo-sysschedules-transact-sql?view=sql-server-ver15
| Schedule property name | Microsoft SQL column name | Description | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ScheduleEnabled | enabled | This field defined if a schedule is enabled or not. Schedules that are not enabled will not be executed. If a schedule is enabled after some of the occurrences should have happened, the schedule will resume from the next scheduled occurence and will not "catch up". | ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqType | freq_type | How frequently a job runs for this schedule.
| ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqInterval | freq_interval | Meaning of the value of this fields depends on the value of ScheduleFreqType.
For example, if you wanted to set the schedule up to activate every day of the week the value of ScheduleFreqInterval would be 127. If you only wanted the schedule to activate on Mondays and Fridays it would be 34.
| ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqSubdayType | freq_subday_type | Units for the ScheduleFreqSubdayInterval.
| ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqSubdayInterval | freq_subday_interval | Number of ScheduleFreqSubdayType to occur between each activation of the schedule. | ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqRelativeInterval | freq_relative_interval | If ScheduleFreqInterval is set to 32 this property can have one of following values:
If ScheduleFreqInterval is set to any other value this field is ignored. | ||||||||||||||||||||||||||||||||||||||
| ScheduleFreqRecurrenceFactor | freq_recurrence_factor | Number of weeks or months between the activation of the schedule. ScheduleFreqRecurrenceFactor is used only if ScheduleFreqType is set to 8, 16, or 32. If this column contains 0, ScheduleFreqRecurrenceFactor will not be used. | ||||||||||||||||||||||||||||||||||||||
| ScheduleActiveStartDate | active_start_date | Date on which the schedule should begin formatted as YYYYMMDD | ||||||||||||||||||||||||||||||||||||||
| ScheduleActiveEndDate | active_end_date | Date on which the schedule should finish formatted as YYYYMMDD | ||||||||||||||||||||||||||||||||||||||
| ScheduleActiveStartTime | active_start_time | Time between ScheduleActiveStartDate and ScheduleActiveEndDate which will be used as starting time for the schedule exexution on a given day. Time is formatted HHMMSS, using a 24-hour clock. | ||||||||||||||||||||||||||||||||||||||
| ScheduleActiveEndTime | active_end_time | Time between ScheduleActiveStartDate and ScheduleActiveEndDate which will be used as stopping time for the schedule exexution on a given day. Time is formatted HHMMSS, using a 24-hour clock. |
A schedule can be created disabled by setting the ScheduleEnabled property to false. This will mean that it will not be triggered and no instructions will be issued until the schedule is enabled. If the schedule is enabled at a point in time where it would have already missed some activations, it will simply resume from the next scheduled activation. For example, if on Monday morning you create a disabled schedule that is meant to trigger every day at mid day and then go ahead an enabled it on Wednesday at 5pm, the next triggered activation will be on Thursday at mid day, and the schedule would have "missed" activations on Monday, Tuesday and Wednesday because it was disabled. This means that an instruction will be issued at mid day Thursday, but there will be no instructions for Monday, Tuesday or Wednesday.
Managing schedules
Retrieving all schedules
Retrieving all past and planned instructions for a specific schedule
Lifecycle of a schedule
Create a new schedule
Modifying and cancelling a schedule
Example schedules
In this section we will look at several schedules. We will focus on the scheduling properties of the payload for brevity and assume each schedule issues the same instruction.