Entity - Instructions (Questions and Actions) - Interrogates the Instruction table

Page version: , last updated:



As of API version 8.0Tachyon implements changes in the accessibility of instructions and their responses with the goal of enabling delegation of administration. The user is supposed to only manage a subset of endpoints, which are specified by means of Management Groups. The delegated administrator should only be able to see information related to his or her Management Groups, and not anything else in the organization. From the point of view of the Instructions API, this implies that the user is not allowed to see any instructions whose set of results might potentially contain responses from endpoints that should be invisible to the user. This is done transparently by the APIs unless otherwise noted, i.e., the API is called in the normal way as in previous versions, but the returned results hide any instructions not accessible to the invoking user.

To this end, the system considers "visible to the user" the instructions that were submitted by any other user whose Management Group assignments are a subset of the Management Group assignments of the user that invokes the API. For this purpose, the system uses the current Management Groups assigned to each user, not the Management Groups that the users could access back at the time when the instruction was submitted.


VerbRequestNotesPermissions required
GET - single

/Consumer/Instructions/{instructionId}



Gets an individual question or action by an Id.

{
    "Id": 1010,
    "Sequence": 19,
    "Name": "1E-Explorer-TachyonCore-BiosDetails",
    "Description": "Returns details of BIOS firmware.",
    "InstructionType": 0,
    "ReadablePayload": "What BIOS firmware is installed?",
    "Cmd": "SendAll",
    "Schema": [
        {
            "Name": "BIOSVersion",
            "Type": "string",
            "Length": 512,
            "RenderAs": null
        },
        {
            "Name": "Caption",
            "Type": "string",
            "Length": 512,
            "RenderAs": null
        },
        {
            "Name": "Manufacturer",
            "Type": "string",
            "Length": 512,
            "RenderAs": null
        },
        {
            "Name": "PrimaryBIOS",
            "Type": "bool",
            "Length": 0,
            "RenderAs": null
        },
        {
            "Name": "ReleaseDate",
            "Type": "datetime",
            "Length": 0,
            "RenderAs": null
        },
        {
            "Name": "SerialNumber",
            "Type": "string",
            "Length": 512,
            "RenderAs": null
        }
    ],
    "Aggregation": {
        "Schema": [
            {
                "Name": "Manufacturer",
                "Type": "string",
                "Length": 512,
                "RenderAs": null
            },
            {
                "Name": "BIOSVersion",
                "Type": "string",
                "Length": 512,
                "RenderAs": null
            },
            {
                "Name": "Count",
                "Type": "int64",
                "Length": 0,
                "RenderAs": null
            }
        ],
        "GroupBy": "Manufacturer,BIOSVersion",
        "Operations": [
            {
                "Name": "Count",
                "Type": "count"
            }
        ]
    },
    "KeepRaw": true,
    "Scope": {
        "Attribute": "OsType",
        "Operator": "==",
        "Value": "Windows",
        "DataType": "String"
    },
    "ReadableScope": {
        "Attribute": "OsType",
        "Operator": "==",
        "Value": "Windows",
        "DataType": "String"
    },
    "InstructionTtlMinutes": 60,
    "ResponseTtlMinutes": 60,
    "CreatedTimestampUtc": "2018-07-13T08:27:05.7Z",
    "SentTimestampUtc": "2018-07-13T08:27:37.323Z",
    "Status": 6,
    "WorkflowState": 5,
    "StatusTimestampUtc": "2018-07-13T09:28:04.61Z",
    "Export": false,
    "ExportLocation": "",
    "ParentInstructionId": null,
    "InstructionDefinitionId": 85,
    "CreatedBy": "SomeDomain\\Some.User",
    "ResultsFilter": null,
    "PreviousResultsFilter": null,
    "ConsumerId": 1,
    "ConsumerName": "Explorer",
    "ConsumerCustomData": null,
    "ParameterJson": null,
    "OffloadResponses": false,
    "RequestedFor": null,
    "ResponseTemplateId": 1,
    "ResponseTemplateConfiguration": {
        "Name": "default",
        "TemplateConfigurations": [
            {
                "Id": "mainchart",
                "Title": "Most common BIOS manufacturers and versions",
                "Type": "Bar",
                "X": "BIOSVersion",
                "Y": "Count",
                "Z": "Manufacturer",
                "PostProcessor": "processingFunction",
                "Size": 1,
                "Row": 1
            }
        ],
        "PostProcessors": [
            {
                "Name": "processingFunction",
                "Function": "ProcessMultiSeries('BIOSVersion', 'Count', 'Manufacturer', '5', '5', 'false')"
            }
        ]
    },
    "Workflow": "{\"StateMachine\":\"State\"}",
    "Comments": null,
    "ScheduledInstructionId": null,
    "ApprovalOffloaded": false,
    "ActionedBy": null,
    "ActionReason": null
}


  • Viewer
  • Questioner
  • Actioner
  • Approver

Returns Unauthorized (401) if user does not have the required permissions at global level or on the parent InstructionDefinition's product pack.

POST/Consumer/Instructions/search

To search instructions based on criteria along with sorting and pagination.

{
    "filter":{
        "Operator": "AND",
        "Operands": [ 
            { 
                "Attribute": "Status",
                "Operator": "==",
                "Value": "5"
            },
            { 
                "Attribute": "CreatedTime",
                "Operator": ">=",
                "Value": "2016-04-21T06:30:00Z"
            },
            { 
                "Attribute": "CreatedTime",
                "Operator": "<=",
                "Value": "2016-04-30T19:55:00"
            }
        ]
    },
    "start": 1,
    "pageSize": 10,
    "sort": [
        {
            "Column": "payload",
            "Direction": "ASC"
        },
        {
            "Column": "CreatedTime",
            "Direction": "DESC"
        }
    ]
}
  • filter - filter expression.To learn about how to define filter check Using scope and filter expressions page.
  • start - starting index to support pagination. Begins from 1.
  • pagesize - number of results to fetch
  • sort - sort expression. To learn about how to define sort criteria check Sort Definition page.

Allowed filter columns:

  • ReadablePayload
  • Description
  • CreatedTime
  • Status
  • DefinitionName (v1.6)
  • DefinitionId (v1.6)
  • ConsumerId (2.0)
  • ConsumerCustomData (v1.6)

Allowed sortable columns

  • ReadablePayload
  • Description
  • CreatedTime
  • Status


NOTE: Only system consumer can search for other consumers' instructions. Other consumers will only see their instructions.

  • Viewer
  • Questioner
  • Actioner
  • Approver

It does not return Unauthorized (401) rather filters out instructions based on permissions.

POST

/Consumer/Instructions



Creates a question or action.

{
	"DefinitionId": 9,
    "DefinitionName": null,
    "Scope": {
		"Attribute": "OsType",
		"Operator" : "=",
		"Value": "Windows"
	},
    "Parameters": null,
	"InstructionTtlMinutes": 60,
	"ResponseTtlMinutes": 120,
    "ParentInstructionId": null,
    "KeepRaw": false,
    "Export": false,
    "ExportLocation": null,
    "ResultsFilter": {
		"Attribute": "NumberOfCores",
		"Operator": ">",
		"Value": "2"
	},
	"PreviousResultsFilter": null,
    "ConsumerCustomData": "MyCustomData",
    "OffloadResponses": false
}

will return:

{
	"Id": 199,
	"Name": "System Processor Details",
	"Description": "Represents a device capable of interpreting a 
sequence of machine instructions on a computer system running Windows",
	"InstructionType": 0,
	"ReadablePayload": "Get Processor Details",
	"Cmd": "SendAll",
	"Schema": [
	    {
    		"Name": "Caption",
    		"Type": "string",
    		"Length": 256
    	},
    	{
    		"Name": "Description",
    		"Type": "string",
    		"Length": 256
    	},
    	{
    		"Name": "Manufacturer",
    		"Type": "string",
    		"Length": 256
    	},
    	{
    		"Name": "NumberOfCores",
    		"Type": "int32",
    		"Length": 0
    	}
    ],
	"Aggregation": null,
	"KeepRaw": false,
	"Scope": null,
	"QuestionTtlMinutes": 60,
	"AnswerTtlMinutes": 120,
	"CreatedTimestampUtc": "2015-10-01T08:36:38.663",
	"Status": 0,
	"AnswerCount": 0,
	"SentCount": 0,
	"ParentQuestionId": null,
	"QuestionDefinitionId": 9,
	"CreatedBy": "",
	"ResultsFilter": {
		"Attribute": "NumberOfCores",
		"Operator": ">",
		"Value": "2"
	},
	"PreviousResultsFilter": null,
    "ConsumerId": 0,
    "ConsumerCustomData": "MyCustomData",
    "OffloadResponses": false,
    "ParameterJson" : null
 }


For questions

  • Questioner
  • Actioner


For actions

  • Actioner

Returns Unauthorized (401) if user does not have the required permissions at global level or on the parent InstructionDefinition's product pack.



POST

/Consumer/Instructions/Targeted


Creates a question or action, supplying a targeted list of devices by Fqdn

As above with the added "Devices" Json property e.g.

{
	"DefinitionId": 9,
    "DefinitionName": null,
    "Parameters": null,
    "InstructionTtlMinutes": 60,
    "ResponseTtlMinutes": 120,
    "ParentInstructionId": null,
    "KeepRaw": false,
    "Export": false,
    "ExportLocation": null,
    "ResultsFilter": {
		"Attribute": "NumberOfCores",
		"Operator": ">",
		"Value": "2"
	},
	"PreviousResultsFilter": null,
    "ConsumerCustomData": "MyCustomData",
    "OffloadResponses": false,
	"Devices":["pedvwks127.pe.local","pedvwks126.pe.local","pedvwks240.pe.local"]
}


 As above

Note: Fqdn list is limited by MaxRequestLength which defaults to 4MB

POST/Consumer/Instructions/{instructionId}/cancel/{keepData}

Cancels an instruction.

  • id - question to stop
  • keepData - flag to indicate if result should be deleted


For questions

  • Questioner
  • Actioner


For actions

  • Actioner

Returns Unauthorized (401) if user does not have the required permissions at global level or on the parent InstructionDefinition's product pack. Instruction's owner can also cancel.

POST/Consumer/Instructions/{instructionId}/rerun

Reruns a question.

Rerunning an action is not allowed, as it can be risky.

For questions

  • Questioner
  • Actioner

Returns Unauthorized (401) if user does not have the required permissions at global level or on the parent InstructionDefinition's product pack.

GET/Consumer/Instructions/{instructionId}/targetlistGets targets of given instruction

For questions

  • Questioner
  • Actioner

Returns Unauthorized (401) if user does not have the required permissions at global level or on the parent InstructionDefinition's product pack.

GET/Consumer/Instructions/InFlight/InstructionSet/{instructionSetId}

Gets "In-Flight" instructions for a given Instruction Set.


The result has this shape:


{
    "TotalCount": 2,
    "Items": [
        {
            "Id": 2401,
            "Name": "TachyonCore-BiosDetails",
            …..
        }
    ]
}


The "TotalCount" property contains the total available In-flight instructions.

The "Items" property contains the list of In-flight instructions which the user can see. (and therefore its length could be less than TotalCount).


Filters out the results based on permissions.

GET/Consumer/Instructions/{instructionId}/approxtarget

Minimum API version - 3.3

Gets approximate target for specific instruction.

Approximate target will be calculated using the scope defined in the instruction.

Approximate target will be calculated for the user who created the instruction, using that user's current permissions.

New for API version 8.0: The calculation for the approximate target only counts the Devices that the current user is allowed to see in accordance to the Management Groups that are assigned to the user.

Requires any permission on any of the instruction sets