Skip to main content

1E SDK

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.

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.

233276233.png

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.

233276232.png

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.

233276231.png

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.

233276230.png

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

233276229.png

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

233276228.png
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

233276205.png

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 (\).

233276227.png

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>