Skip to main content

1E 23.7 (SaaS)

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

233276245.png
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>