Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Summary

Excerpt

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 introduced in Tachyon 3.1, with highlighted changes introduced by later versions. Many of the concepts, terminology and definitions also apply to earlier versions of Tachyon.

This page assumes basic familiarity with XML and JSON formats.


Panelbox
namegrey
titleOn this page:

Table of Contents
maxLevel3
minLevel2
indent20px
excludeSummary|On this page|In this section...
separatornewline


Terminology

You should understand the following terms before reading further:

TermExplanation
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 PayloadThe 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.

Info
titleProduct 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.


Note
titleOld product packs

Tachyon 3.1 introduced a new instruction definition XML schema compared to earlier versions of Tachyon, which means you cannot use old product packs on new systems and vice versa. Amongst other things, the schema for 3.1 means a XML file encapsulates everything that relates to an instruction including resources, whereas previously the instruction XML and resource files were separate and included a zipped folder structure called a Product Pack.


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 SignatureA 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:

Code Block
titleInstruction 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.

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

ElementRequiredPurposeDatabase column
InstructionDefinitionYes

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\PayloadYes

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\CommentsNoContains optional comments about the Instruction Definition provided by the author.InstructionDefinition.Comments
InstructionDefinition\SchemaJsonYes

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\AggregationJsonNo

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\ParameterJsonNo

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\WorkflowNoA 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\ResponseTemplateConfigurationNo

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\ResourcesNoA container element for one or more <Resource> child elements, which define the content for embedded resources for this Instruction Definition.N/A
InstructionDefinition\Resources\ResourceYesDefines the name of a resource, and contains one or more <Content> child elements.InstructionDefinitionResource table
InstructionDefinition\Resources\Resource\ContentYes

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\TaskGroupsNoA container element for one or more <TaskGroup> child elements.N/A
InstructionDefinition\TaskGroups\TaskGroupYesDefines the path of a Task Group under which this Instruction Definition should be grouped.TaskGroups and Task
InstructionDefinition\SignatureNoContains 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.

Info
titleDigital 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

Code Block
languagexml
firstline1
titleSample Instruction Definition
linenumberstrue
collapsetrue
<?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.

Info
titleXML 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.


Note
titleCase Sensitivity

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


Info
titleJSON 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 NameRequiredDataTypeDatabase MappingDescriptionExample value(s)
xmlnsYesstring
References the XML namespace corresponding to the schema for Tachyon Instruction Definitions. http://schemas.1e.com/Tachyon/InstructionDefinition/1.0
NameYesstringInstructionDefinition.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

InstructionTypeYesstring (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, Action and EventSubscription.

Use Question

 

  • Question - use when the instruction will not alter the state of any device on which it runs.
  • Use Action - use when the instruction may modify the state of a device on which it runs.Use EventSubscription when the instruction
Warning
titleDeprecated

Prior to v5.0, EventSubscription was used to indicate an instruction that includes a Subscribe statement in its Payload to return results over the time it is active.

Warning
titleDeprecated

The eventing infrastructure was deprecated in v3.0 and fully removed in v4v5.20. This means that all references to EventSubscription are no longer applicable from this version v5.0 onwards.


Question

Action

EventSubscription

DescriptionYesstringInstructionDefinition.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.

ReadablePayloadYesstringInstructionDefinition.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

InstructionTtlMinutesYesunsigned integerInstructionDefinition.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
ResponseTtlMinutesYesunsigned integerInstructionDefinition.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
VersionYesstring (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

MinimumInstructionTtlMinutesNounsigned 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, entry DefaultInstructionTtlMinutes "Minimum" is used.

10
MaximumInstructionTtlMinutesNounsigned integerInstructionTtlRange.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, entry DefaultInstructionTtlMinutes "Maximum" is used.

20
MinimumResponseTtlMinutesNounsigned integerResponseTtlRange.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, entry DefaultResponseTtlMinutes is used.

10
MaximumResponseTtlMinutesNounsigned integerResponseTtlRange.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, entry DefaultResponseTtlMinutes is used.

60
AuthorNostringInstructionDefinition.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.exe12
svchost.exe4
ccmexec.exe1
outlook.exe13

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

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

and the actual XML element would look like this:

Code Block
languagexml
titleSchemaJson xml element
<SchemaJson>
<![CDATA[
[
    {
        "Name":  "ProcessName",
        "Type":  "string",
        "Length": "256"
    },
    {
        "Name":  "ConnectionCount",
        "Type":  "Int32"
    }
]
]]>
</SchemaJson>

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

Anchor
schemaColumnProperties
schemaColumnProperties

Property NameRequiredDescription
NameYesColumn name.
TypeYesDefines 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.
LengthNoApplicable only to String data type but not mandatory to have. If none specified, no size restriction is applied.
RenderAsNoDefines 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

NameDescription
BoolPossible values are either true or false.
Int32Can store any integer value between -2,147,483,648 and 2,147,483,647 inclusive.
Int64Can store any integer value between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 inclusive.
StringCan 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.
DataTimeOffsetCan store date/time along with timezone offset.
GuidCan 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.


Tip
iconfalse

3.2


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:

Code Block
languagejs
collapsetrue
[
    {
        "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:

Code Block
languagejs
collapsetrue
{
   "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:

Code Block
languagexml
titleAggregationJson xml element
collapsetrue
<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 NameRequiredDescription
SchemaYesDefines 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.
GroupByYesDefines a comma separated list of column names against which aggregated data is summarised. All the columns must be present in SchemaJson.
OperationsYesDefines 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

TypeDescription
countReturns 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:

Code Block
languagesql
@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:

Code Block
languagejs
[
   {
      "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 NameRequiredDescriptionExample value
NameYesName of the parameter. Has to be unique.MachineAddress
PatternYes

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%
DataTypeYes

Data type of this parameter. Supported types:

  • int (fixed point integer)
  • float (floating point integer)
  • string (text field)
  • date
  • time
string
ControlTypeYes

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
PlaceholderNoPlaceholder to display in the UI for this parameterAddress of target machine
DefaultValueNo

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.


ValidationNo

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

ControlMetadataNo

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


SourceNo

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

TODO

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 nameDescriptionExample valueDatabase field
FileNameName of the filegetSystemInfo.ps1InstructionDefinitionResource.FileName
SizeSize of the file in bytes2174InstructionDefinitionResource.Size
HashSHA256 hash of the resource6051b31bb1a0875f654fcbb5cf5238c1bc249e8a98ed7c0eb685c10db80e2b96InstructionDefinitionResource.SHA256Checksum
Platform

Platform this resource can be used on.

Allowed values are:

  • Windows
  • Android
  • MacOS
  • Linux
  • Solaris
WindowsInstructionDefinitionResource.Platform
TypeType of resourcePowershellInstructionDefinitionResource.Type

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

Code Block
languagexml
titleExample 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),

Code Block
languagexml
titleExample TaskGroups
<TaskGroups>
    <TaskGroup Name="Software Vendors\Microsoft\Configuration Manager" />
</TaskGroups>


XSD schema

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

Code Block
languagexml
firstline1
titleXSD schema
linenumberstrue
collapsetrue
<?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="Android" />
              <xs:enumeration value="MacOS" />
              <xs:enumeration value="Linux" />
              <xs:enumeration value="Solaris" />
            </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>