Using TIMS

Installing TIMS

Please refer to Installing TIMS.

Starting TIMS

Double-click on the shortcut or executable Tachyon.InstructionManagementStudio.exe

You may be see a UAC prompt from 1E Client.

Starting TIMS in SYSTEM context

Sometimes you may need to develop and test your instructions in SYSTEM context, in order to replicate how the Tachyon client runs actually runs.

You can do this by starting TIMS using Microsoft SysInternal's PSEXEC utility.

1. Copy PSEXEC utility to a known path, eg. Windows\System32 folder, or to the same folder as TIMS.
2. In the TIMS folder, create a command file called StartTIMS.cmd containing the instructions shown below
3. Create a shortcut to the cmd file, and use this to start TIMS using Run As Administrator
4. If you are using PSEXEC64 then edit the cmd file accordingly.

:: Used to start TIMS in SYSTEM security context
:: PSEXEC.EXE should exist in local folder or a system path
:: This script should exist in the TIMS folder
:: Create shortcut and use Advanced to set as Run as administrator
@pushd %~dp0
:: create default folder for SYSTEM to avoid popups
@md "%SYSTEMROOT%\system32\config\systemprofile\Desktop" 2>nul
:: Set folder option to see file extensions
@reg add HKEY_USERS\S-1-5-18\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced /v HideFileExt /t REG_DWORD /d 0 /f
:: Start TIMS in SYSTEM context
PsExec.exe -s -i -d "%~dp0Tachyon.InstructionManagementStudio.exe"
:: Stop and display error if Psexec not found, or not admin
@if %ERRORLEVEL% == 9009 @pause>nul
@if %ERRORLEVEL% == 5 @pause>nul

The TIMS user-interface

You can execute your script by clicking on Run or pressing F5.

You can highlight part of your script and then execute.

You can increase the size of the text in the script pane by using Zoom on your mouse (Ctrl+scroll up and down).  

Results are shown in the bottom panel by clicking on the Results tab. You can click on any column heading to sort the results. In TIMS, columns are displayed in alphabetic A-Za-z order, not necessarily in the order defined in the instruction. The order they appear in Tachyon Explorer may be different as well and is defined by the Schema as described in Adding a schema. The Schema allows you to pick which columns are included in the response to the Server.

If you get an error, such as 'syntax error in instruction' then review the log by clicking on the Log tab as the bottom of the TIMS window. You can disable log scrolling by unchecking the Auto-scroll log tickbox. The log will periodically scroll as the client performs background tasks, such as updating the Tachyon Activity Record tables.  See also Instruction Exit Codes.

You can adjust TIMS window and panel positions:

• entirely hide the top pane temporarily by clicking the 'Hide top pane' icon. Click it again to re-display the top pane
• adjust the relative size of the top and bottom panes of TIMS by dragging the horizontal splitter bar
• adjust the relative size of the script and instruction definition panes by dragging the vertical splitter bar in the top pane.

Use the F11 button to toggle visibility of the top pane (the script and instruction definition). Hiding the top pane is useful to display the bottom pane (results and log details).

Quick verification that TIMS is working

Enter the line of text

SELECT "%environment:now%";

Click the Run icon.

You should see the current date/time as shown below

Creating an Instruction XML file

Instruction XML files allow code written in TIMS to be uploaded to the Tachyon server, so that the instructions can be invoked by asking a question or requesting that an action be performed.

About questions and actions

• Questions  are instructions that can be searched for, and invoked, directly from the Tachyon Explorer 'I want to know' page. Questions should generally not alter the state of any endpoint on which they are run.

• Actions  are instructions that can only be searched for and invoked once an initial question has been asked. You 'follow up' the initial question either by asking further questions or by invoking actions.

Suppose that we want to create a new instruction XML file from our example above. It will perform the incredibly useful function of telling us "What time is it"

Validating the file

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.

Adding a schema

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

Alter the column name to a valid name

Alter the column name to 'currenttime'. You will now be able to save the schema

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

Adding a task group

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

Saving the instruction XML file

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.

Examining the XML file

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>

Adding resources

Resources are additional files that are required when executing instructions in an instruction XML file. Resources are downloaded from the Tachyon content URL by the Tachyon client, when they are accessed.

TIMS embeds resources directly into the instruction XML file, so that when this is loaded into Tachyon, the embedded resources are automatically extracted and copied to the Tachyon content URL.

To add a resource, click the Import Resource toolbar in the TIMS menu. Browse to the file and select it.

TIMS will automatically determine the resource type and compute its SHA-256 hash and size as shown in the dialog below

The options 'update this resource from a file' and 'save this resource to a file' will be discussed shortly. They are mainly useful when managing already-embedded resources.

Press OK to insert the resource. The code block below shows how the instruction XML file looks after the resource has been embedded. Note that the base-64 encoding of the resource has been truncated for clarity.

<Resources>
    <Resource Name="setperm">
      <Content Type="PowerShell" FileName="setperm.ps1" Size="269" Platform="Windows" Hash="8943cb3a1e6a848bbe52014bd1c082e4841060791b7ce8c1f9f3b349c3bd8b64">
		<![CDATA[JGFjbD1nZXQ.................]]>
	  </Content>
    </Resource>
  </Resources>

Managing embedded resources

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

Insert Snippet to Download

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");

Resource downloading in the TIMS environment

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.

Edit 

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.

Update this resource from a file

When this option is selected, you will be prompted to select a file. The file contents completely replace the current resource.

Save this resource to a file

When this option is selected, you will be prompted to enter a file name. A copy of the resource is saved to the file you specify

Remove

The resource is removed from the instruction XML file.

Instruction Parameters

Our example instruction did not require any input parameters. For instructions that require parameters, TIMS allows you to define each parameter, along with its type, and various other attributes.

If you specify a parameter in TIMS, you will be prompted to enter a parameter value each time you run the instruction. The previous entry entered during that editing session is remembered.

Parameter properties

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.

Aggregation

Instruction results can be automatically aggregated by Tachyon, so that when a user clicks on an aggregated result, Tachyon then 'drills down' and displays the data that was aggregated.

To aggregate results you need to return at least two columns from the instruction.

One column will be used to group the results. Results in each group are then aggregated by one or more of the remaining columns in the result set. Aggregation means computing some value across all the results, such as their sum, min, max etc.

We will modify the instruction schema and instruction that we have been working with in order to set up aggregation.

Configure Aggregation

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

Aggregated data 

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

Computing multiple aggregated 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.

Enabling and disabling aggregation

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.

Workflow

Tachyon questions and actions are associated with workflow definitions which define how the questions and actions are processed when they are submitted.

There are two global workflow settings which are used by default.

One global workflow setting is associated with questions, and one with actions.

You can override the global defaults for an instruction by clicking the workflow button in the toolbar

Choosing the empty dropdown option means that the default globally configured workflow option will be used when the instruction is run. The global default will depend on whether the instruction is a question or action

Otherwise, choosing an alternative workflow option will override the global default for the instruction.

Workflow options are discussed in more detail in the documentation on Tachyon Workflow

If workflow is overridden, the instruction XML file will contain a workflow section, such as this

<Workflow><![CDATA[{"StateMachine":"State with Approval"}]]></Workflow>

Digital signing

You can choose whether or not the instruction XML is digitally signed, and if so, whether or not you should be prompted to sign it when saving an instruction definition.

Instructions...

• do not need to be signed if you only want to develop and test instructions locally in TIMS, or share with other developers
• must be signed with an appropriate code signing certificate if you want to import instructions into a Tachyon system and run them, as described in Running instructions in Tachyon for the first time.

In order to use any of the signing options, you must have an appropriate certificate. The certificate and its private key must be available to the user running TIMS and must be placed in the user's personal store.

The Digital Signing menu allows you to select a signing certificate that has previously been imported into your certificate store. If the menu cannot locate a Code Signing certificate, the following warning dialog appears.

Templates

Templates allow you to add visualisation capabilities to your instruction. Visualisation allows you to show results graphically in a variety of formats, as opposed to simply showing tabular results.

At present TIMS does not support the manipulation of visualisations, and requires you to copy a template XML directly into the Template panel, which is then saved as part of the instruction definiation.

The TIMS menu

Above the toolbar, the TIMS menu provides additional functionality.

The File menu

The file menu allows you to

• Open, Save and Save As Instruction XML file (the full definition capable of being imported into a Tachyon system)
• Browse folders containing Instruction XML files
• Import and Export as a *.txt file (just the script text)
• Reset the current instruction definition to an empty starting point
• Exit TIMS

Opening and Saving instructions

The Open option allows you to load an instruction from an existing instruction XML file. This will replace any existing script and instruction settings.

You will be warned if the instruction you are currently editing has any unsaved changes.

The Save and Save As options allow you to save an instruction XML file.

TIMS will validate an instruction before it is saved, as described in Validating the file.

Save warnings

When saving, you will be given various warnings asking if you wish to continue?

• You have changed the instruction in the editor without running it.

Validation warnings will be displayed before you can continue saving:

• No task groups defined

Save errors

Validation errors will be displayed which must be corrected before you can try again.

• No Description, Name or ReadablePayload
• No schema

Currently, TIMS does not enforce Version, but this is actually mandatory. Version should be entered as Major.Minor.

Importing and exporting scripts

The Import Script option allows you to load script text into the script pane from an existing TIMSS script TXT file. All existing schema, aggregation, workflow and parameter settings remain unchanged. You are NOT warned if the script you are currently editing has any unsaved changes.

The Export Script option allows you to save the script text in the script pane as a separate TIMS script TXT file.

The Edit menu

The Edit menu supports the following operations on script text in the script pane.

The Tools menu

The tools menu allows you to view the agent properties, loaded modules and change preferences.

Agent properties

The agent properties dialog shows the current properties of the endpoint device

Loaded modules

The loaded modules dialog shows all the DLLs loaded by TIMS. If you are familiar with the names of Agent language modules and methods, then you will notice the DLLs have the similar names, however some modules appear missing because they are are combined into DLLs. 

As stated before, TIMS has a version of th eAgent runnig in a sanbox, so this list reflects those versions and any extensibles that may have been added.

Preferences

The preferences dialog allows you to change the prefix associated with instruction names. 

Tachyon's licensing system uses name prefixes to control which instructions can be uploaded and used. For an instruction to use a name prefix, the prefix (pattern) must be registered in your Tachyon system's license file (obtained from1E) along with details of each code signing certificate that can use that prefix. All the instructions which you sign should have the same prefix that is unique within your Tachyon system. Do not prefix your instructions with 1E.

Specifying a prefix saves time by pre-populating the Name field in the instruction definition, so that you only need to add the unique part of your instruction name.

The Help menu

The help menu displays the version of TIMS. This is usually the same as the version of the Tachyon Agent included with TIMS, but to find the actual version of the Agent go to Tools → Agent properties... → Agent version.