Instruction Definition Reference

Tachyon Instruction Definition format and attributes.

Tachyon Instructions - questions and actions - are defined using an XML format. This format includes the body of the Instruction (the logic that the Tachyon Agent will run to execute the Instruction), as well as other metadata which determines how the Instruction is described, categorized and how its lifecycle is managed.

Typically, an Instruction Definition is authored using a tool like Tachyon Instruction Management Studio.

This page is a reference for the instruction definition schema.

This page assumes basic familiarity with XML and JSON formats.

Terminology

You should understand the following terms before reading further:

Term	Explanation
Instruction Definition	An Instruction Definition exists as an XML file before being imported into Tachyon, and typically describes a Question or an Action. This file contains all the information necessary to ask that Question or instigate that Action.
Instruction	An Instruction is an "instance" of when an Instruction Definition is used, created when that Instruction Definition is executed. For example, typing a question fragment into Tachyon Explorer technically shows a list of available Instruction Definitions. At the point that a specific question is selected and the user clicks "Ask this question", a new Instruction instance is created based on the Instruction Definition. You can think of Instruction Definitions as being like templates, and Instructions like things being created from that template. Instructions are transitory, in the sense that they have a finite lifetime.
Instruction Resource	An Instruction Resource is a file, such as a PowerShell script, which is embedded into the Instruction Definition. When a Tachyon Agent runs an Instruction based on this Instruction Definition, the Instruction Resource is available to be downloaded and used by the Agent.
Instruction Payload	The payload of an Instruction is a sequence of steps (expressed in the Tachyon Agent Language) which are sent to, and executed by, the Tachyon Agent when that Instruction is issued.
Product Pack	A Product Pack is the name given to a zip file which contains one or more (normally related) Instruction Definition XML files. Product Pack zip files can be imported directly into Tachyon Explorer, which will import all the contained Instruction Definitions. Product Pack structure Product Pack zip files must contain "flat" set of XML files; in other words, the zip file should not contain any sub-folders.
Task Group	A Task Group is a hierarchical structure used to group together related Instruction Definitions, similar to folders on a file-system. Task Groups are displayed in the Tachyon Explorer "Tasks" page.
Digital Signature	A Digital Signature is a way of guaranteeing that a document (e.g. an XML file) was created by a specific author, and that the document has not been modified or tampered with since it was authored.

Instruction Definition format

An Instruction Definition XML file comprises of an XML document header, an <InstructionDefinition> parent XML element, and various sub-elements describing specific aspects of the definition.

The sub-elements are outlined below, some of which are described in more detail in later sections.

At a high-level, the XML format is as follows:

Instruction Definition XML structure

+-- (XML document header)
+-- InstructionDefinition
    +-- Comments
    +-- Payload
    +-- ParameterJson
    +-- SchemaJson
    +-- AggregationJson
    +-- Workflow
    +-- ResponseTemplateConfiguration
    +-- Resources
    |   +-- Resource
    |       +-- Content
    +-- TaskGroups
    |   +-- TaskGroup
    +-- Signature

Note that child elements of the <InstructionDefinition> element can appear in any order.

The individual elements have the following purposes (elements highlighted in blue are links to more detail further down in the page):

Element	Required	Purpose	Database column
InstructionDefinition	Yes	The parent element in the XML document, including basic properties of the Instruction Definition such as its name, description, type, version. All other XML elements within the document are child elements of this parent element.	N/A
InstructionDefinition\Payload	Yes	Contains the Instruction Payload, written in the Tachyon Agent Language, that should be sent to the Tachyon Agent(s), including placeholders for any parameter values which are substituted when the Instruction is issued. The content of this element is typically marked up as CDATA within the XML (to simplify escaping of reserved XML characters).	InstructionDefinition.Payload
InstructionDefinition\Comments	No	Contains optional comments about the Instruction Definition provided by the author.	InstructionDefinition.Comments
InstructionDefinition\SchemaJson	Yes	A JSON representation of the data structure which will be created to store Responses from Tachyon Agents when they reply to this Instruction. The content of this element is typically marked up as CDATA within the XML.	InstructionDefinition.SchemaJson
InstructionDefinition\AggregationJson	No	A JSON representation of the data structure which will be created to store summarized ("aggregated") Responses from Tachyon Agents, and the grouping and aggregate operations which define how the data should be summarized. The content of this element is typically marked up as CDATA within the XML.	InstructionDefinition.AggregationJson
InstructionDefinition\ParameterJson	No	A JSON representation of the parameters for this Instruction Definition. Parameters can be supplied by the user at the point that the Instruction is issued. The content of this element is typically marked up as CDATA within the XML.	InstructionDefinition.ParameterJson
InstructionDefinition\Workflow	No	A JSON representation of the Tachyon Workflow state machine, and other metadata, to be used if the Instruction Definition should not follow the corresponding default approval workflow.	InstructionDefinition.Workflow
InstructionDefinition\ResponseTemplateConfiguration	No	A JSON representation of the logic that Tachyon Consumers may use to provide customized rendering of Responses for the Instruction, such as charts and graphs. This topic is described in more depth here: Custom Response Visualizations	InstructionDefinition.ResponseTemplateConfiguration and InstructionDefinition.ResponseTemplateId
InstructionDefinition\Resources	No	A container element for one or more `<Resource>` child elements, which define the content for embedded resources for this Instruction Definition.	N/A
InstructionDefinition\Resources\Resource	Yes	Defines the name of a resource, and contains one or more `<Content>` child elements.	InstructionDefinitionResource table
InstructionDefinition\Resources\Resource\Content	Yes	Defines the properties and metadata about the (platform-specific) content for an individual resource, and the content itself (represented as base-64 encoded binary). The content of this element is typically marked up as CDATA within the XML.	InstructionDefinitionResource.Content
InstructionDefinition\TaskGroups	No	A container element for one or more `<TaskGroup>` child elements.	N/A
InstructionDefinition\TaskGroups\TaskGroup	Yes	Defines the path of a Task Group under which this Instruction Definition should be grouped.	TaskGroups and Task
InstructionDefinition\Signature	No	Contains digital signature information for the XML file.	N/A

Digital Signature

As well as the elements described above, an Instruction Definition XML file will typically include a Digital Signature. This signature provides a mechanism to verify the source and integrity of the file.

Digital Signatures and Licensing

Licenses issued by 1E for Tachyon contain restrictions on the Instruction Definitions which can be imported (based on the name of the Instruction Definition, and who has signed it).

Instruction Definition XML files are signed in accordance with the standard defined by the World Wide Web Consortium. The details of the signing mechanism are beyond the scope of this document, but in summary:

The XML document contains an additional <Signature> element underneath the root <InstructionDefinition> element
The <Signature> element contains a number of child elements, which include a Digest Value, a Signature Value, and a base-64 encoded representation of the X509 certificate used to sign the document
Modifying or invalidating the content of the Digital Signature will effectively render the XML file unsigned. If this happens, the Instruction Definition XML file cannot be imported into Tachyon.

The signing certificate is not required to issue instructions. The system will only save the thumbprint in InstructionDefinition.Thumbprint field in the database and will use this thumbprint along with instruction definition name and payload to create a checksum (InstructionDefinition.Checksum field in the database). Checksum is used to prevent instruction definition from being tampered with directly in the database after it was imported and it is verified each time an instruction is issued based on given definition.

The signing certificate is required in the Trusted Publishers certificate store on the server only in order that an Instruction administrator can import instructions.

Sample Instruction Definition XML

Sample Instruction Definition Expand source

<?xml version="1.0" encoding="utf-8"?>
<InstructionDefinition xmlns="http://schemas.1e.com/Tachyon/InstructionDefinition/1.0"
    Name="1E-Explorer-TachyonCore-FindNonBitLockerDrives"
    InstructionType="Question"
    InstructionTtlMinutes="30"
    ResponseTtlMinutes="30"
    ReadablePayload="Which fixed drives don't have Bitlocker enabled?"
    Description="Returns fixed drives which don't have Bitlocker enabled."
    Version="3">
    <Payload>
<![CDATA[
@script = HttpGetFile(URL : "findNonBitlockerDrives.ps1", Size:917, Hash:"e91ab19be166e029b71d1dba42eac838141fc23afc247a242f29c6a08b0cbcfa");
Scripting.Run( Language: "PowerShell", ExecutionPolicy : "Override", Script : @script, InterpretAsJson : true );
]]>
    </Payload>
    <SchemaJson>
<![CDATA[
[
    {
        "Name":  "MountPoint",
        "Type":  "String",
        "Length":  16
    },
    {
        "Name":  "CapacityGB",
        "Type":  "String",
        "Length":  64
    },
    {
        "Name":  "VolumeStatus",
        "Type":  "String",
        "Length":  64
    }
]
]]>
    </SchemaJson>
    <ParameterJson>
<![CDATA[]]>
    </ParameterJson>
    <AggregationJson>
<![CDATA[
{
    "Schema":  [
                   {
                       "Name":  "MountPoint",
                       "Type":  "string",
                       "Length":  512
                   },
                   {
                       "Name":  "Count",
                       "Type":  "int32"
                   }
               ],
    "GroupBy":  "MountPoint",
    "Operations":  [
                       {
                           "Name":  "Count",
                           "Type":  "count"
                       }
                   ]
}
]]>
    </AggregationJson>
    <ResponseTemplateConfiguration>
<![CDATA[
{
    "Name":  "default",
    "TemplateConfigurations":  [
                                   {
                                       "Id":  "driveChart",
                                       "Title":  "MountPoint vs device count",
                                       "Type":  "Pie",
                                       "X":  "MountPoint",
                                       "Y":  "Count",                                      
                                       "PostProcessor":  "mountPointProcessingFunction",
                                       "Size":  1,
                                       "Row":  1
                                   }
                               ],
    "PostProcessors":  [
                           {
                               "Name":  "mountPointProcessingFunction",
                               "Function":  "ProcessSingleSeries('MountPoint', 'Count', '10', 'Devices with this Mount Point', 'false')"
                           }
                       ]
}
]]>
    </ResponseTemplateConfiguration>
    <Resources>
        <Resource Name="FindNonBitlockerDrives">
            <Content FileName="findNonBitlockerDrives.ps1"
                Size="917"
                Hash="e91ab19be166e029b71d1dba42eac838141fc23afc247a242f29c6a08b0cbcfa"
                Platform="Windows"
                Type="PowerShell">
                <![CDATA[I2ZpbmRzIGZpeGVkIGRyaXZ ... [omitted for brevity] ... bXByZXNzDQpleGl0IDA=]]>
            </Content>
        </Resource>
    </Resources>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
                <DigestValue>EFanv4wJtb8NkudpydiCW0gI+7M=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>
            fGyi0f6v8xi+l0QrARqVHykyjMwHayis4fnQ+o9XoYDldsAI ... [omitted for brevity] ... YQtND4yptDkK3pvzg==
        </SignatureValue>
        <KeyInfo>
            <X509Data>
                <X509Certificate>
                    MIIGejCCBGKgAwIBA ... [omitted for brevity] ... tYAiJcgeRctvzo8G5B
                </X509Certificate>
            </X509Data>
        </KeyInfo>
    </Signature>
</InstructionDefinition>

Instruction Definition XML elements

The best way to get an understanding of the Instruction Definition XML format is to look at specific examples and see how the definition corresponds to each facet of the Instruction Definition.

This section describes the XML format in detail. The following section contains an XSD which can be used to check the validity of an individual Instruction Definition file.

XML Schema Versioning

Note that the XML references an XML namespace: http://schemas.1e.com/Tachyon/InstructionDefinition/1.0

The last part of this namespace references a version number (1.0), which corresponds to the version of the XML format used to express the Instruction Definition.

Future changes to the InstructionDefinition XML format will reference higher version numbers of the namespace for compatibility puropses.

Case Sensitivity

Note that XML and JSON formats are case sensitive with respect to names of elements and attributes.

JSON inside XML

Many of the XML elements inside the Instruction Definition format contain embedded JSON.

The contents for these elements are usually marked up as CDATA within the XML to simplify escaping of reserved XML character sequences.

Since JSON content cannot be validated by an XML schema, the XSD supplied below will be unable to detect problems with JSON formatting, however any such problems can be identified at the point the Instruction Definition is imported in Tachyon (either through Tachyon Explorer or the Tachyon Consumer API).

The JSON formats are described in detail below.

InstructionDefinition

This is the root element - aside from the XML declaration element - of the document.

This element represents an individual Instruction Definition, and must appear exactly once within the document.

This element has the following attributes:

Attribute Name	Required	DataType	Database Mapping	Description	Example value(s)
xmlns	Yes	string		References the XML namespace corresponding to the schema for Tachyon Instruction Definitions.	`http://schemas.1e.com/Tachyon/InstructionDefinition/1.0`
Name	Yes	string	InstructionDefinition.Name	The name of the Instruction Definition, which must be unique. The name should follow the format companyName-optionalConsumerName-name, as Tachyon licenses restrict which instructions can be issued based on a naming pattern. Instruction Definitions whose names do not match a licensed naming pattern will be able to be imported into Tachyon, but will not be able to be used without a corresponding license. Instruction names are limited to 256 characters.	`1E-Explorer-OperatingSystemSummary` `1E-NightWatchman-PowerProfileConfiguration` `Acme-Networking-DhcpAllocationPatterns` `Acme-SoftwareUsageSummary`
InstructionType	Yes	string (enumeration)	InstructionDefinition.InstructionType	The type of instruction, which determines the default approval workflow that will be used when the instruction is issued. Possible values are: `Question` - use when the instruction will not alter the state of any device on which it runs `Action` - use when the instruction may modify the state of a device on which it runs.	`Question` `Action`
Description	Yes	string	InstructionDefinition.Description	A brief description of what the instruction does when it runs. This description is visible in Tachyon Explorer. Where possible, your description should start with a verb in the present tense (see examples).	`Shows the number of TCP connections by recently executed processes.` `Modifies the Finance application configuration to enable HTTPS.` `Counts the number of times applications (per publisher) have been run.`
ReadablePayload	Yes	string	InstructionDefinition.ReadablePayload	The primary text to show for the instruction, normally phrased in the form of a question or an action. This text is shown throughout Tachyon Explorer, for example when selecting an instruction from the home page. The Readable Payload must contain substitution placeholders for all parameters which have been defined for the instruction (see examples).	Question examples `Which devices have a USB storage device connected?` `How many connections has each process made in the last %days% days?` `Which versions of %publisher% %product% are installed?` Action examples `Remove all expired certificates from Windows certificate store` `Close any browser processes which are running as a local administrator` `Delete any temporary files with a %extension% file extension`
InstructionTtlMinutes	Yes	unsigned integer	InstructionDefinition.InstructionttlMinutes	Also known as the gather period. This period starts after the instruction has been approved. The number of minutes, by default, for which Instructions based on this Instruction Definition will be open to receive responses from Tachyon Agents. The possible valid range of values is defined in the Global Settings table within the Tachyon master database. The setting is named DefaultInstructionTtlMinutes, and uses JSON to represent a pair of minimum and maximum values. The database default for this range is minimum of 10 minutes, maximum of 1440 minutes (i.e. 1 day). In Tachyon Explorer, this value can be overridden by the user, as long as it falls within the minimum and the maximum values (described below), or the default minimum/maximum (defined in the Global Settings table) if one or both of these is not specified for this Instruction Definition.	30
ResponseTtlMinutes	Yes	unsigned integer	InstructionDefinition.ResponseTtlMinutes	Also known as the keep period. This period starts after the gather period has completed. The number of minutes, by default, for which responses to Instructions based on this Instruction Definition will be kept before they are deleted automatically. The possible valid range of values is defined in the Global Settings table within the Tachyon master database. The setting is named DefaultResponseTtlMinutes, and uses JSON to represent a pair of minimum and maximum values. The database default for this range is minimum of 10 minutes, maximum of 10080 minutes (i.e. 7 days). In Tachyon Explorer, this value can be overridden by the user, as long as it falls within the minimum and the maximum values (described below), or the default minimum/maximum (defined in the Global Settings table) if one or both of these is not specified for this Instruction Definition.	240
Version	Yes	string (representing numeric value)	InstructionDefinition.Version	A number representing the version number of this Instruction Definition. This version number should be incremented by the author whenever a change is made to the Instruction Definition. The version number may be a single integer number, or may be dotted-notation (e.g. 1.2), with up to four components. Uploading an Instruction Definition into Tachyon where a previous definition already exists with the same name but with a higher version number will result in an error. Uploading an Instruction Definition into Tachyon where a previous definition already exists with the same name and the same version number will cause the definition being uploaded to be discarded.	3 1.0
MinimumInstructionTtlMinutes	No	unsigned integer	InstructionTtlRange.Minimum inside InstructionDefinition.Restrictions	Specifies the minimum instruction TTL allowed for this instruction (see above). If this field is omitted a default value taken from GlobalSetting table, entryDefaultInstructionTtlMinutes "Minimum" is used.	10
MaximumInstructionTtlMinutes	No	unsigned integer	InstructionTtlRange.Maximum inside InstructionDefinition.Restrictions	Specifies the maximum instruction TTL allowed for this instruction (see above). If this field is omitted a default value taken from GlobalSetting table, entryDefaultInstructionTtlMinutes "Maximum" is used.	20
MinimumResponseTtlMinutes	No	unsigned integer	ResponseTtlRange.Minimum inside InstructionDefinition.Restrictions	Specifies the minimum response TTL allowed for this instruction (see above). If this field is omitted a default value taken from GlobalSetting table, entryDefaultResponseTtlMinutesis used.	10
MaximumResponseTtlMinutes	No	unsigned integer	ResponseTtlRange.Maximum inside InstructionDefinition.Restrictions	Specifies the maximum response TTL allowed for this instruction (see above). If this field is omitted a default value taken from GlobalSetting table, entryDefaultResponseTtlMinutesis used.	60
Author	No	string	InstructionDefinition.Author	The name or email address of the author who created this Instruction Definition. Author names are limited to 256 characters.

SchemaJson

This field will contain JSON array of schema objects inside a CDATA field.

Responses returned for an instruction are of tabular format with one or more columns. SchemaJson defines the data structure that will be used to create table to store responses. It is made of a collection of JSON objects each representing a column.

For example, you may wish to create an instruction which counts the number of TCP connections made per process resulting in responses like:

ProcessName	ConnectionCount
`iexplore.exe`	`12`
`svchost.exe`	`4`
`ccmexec.exe`	`1`
`outlook.exe`	`13`

To store this kind of responses SchemaJson may look like...

[
    {
        "Name":  "ProcessName",
        "Type":  "string",
        "Length": "256"
    },
    {
        "Name":  "ConnectionCount",
        "Type":  "Int32"
    }
]

and the actual XML element would look like this:

SchemaJson xml element

<SchemaJson>
<![CDATA[
[
    {
        "Name":  "ProcessName",
        "Type":  "string",
        "Length": "256"
    },
    {
        "Name":  "ConnectionCount",
        "Type":  "Int32"
    }
]
]]>
</SchemaJson>

Each column definition (JSON array element) has following properties.

Property Name	Required	Description
Name	Yes	Column name.
Type	Yes	Defines the type of data that can be stored. These data types are based on CLR data types. Supported data types are listed in the table below.
Length	No	Applicable only to String data type but not mandatory to have. If none specified, no size restriction is applied.
RenderAs	No	Defines custom value renderer for the column in Tachyon Explorer. For example, if an instruction returns locations it's possible to display maps in Tachyon Explorer provided a renderer is available for that.

Supported Data Types

Name	Description
Bool	Possible values are either true or false.
Int32	Can store any integer value between -2,147,483,648 and 2,147,483,647 inclusive.
Int64	Can store any integer value between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 inclusive.
String	Can store any text data. Depending on size requirements optional length can be specified. If no length is specifed, text of any length can be stored.
DataTimeOffset	Can store date/time along with timezone offset.
Guid	Can store a UUID.
CLOB	Can store a large amount of text. Contents of this type will by default be truncated to a fixed length when the responses are retrieved. In order to retrieve full contents of the field another call to the Consumer API will be required. Truncation length is configurable inside GlobalSetting table, entry ClobDefaultReadSize.

RenderAs

RenderAs is a hint to a Tachyon consumer that gives additional information on how to render given column.

Tachyon Explorer supports two values:

ipAddress - this column's value will be formatted as an IP address, with subnet, mask and other information
preformatted - this column's value will be placed inside a <pre> tag in order to preserve formatting.

Please note this field is just a hint for a Tachyon consumer. It has no effect on how the instruction is processed, how responses are gathered or how the data is stored.

It is up to the consumer to implement support for renderas and decide how to interpret the value. TachyonExplorer supports renderas values used by instruction definitions written by 1E but will not support renderas values introduced by 3rd party.

AggregationJson

Depending on the type of data returned from an instruction, it may be appropriate to summarize/aggregate the data before it is presented. For example, you may wish to create an instruction which counts the number of TCP connections made per process, but instead of displaying the results per-device, you wish to display the results aggregated across all devices.

In other words, instead of seeing results which look like this in Explorer:

Device Name	Process Name	Connection Count
device1.acme.or	iexplore.exe	12
device1.acme.org	svchost.exe	4
device1.acme.org	ccmexec.exe	1
device1.acme.org	outlook.exe	13
device2.acme.org	outlook.exe	12
device2.acme.org	svchost.exe	4
device3.acme.org	iexplore.exe	3
device3.acme.org	svchost.exe	5

Or you may prefer to see results like this:

Process Name	Connection Count
`iexplore.exe`	`15`
`svchost.exe`	`13`
`ccmexec.exe`	`1`
`outlook.exe`	`25`

This can be achieved by defining an “aggregation schema” for the instruction. This is like performing a GROUP BY and an aggregation function(s) (e.g. COUNT, MIN, SUM, etc.) on the data as a whole, rather than on each device’s set of data individually.

In this case, each Tachyon Agent still executes the same instruction and returns the same data, but the Tachyon Server automatically performs aggregation of that data while it is collected.

Aggregation schema is defined in AggregationJson. As the name suggests this is a JSON object. This depends on SchemaJson as aggregation is done on columns defined in SchemaJson.

For example, given the SchemaJson:

Expand source

[
    {
        "Name":  "ProcessName",
        "Type":  "string",
        "Length": "256"
    },
    {
        "Name":  "ConnectionCount",
        "Type":  "Int32"
    }
]

Or if we want to achieve the result described above we will need aggregation schema like:

Expand source

{
   "Schema":[
      {
         "Name":"ProcessName",
         "Type":"String",
         "Length":256
      },
      {
         "Name":"Count",
         "Type":"int32"
      }
   ],
   "GroupBy":"ProcessName",
   "Operations":[
      {
         "Name":"Count",
         "Type":"sum(ConnectionCount)"
      }
   ]
}

and the xml element would look like this:

AggregationJson xml element Expand source

<AggregationJson>
<![CDATA[
{
   "Schema":[
      {
         "Name":"ProcessName",
         "Type":"String",
         "Length":256
      },
      {
         "Name":"Count",
         "Type":"int32"
      }
   ],
   "GroupBy":"ProcessName",
   "Operations":[
      {
         "Name":"Count",
         "Type":"sum(ConnectionCount)"
      }
   ]
}
]]>
</AggregationJson>

From the example we can see aggregation schema has three properties.

Property Name	Required	Description
Schema	Yes	Defines a list of columns that is used to store aggregated data. These column definitions are the same as the column definitions in SchemaJson. This list combines aggregation operation resultant columns as well as columns against which aggregated data is grouped.
GroupBy	Yes	Defines a comma separated list of column names against which aggregated data is summarised. All the columns must be present in SchemaJson.
Operations	Yes	Defines a list of aggregation operations to be performed. Supported operations are count, min, max and sum. Each operation results in a column that needs to be in the aggregation schema.

Supported Aggregation Operations

Type	Description
count	Returns the number of items in the group. Resultant data type is Int32.
min(column_name)	Returns the minimum value for the column in the group. Column must exist in in SchemaJson. Resultant column data type is derived from the source data type.
max(column_name)	Returns the maximum value for the column in the group. Column must exist in in SchemaJson. Resultant column data type is derived from the source data type.
sum(column_name)	Returns the sum of all values for the column in the group. Column must exist in in SchemaJson. Resultant column data type is derived from the source data type.

Aggregation schema columns have to exist in either regular schema (see above) and in the GroupBy field or in the Operations array inside the AggregationSchema itself.

ParameterJson

Tachyon allows users to pass parameters while issuing an instruction. Allowed parameters are defined in ParameterJson. It is made of a collection of JSON objects each representing a parameter.

For example, we want to know what software is installed published by a publisher where publisher is supplied as parameter by the user. The payload looks like:

@allInstallations = Software.GetInstallations();
select * from @allInstallations
where Publisher like '%%publisher%%';

This payload needs publisher value to be passed as parameter. The parameter declaration may look like:

[
   {
      "Name":"Publisher",
      "Pattern":"%publisher%",
      "DataType":"string",
      "ControlType":"freeText",
      "ControlMetadata":"",
      "Placeholder":"enter publisher name",
      "DefaultValue":null,
      "Validation":{
         "Regex":null,
         "MaxLength":256,
         "AllowedValues":null,
         "NumValueRestrictions":null
      }
   }
]

Property Name	Required	Description	Example value
Name	Yes	Name of the parameter. Has to be unique.	MachineAddress
Pattern	Yes	Pattern for the parameter. Has to be unique. This pattern will be substituted with a value provided when an instruction is issued based on this definition. Please note literal text substitution will be performed so ANY text that matches the pattern will be replaced with parameter value. You should therefore make sure your patterns are unique enough so that unwanted text substitution doesn't occur. The pattern does not have to start or end with '%' character, or any specific character and is completely free form.	%MachineAddr%
DataType	Yes	Data type of this parameter. Supported types: int (fixed point integer) float (floating point integer) string (text field) date time	string
ControlType	Yes	Type of control for this parameter which determines what should be shown in the Tachyon Explorer UI. freeText - UI should display a text box where any text will can be entered and will be validated according to validation rules specified in 'Validation' element valuePicker - UI should display a value picker with values. A list of allowed values can be defined in the Validation AllowedValues property. customPropertyKey - UI should display a value picker list of custom property key names of the type specified by Control Metadata customPropertyValue - UI should display a value picker list of custom property values of the type specified by Control Metadata	freeText
Placeholder	No	Placeholder to display in the UI for this parameter	Address of target machine
DefaultValue	No	Default value for this parameter. Default value must be a valid value for the data type of the parameter ie. you can't assign a string default value to a parameter that has int data type.
Validation	No	Validation rules for this parameter: Regex - regular expression, in .NET framework regular expression syntax. Valid only for string free text fields MaxLength - maximum input string length. Valid only for string parameters. AllowedValues - array of allowed values. Valid only for value picker entry type NumValueRestrictions - Not yet supported
ControlMetadata	No	Control metadata. Usage depends on Control Type: freeText - ignored, not required valuePicker - ignored, not required customPropertyKey - must contain type of custom property ie. "CoverageTag" as it exists in the database customPropertyValue - must contain type of custom property ie. "CoverageTag" as it exists in the database
Source	No	Used only by custom property value parameters and ignored by all other control types. Points to a related parameter that has the custom property key to use to pr value. In the example below, note how the "Source" for the customPropertyValue parameter is the same as the "Name" of the customPropertyKey parameter.

Example

Workflow

...

ResponseTemplateConfiguration

A JSON representation of the logic that Tachyon Consumers may use to provide customized rendering of Responses for the Instruction, such as charts and graphs.

This topic is described in more depth here:Custom Response Visualizations.

Resources

This element will contain a collection of Resource elements, each of which will be a single resource used by the instruction. Resources are usually script files, but they can be any file format.

Resource

Resource has a single attribute - Name - by which it is referenced by the script. This element has one child element - Content.

Content

This element contains the actual resource along with some metadata that helps to identify and verify it. All of the metadata attributes are mandatory.

The metadata is in the attributes of the tag:

Attribute name	Description	Example value	Database field
FileName	Name of the file	getSystemInfo.ps1	InstructionDefinitionResource.FileName
Size	Size of the file in bytes	2174	InstructionDefinitionResource.Size
Hash	SHA256 hash of the resource	6051b31bb1a0875f654fcbb5cf5238c1bc249e8a98ed7c0eb685c10db80e2b96	InstructionDefinitionResource.SHA256Checksum
Platform	Platform this resource can be used on. Allowed values are: Windows MacOS Linux	Windows	InstructionDefinitionResource.Platform
Type	Type of resource	Powershell	InstructionDefinitionResource.Type

While the resource itself is inside the CDATA section in the tag in a Base64 encoded form to prevent issues with illegal characters.

Example Resources section

<Resources>
    <Resource Name="GetSystemInfo">
        <Content
            FileName="getSystemInfo.ps1"
            Size="2174"
            Hash="6051b31bb1a0875f654fcbb5cf5238c1bc249e8a98ed7c0eb685c10db80e2b96"
            Platform="Windows"
            Type="PowerShell"><![CDATA[cGFyYW0oDQo...]]></Content>
    </Resource>
</Resources>

TaskGroups

Inside this element you will find a collection of TaskGroup elements. Instruction can belong to more than one TaskGroup.

TaskGroup

Each TaskGroup element has a single a attribute - Name - which defines an arbitrary path to a Task group underneath which this instruction should appear.

If that path does not exist it is created (the TaskGroup entries are created),

Example TaskGroups

<TaskGroups>
    <TaskGroup Name="Software Vendors\Microsoft\Configuration Manager" />
</TaskGroups>

XSD schema

The following XSD can be used to validation Instruction Definition XML files.

XSD schema Expand source

<?xml version="1.0" encoding="utf-8"?>

<xs:schema elementFormDefault="qualified"
           attributeFormDefault="unqualified"
           targetNamespace="http://schemas.1e.com/Tachyon/InstructionDefinition/1.0"
           xmlns="http://schemas.1e.com/Tachyon/InstructionDefinition/1.0"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="InstructionDefinition">
    <xs:complexType>
      <xs:all>
        <xs:element name="Payload" type="xs:string" minOccurs="1" maxOccurs="1" />
        <xs:element name="SchemaJson" type="xs:string" minOccurs="1" maxOccurs="1" />
        <xs:element name="AggregationJson" type="xs:string" minOccurs="0" maxOccurs="1" />
        <xs:element name="ParameterJson" type="xs:string" minOccurs="0" maxOccurs="1" />
        <xs:element name="Workflow" type="xs:string" minOccurs="0" maxOccurs="1" />
        <xs:element name="ResponseTemplateConfiguration" minOccurs="0" maxOccurs="1" />
        <xs:element name="Comments" minOccurs="0" maxOccurs="1" />
        <xs:element name="Resources" minOccurs="0" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Resource" type="resourceType" minOccurs="1" maxOccurs="unbounded" />
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="TaskGroups" minOccurs="0" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="TaskGroup" type="taskGroupType" minOccurs="1" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:all>
      <xs:attribute name="Name" type="xs:string" use="required" />
      <xs:attribute name="InstructionType" use="required">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="Question" />
            <xs:enumeration value="Action" />
            <xs:enumeration value="EventSubscription" />
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="Description" type="xs:string" use="required" />
      <xs:attribute name="ReadablePayload" type="xs:string" use="required" />
      <xs:attribute name="InstructionTtlMinutes" type="xs:unsignedInt" use="required" />
      <xs:attribute name="ResponseTtlMinutes" type="xs:unsignedInt" use="required" />
      <xs:attribute name="Version" type="xs:string" use="required" />
      <!-- The following attributes end up the in 'Restrictions' field on InstructionDefinition -->
      <xs:attribute name="MinimumInstructionTtlMinutes" type="xs:unsignedInt" use="optional" />
      <xs:attribute name="MaximumInstructionTtlMinutes" type="xs:unsignedInt" use="optional" />
      <xs:attribute name="MinimumResponseTtlMinutes" type="xs:unsignedInt" use="optional" />
      <xs:attribute name="MaximumResponseTtlMinutes" type="xs:unsignedInt" use="optional" />
      <xs:attribute name="Author" type="xs:string" use="optional" />
    </xs:complexType>
  </xs:element>
  <xs:complexType name="resourceType">
    <xs:sequence>
      <xs:element name="Content" type="contentType" minOccurs="1" maxOccurs="unbounded" />
    </xs:sequence>
    <xs:attribute name="Name" use="required"/>
  </xs:complexType>
  <xs:complexType name="contentType">
    <xs:simpleContent>
      <xs:extension base="xs:string">
        <xs:attribute name="Type" type="xs:string" use="required" />
        <xs:attribute name="FileName" type="xs:string" use="required" />
        <xs:attribute name="Size" type="xs:unsignedLong" use="required" />
        <xs:attribute name="Hash" type="xs:string" use="required" />
        <xs:attribute name="Platform" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="Windows" />
                            <xs:enumeration value="MacOS" />
              <xs:enumeration value="Linux" />
                          </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
      </xs:extension>
    </xs:simpleContent>
    <!-- Can use this online tool to generate hash - https://md5file.com/calculator -->
  </xs:complexType>
  <xs:complexType name="taskGroupType">
    <xs:attribute name="Name" type="xs:string" use="required" />
  </xs:complexType>
</xs:schema>

In this section:

1E 23.7 (SaaS)