Version: 9
restore

Contents

Introduction

On this page we will look at uploading instruction definitions into the system and organising them into sets.

Instruction Definitions

Uploading Instruction Definitions

Deleting Instruction Definitions

Instruction Sets

Instruction sets are containers that hold instruction definitions. Permissions are assigned to instruction sets and not to individual instructions.

Instruction sets can contain any number of instructions and cannot be nested.

Any given instruction definition can only be assigned to one instruction set or to no set at all at any particular time. This means an instruction definition cannot belong to multiple instruction sets at the same time, but doesn't have to belong to a set either.

If an instruction definition doesn't belong to an instruction set, you cannot issue instructions based on that instruction definition.

Adding an Instruction Set

To add an instruction set all you need is a name. This name needs to be unique and no two instruction sets can have the same name.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request with following payload:

Payload sent to https://my.tachyon.server/Consumer/InstructionSets
{
  "Name": "Hardware questions"
}

will yield following response:

Return payload
{
    "Id": 1,
    "Name": "Hardware questions",
    "Description": null,
    "Icon": null
}

Use InstructionSets object inside the Tachyon connector instance.

Creating an Instruction Set
var payload = new Tachyon.SDK.Consumer.Models.Send.InstructionSet
{
    Name = "Hardware questions"
};

var response = connector.InstructionSets.Add(payload);

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

An instruction set can also have a description and an icon.

The icon can be supplied either directly as binary data inside the "Icon" parameter or as the same binary data encoded in a base64 string supplied in "IconInBase64" parameter.

"UseIcon" parameter is a flag indicating if an icon should be used.

If this flag is set to true, icon will be used in following way:

  • If Icon field (byte array) is supplied, it will be used as the icon.
  • If Icon isn't supplied and IconInBase64 is supplied, it will be used as the icon.
  • If both Icon and IconInBase64 are supplied, Icon will be used and IconInBase64 will be ignored.
  • If neither Icon or IconInBase64 were supplied, icon will not be used and if there already was an icon assigned to the instruction set, it will be removed.

If this flag is set to false, no changes will be made to the icon. Both Icon and IconInBase64 fields are ignored.


Now we will create an Instruction Set with a description and an icon.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request with following payload:

Payload sent to https://my.tachyon.server/Consumer/InstructionSets
{
  "Name": "Hardware questions",
  "Description": "This is a description",
  "UseIcon": true,
  "Icon": [<binary data here>]
}

will create an instruction set that uses binary data inside Icon. In order to use binary data encoded as base64 string make POST request with following payload:

Payload sent to https://my.tachyon.server/Consumer/InstructionSets
{
  "Name": "Hardware questions",
  "Description": "This is a description",
  "UseIcon": true,
  "IconInBase64": "<binary data encoded as base64 here>"
}

Both POST calls will yield following response:

Return payload
{
    "Id": 1,
    "Name": "Hardware questions",
    "Description": "This is a description",
    "Icon": [<binary data here>]
}

because the icon is always returned in its binary form

Use InstructionSets object inside the Tachyon connector instance.

To create an instruction set that uses an icon supplied as a binary array you can use code below and supply the icon inside binaryData variable

Creating an Instruction Set
var payload = new Tachyon.SDK.Consumer.Models.Send.InstructionSet
{
    Name = "Hardware questions",
    Description = "This is a description",
    UseIcon = true,
    Icon = binaryData
};

var response = connector.InstructionSets.Add(payload);

To create an instruction set that uses an icon supplied as binary data encoded in a base64 string, you can use code below and supply the icon inside encodedData variable

Creating an Instruction Set
var payload = new Tachyon.SDK.Consumer.Models.Send.InstructionSet
{
    Name = "Hardware questions",
    Description = "This is a description",
    UseIcon = true,
    IconInBase64 = encodedData
};

var response = connector.InstructionSets.Add(payload);

In either case, response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

Editing an Instruction Set

To edit an instruction set you will need its Id.

You can modify all properties of an instruction set, apart from the Id, and icon follows the same rules as were outlined in the paragraph above.

This means the payload will look almost the same as what we've used to create an instruction set, with the addition of Id, and we will be making PUT requests instead of POST.

Direct Consumer API callC# code using Consumer SDK library

Making a PUT request with following payload:

Payload sent to https://my.tachyon.server/Consumer/InstructionSets
{
  "Id": 1,
  "Name": "Hardware instructions"
}

will yield following response:

Return payload
{
    "Id": 1,
    "Name": "Hardware instructions",
    "Description": null,
    "Icon": null
}

providing the instruction set with the Id of 1 didn't have an icon.

Use InstructionSets object inside the Tachyon connector instance.

Updating an Instruction Set
var payload = new Tachyon.SDK.Consumer.Models.Send.InstructionSet
{
   Id = 1,
   Name = "Hardware instructions"
};

var response = connector.InstructionSets.Update(payload);

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

Deleting an Instruction Set

An instruction set can be deleted, which will cause all instruction definitions that belonged to it to become unassigned.

Direct Consumer API callC# code using Consumer SDK library
Make a DELETE request to https://my.tachyon.server/Consumer/InstructionSets/Id/1

Use InstructionSets object inside the Tachyon connector instance.

Deleting an Instruction Set
connector.InstructionSets.Delete(1);

You can also delete an instruction set along with all instruction definitions within that set. This option should be exercised with caution as it will permanently remove the instruction definitions.

Direct Consumer API callC# code using Consumer SDK library
Make a DELETE request to https://my.tachyon.server/Consumer/InstructionSets/Id/1?deleteContent=true

Use InstructionSets object inside the Tachyon connector instance.

Deleting an Instruction Set with all Instruction Definitions in that set
connector.InstructionSets.DeleteWithContents(1, true);

One thing to remember is that you cannot delete Instruction Definitions that have pending or in-flight Instructions or Scheduled Instructions, so trying to delete an Instruction Set with contents that has instruction definitions like that will fail.

Getting Instruction Sets

In the first example we will retrieve all instruction sets available.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to https://my.tachyon.server/Consumer/InstructionSets will yield following response

Return payload
[{
    "Id": 1,
    "Name": "Hardware instructions",
    "Description": "This pack contains questions and actions dealing with hardware",
    "Icon": null
},{
    "Id": 2,
    "Name": "Software instructions",
    "Description": "This pack contains questions and actions dealing with software",
    "Icon": null
},{
    "Id": 3,
    "Name": "Patch success instructions",
    "Description": null,
    "Icon": null
}]

Use InstructionSets object inside the Tachyon connector instance.

Retrieving all Instruction Sets
response = connector.InstructionSets.GetAll();

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

You can also retrieve all instruction sets along with the count of instruction definitions that belong to each set.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to https://my.tachyon.server/Consumer/InstructionSets will yield following response

Return payload
[{
    "Id": 1,
    "Name": "Hardware instructions",
    "Description": "This pack contains questions and actions dealing with hardware",
    "Icon": null,
    "CountOfDefinitions": 22
},{
    "Id": 2,
    "Name": "Software instructions",
    "Description": "This pack contains questions and actions dealing with software",
    "Icon": null,
    "CountOfDefinitions": 37
},{
    "Id": 3,
    "Name": "Patch success instructions",
    "Description": null,
    "Icon": null,
    "CountOfDefinitions": 8
}]

Use InstructionSets object inside the Tachyon connector instance.

Retrieving all Instruction Sets
response = connector.InstructionSets.GetAllWithCounts();

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

Lastly, you can retrieve a specific instruction set by its Id or Name.

Direct Consumer API callC# code using Consumer SDK library

Making a GET request to https://my.tachyon.server/Consumer/InstructionSets/Id/1 will yield following response

Return payload
{
    "Id": 1,
    "Name": "Hardware questions",
    "Description": null,
    "Icon": null
}

Use InstructionSets object inside the Tachyon connector instance.

Retrieving specific Instruction Set
response = connector.InstructionSets.Get(id);

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

Adding Instruction Definitions to an Instruction Set

Instruction definitions can be added to Instruction set either via the Instruction Set API or Instruction Definitions API.

First, we'll look on how to do that using Instruction Set API.

Direct Consumer API callC# code using Consumer SDK library

Making a POST request with following payload:

{
  "SetId": 1,
  "InstructionDefinitionIds": [
    1,2,3
  ]
}

will yield following response

Return payload
{
    "Id": 1,
    "Name": "Hardware questions",
    "Description": null,
    "Icon": null
}

Use InstructionSets object inside the Tachyon connector instance.

Adding Instruction Definitions to specific Instruction Set
response = connector.InstructionSets.AddInstructionDefinitions(1, new List<int> {1,2,3});

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

It is worth pointing out that if you do not provice SetId in your payload the call will still succeed but the instructions will become unassigned.

And now using Instruction Definition API

Direct Consumer API callC# code using Consumer SDK library

Making a POST request to https://my.tachyon.server/Consumer/InstructionDefinitions/Id/1/InstructionSet/1 without any payload will yield following response:

Return payload
{
    "Id": 1,
    "Name": "1E-Explorer-Examples-CountEventLogErrorsInLastX",
    "Description": "Returns
 event log entries aggregated on event ID (EventCode) of a specified 
type in the a specified Windows event log in the last few days. 
Specifying a long period may result in a large amount of data from each 
agent.",
    "InstructionSetId": 2,
    "InstructionSetName": "Wszystko",
    "InstructionType": 0,
    "ReadablePayload": "Which event IDs of type %type% have been logged in the Windows %logname% event log in the last %numDays% days?",
    "Parameters": [{
        "Name": "type",
        "Pattern": "%type%",
        "DataType": "string",
        "ControlType": "valuePicker",
        "ControlMetadata": null,
        "Placeholder": "event type",
        "DefaultValue": null,
        "Validation": {
            "Regex": null,
            "MaxLength": null,
            "AllowedValues": ["information",
            "warning",
            "error"],
            "NumValueRestrictions": null
        },
        "Value": null,
        "HintText": null,
        "Source": null
    },
    {
        "Name": "logname",
        "Pattern": "%logname%",
        "DataType": "string",
        "ControlType": "valuePicker",
        "ControlMetadata": null,
        "Placeholder": "log name'",
        "DefaultValue": null,
        "Validation": {
            "Regex": null,
            "MaxLength": null,
            "AllowedValues": ["application",
            "security",
            "setup",
            "system"],
            "NumValueRestrictions": null
        },
        "Value": null,
        "HintText": null,
        "Source": null
    },
    {
        "Name": "numDays",
        "Pattern": "%numDays%",
        "DataType": "int",
        "ControlType": "freeText",
        "ControlMetadata": null,
        "Placeholder": "number of days",
        "DefaultValue": null,
        "Validation": {
            "Regex": null,
            "MaxLength": null,
            "AllowedValues": null,
            "NumValueRestrictions": null
        },
        "Value": null,
        "HintText": null,
        "Source": null
    }],
    "Schema": [{
        "Name": "Category",
        "Type": "int64",
        "Length": 0,
        "RenderAs": null
    },
    {
        "Name": "CategoryString",
        "Type": "String",
        "Length": 256,
        "RenderAs": null
    },
    {
        "Name": "EventCode",
        "Type": "int64",
        "Length": 0,
        "RenderAs": null
    },
    {
        "Name": "EventIdentifier",
        "Type": "int64",
        "Length": 0,
        "RenderAs": null
    },
    {
        "Name": "Message",
        "Type": "String",
        "Length": 4096,
        "RenderAs": null
    },
    {
        "Name": "RecordNumber",
        "Type": "int64",
        "Length": 0,
        "RenderAs": null
    },
    {
        "Name": "SourceName",
        "Type": "String",
        "Length": 256,
        "RenderAs": null
    },
    {
        "Name": "GeneratedTimeStamp",
        "Type": "datetime",
        "Length": 0,
        "RenderAs": null
    },
    {
        "Name": "User",
        "Type": "String",
        "Length": 256,
        "RenderAs": null
    }],
    "Aggregation": {
        "Schema": [{
            "Name": "EventCode",
            "Type": "int64",
            "Length": 0,
            "RenderAs": null
        },
        {
            "Name": "Count",
            "Type": "int32",
            "Length": 0,
            "RenderAs": null
        }],
        "GroupBy": "EventCode",
        "Operations": [{
            "Name": "Count",
            "Type": "count"
        }]
    },
    "InstructionTtlMinutes": 30,
    "ResponseTtlMinutes": 30,
    "MinimumInstructionTtlMinutes": 10,
    "MaximumInstructionTtlMinutes": 10080,
    "MinimumResponseTtlMinutes": 10,
    "MaximumResponseTtlMinutes": 10080,
    "Workflow": null,
    "ResponseTemplateId": 1,
    "OriginalFileName": null,
    "ResponseTemplateConfiguration": {
        "Name": "default",
        "TemplateConfigurations": [{
            "Id": "leftpie",
            "Title": "Number of EventIds across devices",
            "Type": "Pie",
            "X": "EventCode",
            "Y": "Count",
            "PostProcessor": "processingFunction",
            "Size": 1,
            "Row": 1
        }],
        "PostProcessors": [{
            "Name": "processingFunction",
            "Function": "ProcessSingleSeries('EventCode', 'Count', '9', 'Number of events', 'true')"
        }]
    },
    "Version": "3",
    "Author": "1E",
    "IsLicensed": true,
    "UploadedTimestampUtc": "2019-03-19T10:14:32.227Z",
    "NumberOfTimesExecuted": 0,
    "Executable": true
}



Use InstructionDefinitions object inside the Tachyon connector instance.

Addign specific Instruction Definition to an Instruction Set
response = connector.InstructionDefinitions.AddDefinitionToSet(1, 1);

response.ReceivedObject object will contain the same data you can see in the JSON response on the left.

As you can see, the main difference is that InstructionSet API allows you to bulk assign Definitions, while InstructionDefinitions API only allows you to assign one definition to a set at a time.

Removing Instruction Definitions from an Instruction Set

Instruction definitions can be removed from Instruction set either via the Instruction Set API or Instruction Definitions API.

First, we'll look on how to do that using Instruction Set API.

Direct Consumer API callC# code using Consumer SDK library

Make a DELETE request with following payload:

{
  "SetId": 1,
  "InstructionDefinitionIds": [
    1,2,3
  ]
}

Use InstructionSets object inside the Tachyon connector instance.

Removing Instruction Definitions from specific Instruction Set
connector.InstructionSets.RemoveInstructionDefinitions(1, new List<int> { 1, 2, 3 });

And now using Instruction Definition API

Direct Consumer API callC# code using Consumer SDK library
Make a DELETE request to https://my.tachyon.server/Consumer/InstructionDefinitions/Id/1/InstructionSet/1

Use InstructionDefinitions object inside the Tachyon connector instance.

Removing a specific Instruction Definition from specific Instruction Set
connector.InstructionDefinitions.RemoveDefinitionFromSet(1, 1);

Exporting Instruction Definitions from a set

In this example we will look at exporting all instruction definitions that belong to a specific set. This allows you to download entire Instruction Set without knowing explicitly which instruction definitions belong to said set.

Direct Consumer API callC# code using Consumer SDK library
Making a GET request to https://my.tachyon.server/Consumer/InstructionSets/Id/{id}/Export will give you back a binary stream with a zip archive that contains all Instruction Definitions from the requested set

Use InstructionSets object inside the Tachyon connector instance.

Exporting all Instruction Definitions that belong to a specific Instruction Set
response = connector.InstructionSets.Export(1);

response.ReceivedObject will be a MemoryStream that holds a zip file which contains Instruction Definitions