Version: 4
restore

Contents

Introduction

On this page we will learn how to browse instruction definitions available in your Tachyon installation.

We will assume that instruction definitions have already been uploaded into Tachyon and organised into Instruction Sets (please refer to Add and Remove Instruction definitions and organise them into instruction sets), with all necessary permissions assigned (please refer to Set up Principals, Roles and Permissions).

C# examples assume you are using Tachyon Consumer SDK and assume that you already have a correctly instantiated instance of Tachyon connector class in an object called 'connector'.

Another thing to remember is that all SDK methods return the same class called ApiCallResponse. Inside the object of that class you'll find a property called ReceivedObject. That object is the actual data received from the API. We will be omitting this detail in the examples and simply saying that the return object contains the data. So when we're saying that XYZ object will contain such-and-such data, what we mean in that the ReceivedObject contains that data, since that is always the case.

When this page mentions permissions on instructions, what it means is Instruction set permissions and not Instruction set management permissions, as those are a separate category of permissions. Instruction set permissions gain Principals access to all instructions within a specific set or all sets.

It is possible to have a permission on given, or even all, Instruction sets, thus being able to issue instructions without being able to manage the instruction sets, so without having instruction set management permissions.

The reverse is also possible and the Principal that is allowed to assign instruction definitions to instruction set may not have permission to issue any of those instructions.

What is an instruction definition?

An instruction definition is a template that is used to create instructions that are then sent to devices running Tachyon Agent for processing.

Instruction definition defines what should the agent do when executing the instruction, what data is returned and if its aggregated, what the parameters for the instruction are, how to present the results to the user and so on.

When an instruction is being issued, some information is copied from the definition that the instruction is based on (like instruction name and type) while other come from information provided with the request to issue the instruction. Please refer to Issue an instruction, track its progress and retrieve responses for details.

What properties can be used to uniquely identify an instruction definition?

Instruction definition has two properties that can be used to identify it.

The first is the Id, which is a number assigned to the instruction definition when it is imported into Tachyon. This means that you cannot foresee it before the instruction is imported and it will be different between Tachyon installations. Also, if you remove the instruction definition and then import it again in the future, it will be given a different Id to the one it had before.

The second property is the name, which must be unique within given installation of Tachyon. An attempt to import and instruction definition with the same name as one that already exists is treated as an upgrade attempt of the existing instruction definition.

The API allows you to use both Id and Name when locating specific instruction definition or issuing an instruction.

How to uniquely identify an instruction?

Instructions can only be identified by their Id, which is assigned when an instruction is created (issued).

They cannot be located by Name, because that it is not unique. Every instruction based on the same instruction definition will have the same name.

How is an instruction created from an instruction definition

Although full details of this process are outside the scope of this page we will cover the basics.

When an instruction is created (which is also called issuing an instruction), the following will happen:

  • The name of the instruction definition will be copied into the newly created instruction
  • The payload and readable payload will be copied into the newly created instruction. Any parameters (provided by the issuer of the instruction), environment variables and global settings will be filled in.
  • Instruction TTL and Response TTL are filled with the values provided by the issuer of the instruction
  • Schema and Aggregation schema are copied from the instruction definition
  • Scope provided by the issuer of the instruction is combined with any compulsory scope resulting from issuing Principal permissions.

although this is not an exhaustive list.

Searching for instruction definitions

Instruction definitions are retrieved for two reasons - to issue instructions and to manage instructions within instruction sets.

When instruction definitions are retrieved for the reason of issuing an instruction, instruction set related permissions of the Principal have to be taken into account. Those permissions will limit which instructions the caller is allowed to issue. This limitation will be enforced by the API endpoint.

When instruction definitions are retrieved fro the reason of managing instruction sets, the Principal retrieving them requires permission to manage instruction sets and doesn't need to have any permissions to the instructions themselves.

This is important because if you retrieve all instruction definitions using the endpoint designed for instruction set management, you might not be able to issue all of those instructions because the list you receive will not be filtered down using your permissions.

Retrieving all instruction definitions

In this example we'll retrieve all instruction definitions that we can issue.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Retrieving only instruction definitions of a specific type

In some cases, you may want to retrieve all instruction definitions of a given type that you can issue. This is used, for instance, by Explorer on the Follow-up question and Follow-up action tabs on the instruction details page.

This can be achieved by using the optional query string parameter on the same call as the one made we made in the last example.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Retrieving all instruction definitions regardless of caller's permissions

As mentioned above, retrieving all definitions should only be used when managing instruction sets.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to will yield following response:

Use  object inside the Tachyon connector instance.

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

It is also worth remembering that this endpoint requires Instruction set management related permissions to work.

Using search-as-you-type feature

This is the feature seen on Explorer's home page "I want to know" in form of a search box, into which you can type text and Tachyon will return instruction definitions you have permissions to use that match the string entered into the search box.

The match is done by searching for the words (defined as a string of characters separated by a space) in instruction definition's readable payload (which is what the Explorer displays after you've picked up an instruction definition) and description (which Explorer displays in the tooltip available after an instruction definition has been selected).

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Searching for instruction definitions that match specific criteria

When managing instruction sets you can also use an endpoint that allows instruction definitions to be filtered, sorted and paginated. This endpoint, like the one that allows you to retrieve all instructions regardless of calling Principal's permissions, requires permissions related to instruction set management to work.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Searching for instruction definitions when issuing a follow-up instruction

When an instruction is to be issued as a follow up to another instruction additional conditions need to be taken into account.

If you were to simply retrieve all definitions like we did above, although we would get a list of instruction definitions that you, the caller, have permission to, but we would ignore all restrictions coming from the instruction that will be the parent (the instruction you're following up on). Those restrictions step from permissions of whoever issued the instruction you're about to follow up on and you need to use another endpoint to make sure you're searching for instruction definitions in the right context.

Retrieving all instruction definitions that can be used to issue a follow-up

You can retrieve all definitions you have permission, much like you did here.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Searching for feasible follow-up instruction definitions that match specific criteria

You can also use a type-as you search endpoint, akin to what we did here.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Retrieving specific instruction definition

You can also attempt to retrieve a specific definition, either by its Id or Name.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to will yield following response:

Use  object inside the Tachyon connector instance.

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

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to will yield following response:

Use  object inside the Tachyon connector instance.

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