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.
Note
Instruction names must be less than 64 characters in length, otherwise 1E platform will return an error, and the instruction will not be saved.
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.
Note
The default instruction type for a new instruction was a question up to TIMS 5.1, but from TIMS 5.2 it is an action. This is to ensure that potentially dangerous instructions require authentications and authorisation by default. If the instruction is harmlessly "read only" then change it to a question.
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"
Tip
The definitions of each element of an Instruction definition are decribed in the Instruction Definition Reference. The guidance below refers to most elements but not all.
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.
Note
You can also see any validation errors at any time by pressing the Validate toolbar button
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).
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
Note
The 'render as' field is an optional field and will not be used in this example.
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
Tip
See Instruction Definition Reference (SchemaJson) for more detail about Schema.
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.
Note
You can enter multiple task groups, and you can also create task group hierarchies, by separating each part of the task group name with a backslash (\).
Press OK to save changes
Tip
See Instruction Definition Reference (TaskGroups) for more detail about Task Groups.
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>