1E 23.11 (SaaS)

Select File/Save or File/Save As from the TIMS main menu.

In this case you will see a set of validation errors that need to be addressed before the file can be saved.

Mandatory Settings

We will now correct the errors by adding a payload and description to the property pane.

Description

• should explain what the instruction does

• should contain useful words that will help searches

• useful to contain details such as platforms it will run on, if it downloads a script, or any restrictions

Name

• The name must be unique within your Tachyon system; you cannot load two instruction XML files into Tachyon that share a common name. If you do, the second file will overwrite the contents of the first.

• A default name has automatically been filled in

  • the first time you start TIMS the prefix is based on your Active Directory Domain Name

  • you can change the default name in Tools→Preferences

ReadablePayload

• is exactly what you see in the Tachyon Explorer when searching for questions and actions

• helps to be a grammatically correct question or action statement

• if the instruction has Instruction Parameters then these must be included so that Explorer users can see and enter the parameters.

Version

• can be a single digit or a dotted notation with 2, 3 or 4 parts.

When using Tachyon Explorer to search for instructions, the search will parse the ReadablePayload and Description fields.

Tip

See Instruction Definition Reference (InstructionDefinition) for descriptions of the other settings (elements).

The schema defines how the instruction output is actually displayed in Tachyon Explorer.

You must define the schema, or format, of the information that will be displayed in Tachyon Explorer, which may be different to what is actually output by the instruction and returned by the Tachyon client to the Server. You would not normally want to send back more data than you want to display.

The schema also defines how the data will be rendered. Normally, you would code your instruction so that its output column names are the same as you want to display. However they may be circumstances when you prefer to use the schema definition to change column names, or reformat or render in a different way.

Press the schema button to define or modify the schema.

TIMS can infer a schema based on the data returned by your instruction, or you can manually define one.

If you select No in the above dialog you will be presented with an empty schema dialog like this.

Use the + button to add a new schema entry, specifying the column name, data type and (optionally) the length

If you select Yes in the above dialog, TIMS will attempt to infer a schema by examining the results that running the instruction produced

However in the latter case, note that the column name is not valid. You will be notified of this when you try and confirm the schema by pressing OK

The 'render as' schema item property

This field allows you to select a rendering scheme which will be applied to the column when it is displayed in the Tachyon Explorer.

There are three rendering schemes currently available

• preformatted

• ipAddress

• currency

The screenshot below shows the effect of each of these.

• The Remote Address column has been associated with the ipAddress rendering scheme.

• The process ID column has been associated with the currency rendering scheme.

• The Process Name column has been associated with the preformatted rendering scheme

Tip

See Instruction Definition Reference (SchemaJson) for more detail about Schema.

You will receive a warning if you try and re-save the file, that you have not associated this instruction XML file with any task group in Tachyon. Task groups allow you to associate instructions with specific tasks in Tachyon, which are visible from the Tachyon Explorer task pane.

It is not mandatory to associate an instruction XML file with a task group.

If you wish to do so, click the Task groups button on the TIMS toolbar

Enter a task group name and press the + button to add the task group name.

Press OK to save changes

You have now addressed all the validation errors and warnings and have a valid instruction XML file.

Select Save or Save As and specify the file name if required.

This is what the generated XML file looks like, at this point

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<InstructionDefinition Author="Andrew.Mayo" Name="1E-NewInstruction-1" ReadablePayload="What time is it" Description="What time is it" InstructionType="Question" InstructionTtlMinutes="10" ResponseTtlMinutes="10" Version="1.0" xmlns="http://schemas.1e.com/Tachyon/InstructionDefinition/1.0">
  <Payload><![CDATA[SELECT "%environment:now%";

]]></Payload>
  <SchemaJson><![CDATA[[
  {
    "Name": "currenttime",
    "Type": "string",
    "Length": 64
  }
]]]></SchemaJson>
  <TaskGroup>
    <TaskGroup Name="New Task" />
  </TaskGroup>
</InstructionDefinition>

Once a resource has been embedded, TIMS shows it in the script pane footer, like this

Click on the resource dropdown to see the available resource management options

The Insert Snippet to Download option inserts code to download the resource programmatically. For example, for the PowerShell resource we embedded, the snippet will look like this

@resource1 = HttpGetFile(URL:"setperm.ps1", Size:269, Hash:"8943cb3a1e6a848bbe52014bd1c082e4841060791b7ce8c1f9f3b349c3bd8b64");

When your instruction is deployed in the Tachyon environment, the above HttpGetFile request will download the resource file from the Tachyon server content endpoint URL.

However while you are developing your instruction in TIMS, when the HttpGetFile is executed, TIMS will instead retrieve the embedded resource from its internal memory and populate the result variable, just as if the file had actually been downloaded.

The Edit option will display the resource dialog we saw previously. You can amend any resource property from this dialog.

You can also select the two options which were mentioned previously.

The resource is removed from the instruction XML file.

If you add more parameters, then when you run an instruction you see all parameters and their current values in the parameters dialog, like this

As with resources, parameters that have been added are shown in the footer pane of the script pane, like this

Click on a parameter dropdown to see the parameter menu.

Remove

This option removes (deletes) the parameter. Any references to the parameter in instruction code will also be removed, and replaced with the current value of the parameter. For example, if I remove the %WhoAmI% parameter my code changes to

select "Andrew";

The parameter dialog shows a number of parameter properties which control how it appears in the Tachyon Explorer along with default values, validation patterns and so forth. Because each field has a descriptive tooltip that appears when you hover over it, I will not repeat this information in the documentation here.

Press the schema button and modify the schema to return two columns, myval1 and myval2 of type int32

Press OK and then modify the instruction to read

select 1 myval1, 2 myval2;

Run the instruction and observe that values are returned for the two columns

We will now define an aggregation for the results. This will control how the Tachyon server processes the raw results from each endpoint when this instruction is executed

Enable aggregation and select a 'group by' column

First you must tick the 'Enable aggregation checkbox

Then select the column you wish the results to be grouped by on the server side. In this case we have selected that the results should be grouped by the 'myval1' column, by clicking the column name and then clicking the Group By button

Choose an aggregation operation and a target column

Choose 'sum' from the operation dropdown list and choose the myval2 column from the column dropdown list

We will name the result 'SumofMyval2'

Then click Add to add the aggregation operation

Press Ok to save changes

The aggregation data is added to the instruction XML file. It will look like this (note: the XML has been reformatted for clarity)

 <AggregationJson>
        <![CDATA[
                        {"Schema":[
                                                {"Name":"myval1","Type":"int32","Length":"0"},
                                                {"Name":"SumOfMyval2","Type":"int64","Length":"0"}
                                          ],
                                                "GroupBy":"myval1","Operations":[{"Name":"SumOfMyval2","Type":"sum(myval2)"}]}
        ]]>
</AggregationJson>

When data is collected by the Tachyon client, the results will be grouped by the value of the myval1 column for all devices that respond. Then, the myval2 column will show the sum of the values of each device's myval2 column results, for that particular grouping value returned in myval1. For example:

Raw data collected from all endpoints

Device	myval1	myval2
D1	1	2
D1	1	3
D2	1	4
D2	2	1
D3	2	5

Aggregated data

myval1	SumofMyval1
1	9
2	6

You can then 'drill down' by clicking on any aggregated row to view the raw data that was aggregated to produce the results.

Just as you can group by multiple columns, you can compute aggregated results multiple times, either for the same column or for different columns.

These columns cannot be part of the aggregate grouping columns, however.

In the example below we compute both the sum of the myval2 columns returned and the minimum value of the myval2 columns.

The 'enable aggregation' checkbox in the aggregation dialog allows you to disable aggregation at any time. However, note that if you do this, your current aggregation settings are immediately lost when you close the dialog.