Contents
-
Writing Tachyon Instructions
-
Integrating with Tachyon
-
Introduction
-
Tachyon RunInstruction command-line tool
-
Consumer API reference
-
Using scope and filter expressions
-
How to guides
-
Add and remove Instruction Definitions and organize them into Instruction Sets
-
Find the right instruction definition
-
Getting data from Tachyon clients
-
Handling errors returned by Tachyon
-
Issue an instruction, track its progress and retrieve responses
-
Set up in instruction to be executed on a schedule
-
Set up Principals, Roles and Permissions, for Tachyon version 8.0 and later
-
Set up Principals, Roles and Permissions, up to and including Tachyon version 5.2
-
Add and remove Instruction Definitions and organize them into Instruction Sets
-
Introduction
-
Tachyon .NET Consumer SDK
-
Tachyon PowerShell Toolkit
-
Index
What is an instruction definition?
An instruction definition is a template used to create instructions which are sent to computers running Tachyon Agent for processing.
The instruction definition defines what the agent does when executing the instruction, for example what data is returned, if it is aggregated, what the parameters for the instruction are, or how to present the results to the user.
When an instruction is issued, some information is copied from the definition the instruction is based on (like instruction name and type) while others come from the information provided with the request to issue the instruction. For more information read issue an instruction, track its progress and retrieve responses.
What properties can be used to uniquely identify an instruction definition?
An instruction definition has two properties to identify it, Id and name:
Id - is a number assigned to the instruction definition when it's imported into Tachyon. This means you cannot predict the Id before the instruction is imported and it will be different between Tachyon installations. If you remove the instruction definition and import it again it will be given a different Id.
Name - must be unique in each Tachyon installation. Importing a new instruction definition with the same name as one already in Tachyon is treated as an upgrade of the existing instruction definition.
The API allows you to use both Id and Name when locating specific instruction definitions 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 it's not unique. Every instruction based on the same instruction definition will have the same name.
How is an instruction created from an instruction definition
Full details of this process are outside the scope of this section.
When an instruction is created (sometimes called issuing) the:
- Instruction definition name gets copied into the newly created instruction
- The payload and readable payload get copied into the newly created instruction - any parameters (provided by the issuer of the instruction), environment variables and global settings are completed
- Instruction TTL and Response TTL are filled with values provided by the instruction issuer
- Schema and Aggregation schema get copied from the instruction definition
- Scope provided by the instruction issuer is combined with any compulsory scope that results from issuing Principal permissions.
This is not a complete list.
Searching for instruction definitions
Instruction definitions are retrieved for two reasons:
Issuing instructions - instruction set related permissions of the Principal have to be taken into account. Those permissions limit which instructions the caller is allowed to issue. This limitation is enforced by the API endpoint.
Managing instruction sets - the Principal retrieving them requires permission to manage instruction sets and does not 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. This is because the list you receive will not be filtered down using your permissions.
Retrieving all instruction definitions
This example retrieves all instruction definitions that can be issued:
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/Instruction Definitions The payload has been trimmed to just two entries to show what you can expect. In a production installation of Tachyon there will be many more instruction definitions, perhaps hundreds. | Use InstructionDefinitions object inside the Tachyon connector instance. Definitions 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 example, by Tachyon Explorer on the Follow-up question and Follow-up action tabs on the instruction details page. You can do this using the optional query string parameter on the same call as the one made in the last example.
The next example shows where we only get the Questions we're allowed to issue.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Make a GET request to https://my.tachyon.server/Consumer/Instruction Definitions?instructionType=question The return payload will have the same structure as the payload seen when we retrieved all the instruction definitions in the previous example. | Use InstructionDefinitions object inside the Tachyon connector instance. Definitions object contains information similar to the retrieving all instruction definitions example. |
Retrieving all instruction definitions regardless of caller permissions
Retrieving all definitions should only be used when managing instruction sets.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer/ InstructionDefinitions/All The return payload has same structure as the payload seen when retrieving all the instruction definitions in the retrieving all instruction definitions examples. | Use InstructionDefinitions object inside the Tachyon connector instance. |
Please note that this endpoint requires Instruction set management related permissions to work.
Using search-as-you-type feature
This is the feature seen on the Tachyon Explorer home page as "I want to know" in form of a search box where Tachyon returns the instruction definitions you have permissions to use based on your search criteria.
The match is achieved by searching for the words (defined as a string of characters separated by a space) in an instruction definition's readable payload (which is what Explorer displays after you've picked an instruction definition) and description (which Explorer displays in the tooltip available after an instruction definition is selected).
This example looks for the word bios and retrieves all instruction definitions containing that word either in the description or readable payload.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer /InstructionDefinitions/Search/Ymlvcw== returns results similar to: | Use InstructionDefinitions object inside the Tachyon connector instance. Definitions object contains the same data you can see in the JSON response on the left. |
Entries for Instruction definitions returned by this endpoint contain only part of the data for performance reasons. This is intended as a search-as-you-type feature so the data must be returned quickly.
Searching for instruction definitions that match specific criteria
When managing instruction sets you can also use an endpoint allowing instruction definitions to be filtered, sorted and paginated. This endpoint, like the one allowing you to retrieve all instructions regardless of calling Principal's permissions, requires permissions related to instruction set management to work.
This example looks for all instruction definitions containing the word bios in their name. Although it looks the same as the search-as-you-type scenario, it looks exclusively on the Name, and not on the readable payload or description because our search parameters only specify the name.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request to Returns a similar response to the one below: | Use InstructionDefinitions object inside the Tachyon connector instance. Definitions object contain the same data you can see in the JSON response on the left. |
If you want to search the same way as search-as-you-type feature, you can adjust the search criteria to include Readable payload and Description columns.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request to Returns a similar response to the one below: | Use InstructionDefinitions object inside the Tachyon connector instance. Definitions object contains the same data you can see in the JSON response on the left. |
Searching for instruction definitions when issuing a follow-up instruction
To issue an instruction as a follow up to another instruction, additional conditions need to be taken into account.
If you were to simply retrieve all definitions as in retrieving all instruction definitions, although you'd get a list of instruction definitions that you, the caller, have permission to, you'd ignore all restrictions coming from the instruction that's the parent (the instruction you're following up on). Those restrictions stem from permissions of whoever issued the instruction you're about to follow up on. 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 to, like with retrieving all instruction definitions, in the context of a follow-up instruction.
This example assumes you're following up on an instruction with the Id of 12. The instruction itself is irrelevant for this example which focuses on establishing what instruction definitions could be used for a follow-up.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Make a GET request to https://my.tachyon.server/Consumer/Instruction Definitions/Parent/12 to retrieve all instruction definitions the caller can issue as a follow-up. The return payload will have the same structure as the payload seen when we were retrieving all the instruction definitions in retrieving all instruction definitions. If you want to only get instruction definitions of a specific type, add a query string parameter as in retrieving only instruction definitions of a specific type. For instance, if you wanted to get all Actions you'd make this GET request: https://my.tachyon.server/Consumer/Instruction Definitions/Parent/12?instructionType=action | Use InstructionDefinitions object inside the Tachyon connector instance. The definitions object will contain the same data we've seen when retrieving all the instruction definitions in retrieving all instruction definitions. |
Searching for feasible follow-up instruction definitions that match specific criteria
You can also use a search-as-you-type endpoint, like the using search-as-you-type feature, when looking for instruction definitions to issue follow-up instructions.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer /InstructionDefinitions/Parent/12/Search/Ymlvcw== will return the following response: | Use InstructionDefinitions object inside the Tachyon connector instance. The definitions 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.
The following two examples look for the Bios instruction definition, both using its Id, which is 66 as seen in previous examples and its name which is 1E-Explorer-TachyonCore-BiosDetails.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer /InstructionDefinitions /Id/66 returns the following response: | Use InstructionDefinitions object inside the Tachyon connector instance. The definition object will contain the same data you can see in the JSON response on the left. |
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https:// my.tachyon.server /Consumer/InstructionDefinitions/Name/1E-Explorer-TachyonCore-BiosDetails returns the same response seen in the previous example. | Use InstructionDefinitions object inside the Tachyon connector instance. The definition object will contain the same information it did in the previous example. |
Exporting Instruction Definitions
You can export Instruction Definitions back into their original XML format.
>Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a GET request to https://my.tachyon.server/Consumer /InstructionDefinitions/Id/1/export gives you a binary stream with an XML document representing requested Instruction Definition. You can also export it by name by making a GET request to https://my.tachyon.server/Consumer /InstructionDefinitions/Name/1E-Explorer-Examples-CountEventLogErrorsInLastX/export | Use InstructionDefinitions object inside the Tachyon connector instance: Or by name: response.ReceivedObject will be a MemoryStream holding an XML file containing the requested Instruction Definition. |
You can also export multiple Instruction Definitions at the same time, specifying either their Ids or Names, giving you a zip file containing one XML file for each Instruction Definition.
Direct Consumer API call | C# code using Consumer SDK library |
---|---|
Making a POST request with following payload if you want to export Instruction Definitions by Id: Or this payload if you want to export them by name: Returns a byte stream with a zip file containing requested Instruction Definitions. | Use InstructionDefinitions object inside the Tachyon connector instance. response.ReceivedObject will be a MemoryStream containing a zip file containing one XML file for each Instruction Definition. The Consumer SDK does not support exporting multiple Instruction Definitions by name. |