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>

In this section:

1E SDK