Version: 4
restore

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 nameMicrosoft SQL column nameDescription
ScheduleEnabledenabledThis 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".
ScheduleFreqTypefreq_type

How frequently a job runs for this schedule.

  • Value of 1 means only there will be only one activation of this schedule so only one instruction will be issued
  • Value of 4 means daily activation
  • Value of 8 means weekly activation
  • Value of 16 means monthly activation
  • Value of 32 means monthly activation relative to ScheduleFreqInterval
ScheduleFreqIntervalfreq_interval

Meaning of the value of this fields depends on the value of ScheduleFreqType.

  • If ScheduleFreqType is set to 1 (one activation of the schedule), this field is not used and should have the value of 0
  • If ScheduleFreqType is set to 4, this field will have the number of days between activations of the schedule. For example, to make a schedule activate every day, set this to 1. To do it every other day, set it to 2.
  • If ScheduleFreqType is set to 8, this field becomes a bit flag that contains information on which days of the week the schedule should be activated. The values are as follows:
DayValue
Sunday1
Monday2
Tuesday4
Wednesday8
Thursday16
Friday32
Saturday64

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.

  • If ScheduleFreqType is set to 16, the value of this field will be the number of the day of the month on which the schedule will be activated.
  • If ScheduleFreqType is set to 32, this propert will have one of following values:
DescriptionValue
Sunday1
Monday2
Tuesday3
Wednesday4
Thursday5
Friday6
Saturday7
Day8
Weekday9
Weekend day10
ScheduleFreqSubdayTypefreq_subday_typeUnits for the ScheduleFreqSubdayInterval.
  • Value of 1 means activate at the specified time
  • Value of 2 means the unit is Seconds
  • Value of 4 means the unit is Minutes
  • Value of 8 means the unit is Hours
ScheduleFreqSubdayIntervalfreq_subday_intervalNumber of ScheduleFreqSubdayType to occur between each activation of the schedule.
ScheduleFreqRelativeIntervalfreq_relative_interval

If ScheduleFreqInterval is set to 32 this property can have one of following values:

DescriptionValue
ScheduleFreqRelativeInterval is not used0
First1
Second2
Third4
Fourth8
Last16

If ScheduleFreqInterval is set to any other value this field is ignored.

ScheduleFreqRecurrenceFactorfreq_recurrence_factorNumber 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.
ScheduleActiveStartDateactive_start_dateDate on which the schedule should begin formatted as YYYYMMDD
ScheduleActiveEndDateactive_end_dateDate on which the schedule should finish formatted as YYYYMMDD
ScheduleActiveStartTimeactive_start_timeTime 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.
ScheduleActiveEndTimeactive_end_timeTime 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

In this section we will learn how to examine what schedules are available, how to create, modify and cancel them and how to see what instructions will be issued by a schedule.

Retrieving scheduled instructions

To retrieve all scheduled instructions (but not instructions issued by schedules) you should use the https://my.tachyon.server/Consumer/ScheduledInstructions endpoint.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to https://my.tachyon.server/Consumer/ScheduledInstructions will yield following response:

Return payload
[
    {
        "Id": 1,
        "Name": "1E-Explorer-TachyonAgent-Echo",
        "Cmd": "SendAll",
        "KeepRaw": true,
        "Scope": null,
        "ReadableScope": null,
        "InstructionTtlMinutes": 60,
        "ResponseTtlMinutes": 120,
        "CreatedTimestampUtc": "2019-12-06T10:53:31.903Z",
        "Export": false,
        "ExportLocation": null,
        "ParentInstructionId": null,
        "InstructionDefinitionId": 23,
        "CreatedBy": "SomeDomain\\Jane.Doe",
        "ResultsFilter": null,
        "PreviousResultsFilter": null,
        "Devices": null,
        "ConsumerId": 1,
        "ConsumerName": "Explorer",
        "ConsumerCustomData": null,
        "ParameterJson": "[{\"Name\":\"msg\",\"Pattern\":\"%msg%\",\"DataType\":null,\"ControlType\":null,\"ControlMetadata\":null,\"Placeholder\":null,\"DefaultValue\":null,\"Validation\":null,\"Value\":\"Machine reporting\",\"HintText\":null,\"Source\":null}]",
        "OffloadResponses": false,
        "RequestedFor": null,
        "Comments": "Reporting machine echo",
        "ActionedBy": "Ollanius Pius",
        "ActionReason": null,
        "Status": 7,
        "StatusTimestampUtc": "2019-12-10T13:24:35.917Z",
        "Workflow": "{\"StateMachine\":\"Scheduled Instruction State with Authentication and Approval\",\"Authenticating\":\"Scheduled Instruction Authentication\",\"Approval\":\"Scheduled Instruction Approval\",\"InProgress\":\"Scheduled Instruction InProgress\",\"Cancelling\":\"Scheduled Instruction Cancelling\"}",
        "WorkflowState": 8,
        "ApprovalOffloaded": false,
        "ReadablePayload": "Echo message %msg%.",
        "ScheduleEnabled": true,
        "ScheduleFreqType": 4,
        "ScheduleFreqInterval": 1,
        "ScheduleFreqSubdayType": 8,
        "ScheduleFreqSubdayInterval": 12,
        "ScheduleFreqRelativeInterval": 0,
        "ScheduleFreqRecurrenceFactor": 0,
        "ScheduleActiveStartDate": "2019-12-06T00:00:00Z",
        "ScheduleActiveEndDate": "2019-12-09T00:00:00Z",
        "ScheduleActiveStartTime": 120000,
        "ScheduleActiveEndTime": 120000,
        "ScheduleLastExecuted": null,
        "ScheduleNextExecution": null,
        "ScheduleReadableFrequency": "Occurs every 1 day(s) every 12 hours starting at 12:00:00 ending at 12:00:00 starting on 06/12/2019 ending on 09/12/2019"
    },
    {
        "Id": 2,
        "Name": "1E-Explorer-TachyonAgent-Echo",
        "Cmd": "SendAll",
        "KeepRaw": true,
        "Scope": null,
        "ReadableScope": null,
        "InstructionTtlMinutes": 60,
        "ResponseTtlMinutes": 120,
        "CreatedTimestampUtc": "2019-12-10T13:04:06.6Z",
        "Export": false,
        "ExportLocation": null,
        "ParentInstructionId": null,
        "InstructionDefinitionId": 23,
        "CreatedBy": "SomeDomain\\Jane.Doe",
        "ResultsFilter": null,
        "PreviousResultsFilter": null,
        "Devices": null,
        "ConsumerId": 1,
        "ConsumerName": "Explorer",
        "ConsumerCustomData": null,
        "ParameterJson": "[{\"Name\":\"msg\",\"Pattern\":\"%msg%\",\"DataType\":\"string\",\"ControlType\":\"freeText\",\"ControlMetadata\":null,\"Placeholder\":\"message to echo\",\"DefaultValue\":null,\"Validation\":{\"Regex\":null,\"MaxLength\":\"200\",\"AllowedValues\":null,\"NumValueRestrictions\":null},\"Value\":\"echo echo echo\",\"HintText\":null,\"Source\":null}]",
        "OffloadResponses": false,
        "RequestedFor": null,
        "Comments": null,
        "ActionedBy": "Ollanius Pius",
        "ActionReason": null,
        "Status": 7,
        "StatusTimestampUtc": "2019-12-12T13:27:57.5Z",
        "Workflow": "{\"StateMachine\":\"Scheduled Instruction State with Authentication and Approval\",\"Authenticating\":\"Scheduled Instruction Authentication\",\"Approval\":\"Scheduled Instruction Approval\",\"InProgress\":\"Scheduled Instruction InProgress\",\"Cancelling\":\"Scheduled Instruction Cancelling\"}",
        "WorkflowState": 8,
        "ApprovalOffloaded": false,
        "ReadablePayload": "Echo message %msg%.",
        "ScheduleEnabled": true,
        "ScheduleFreqType": 1,
        "ScheduleFreqInterval": 0,
        "ScheduleFreqSubdayType": 0,
        "ScheduleFreqSubdayInterval": 0,
        "ScheduleFreqRelativeInterval": 0,
        "ScheduleFreqRecurrenceFactor": 0,
        "ScheduleActiveStartDate": "2019-12-10T00:00:00Z",
        "ScheduleActiveEndDate": "2019-12-11T00:00:00Z",
        "ScheduleActiveStartTime": 142000,
        "ScheduleActiveEndTime": 140200,
        "ScheduleLastExecuted": "2019-12-10T14:20:00Z",
        "ScheduleNextExecution": null,
        "ScheduleReadableFrequency": "Occurs once on 10/12/2019 at 14:20:00"
    },
    {
        "Id": 3,
        "Name": "1E-Explorer-TachyonAgent-Echo",
        "Cmd": "SendAll",
        "KeepRaw": true,
        "Scope": null,
        "ReadableScope": null,
        "InstructionTtlMinutes": 60,
        "ResponseTtlMinutes": 120,
        "CreatedTimestampUtc": "2019-12-10T13:06:47.78Z",
        "Export": false,
        "ExportLocation": null,
        "ParentInstructionId": null,
        "InstructionDefinitionId": 23,
        "CreatedBy": "SomeDomain\\Jane.Doe",
        "ResultsFilter": null,
        "PreviousResultsFilter": null,
        "Devices": null,
        "ConsumerId": 1,
        "ConsumerName": "Explorer",
        "ConsumerCustomData": null,
        "ParameterJson": "[{\"Name\":\"msg\",\"Pattern\":\"%msg%\",\"DataType\":\"string\",\"ControlType\":\"freeText\",\"ControlMetadata\":null,\"Placeholder\":\"message to echo\",\"DefaultValue\":null,\"Validation\":{\"Regex\":null,\"MaxLength\":\"200\",\"AllowedValues\":null,\"NumValueRestrictions\":null},\"Value\":\"echo echo echo\",\"HintText\":null,\"Source\":null}]",
        "OffloadResponses": false,
        "RequestedFor": null,
        "Comments": null,
        "ActionedBy": "Ollanius Pius",
        "ActionReason": null,
        "Status": 7,
        "StatusTimestampUtc": "2019-12-12T13:27:59.543Z",
        "Workflow": "{\"StateMachine\":\"Scheduled Instruction State with Authentication and Approval\",\"Authenticating\":\"Scheduled Instruction Authentication\",\"Approval\":\"Scheduled Instruction Approval\",\"InProgress\":\"Scheduled Instruction InProgress\",\"Cancelling\":\"Scheduled Instruction Cancelling\"}",
        "WorkflowState": 8,
        "ApprovalOffloaded": false,
        "ReadablePayload": "Echo message %msg%.",
        "ScheduleEnabled": true,
        "ScheduleFreqType": 1,
        "ScheduleFreqInterval": 0,
        "ScheduleFreqSubdayType": 0,
        "ScheduleFreqSubdayInterval": 0,
        "ScheduleFreqRelativeInterval": 0,
        "ScheduleFreqRecurrenceFactor": 0,
        "ScheduleActiveStartDate": "2019-12-10T00:00:00Z",
        "ScheduleActiveEndDate": "2019-12-11T00:00:00Z",
        "ScheduleActiveStartTime": 142000,
        "ScheduleActiveEndTime": 140200,
        "ScheduleLastExecuted": "2019-12-10T14:20:00Z",
        "ScheduleNextExecution": null,
        "ScheduleReadableFrequency": "Occurs once on 10/12/2019 at 14:20:00"
    }
]

Use ScheduledInstructions object inside the Tachyon connector instance.

Retrieving all scheduled instructions
schedules = connector.ScheduledInstructions.GetAll();

"schedules" object will contain the same data you can see in the JSON response on the left.

You can also retrieve a single scheduled instruction by using its Id. You cannot use the name because there might be multiple scheduled instructions that use the same instruction definition.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to https://my.tachyon.server/Consumer/ScheduledInstructions/1 will yield following response:

Return payload
{
    "Id": 1,
    "Name": "1E-Explorer-TachyonAgent-Echo",
    "Cmd": "SendAll",
    "KeepRaw": true,
    "Scope": null,
    "ReadableScope": null,
    "InstructionTtlMinutes": 60,
    "ResponseTtlMinutes": 120,
    "CreatedTimestampUtc": "2019-12-06T10:53:31.903Z",
    "Export": false,
    "ExportLocation": null,
    "ParentInstructionId": null,
    "InstructionDefinitionId": 23,
    "CreatedBy": "SomeDomain\\Jane.Doe",
    "ResultsFilter": null,
    "PreviousResultsFilter": null,
    "Devices": null,
    "ConsumerId": 1,
    "ConsumerName": "Explorer",
    "ConsumerCustomData": null,
    "ParameterJson": "[{\"Name\":\"msg\",\"Pattern\":\"%msg%\",\"DataType\":null,\"ControlType\":null,\"ControlMetadata\":null,\"Placeholder\":null,\"DefaultValue\":null,\"Validation\":null,\"Value\":\"Machine reporting\",\"HintText\":null,\"Source\":null}]",
    "OffloadResponses": false,
    "RequestedFor": null,
    "Comments": "Reporting machine echo",
    "ActionedBy": "Ollanius Pius",
    "ActionReason": null,
    "Status": 7,
    "StatusTimestampUtc": "2019-12-10T13:24:35.917Z",
    "Workflow": "{\"StateMachine\":\"Scheduled Instruction State with Authentication and Approval\",\"Authenticating\":\"Scheduled Instruction Authentication\",\"Approval\":\"Scheduled Instruction Approval\",\"InProgress\":\"Scheduled Instruction InProgress\",\"Cancelling\":\"Scheduled Instruction Cancelling\"}",
    "WorkflowState": 8,
    "ApprovalOffloaded": false,
    "ReadablePayload": "Echo message %msg%.",
    "ScheduleEnabled": true,
    "ScheduleFreqType": 4,
    "ScheduleFreqInterval": 1,
    "ScheduleFreqSubdayType": 8,
    "ScheduleFreqSubdayInterval": 12,
    "ScheduleFreqRelativeInterval": 0,
    "ScheduleFreqRecurrenceFactor": 0,
    "ScheduleActiveStartDate": "2019-12-06T00:00:00Z",
    "ScheduleActiveEndDate": "2019-12-09T00:00:00Z",
    "ScheduleActiveStartTime": 120000,
    "ScheduleActiveEndTime": 120000,
    "ScheduleLastExecuted": null,
    "ScheduleNextExecution": null,
    "ScheduleReadableFrequency": "Occurs every 1 day(s) every 12 hours starting at 12:00:00 ending at 12:00:00 starting on 06/12/2019 ending on 09/12/2019"
}

Use ScheduledInstructions object inside the Tachyon connector instance.

Retrieving a single scheduled instruction
schedule = connector.ScheduledInstructions.GetScheduledInstruction(1);

"schedule" object will contain the same data you can see in the JSON response on the left.

Retrieving past and/or 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.