Instructions
Entity - Instructions (Questions and Actions) - Interrogates the Instruction table
Note for API version 8.0
As of API version 8.0, Tachyon 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.
Verb | Request | Notes | Permissions required |
|---|---|---|---|
GET - single | /Consumer/Instructions/{instructionId} | Gets an individual question or action by an Id. Example Response Expand source {
"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
} |
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. Example Request {
"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"
}
]
}
Allowed filter columns:
Allowed sortable columns
NOTE: Only system consumer can search for other consumers' instructions. Other consumers will only see their instructions. |
It does not return Unauthorized (401) rather filters out instructions based on permissions. |
POST | /Consumer/Instructions | Creates a question or action. Example Request {
"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: Example Response {
"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
For actions
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. Example Request {
"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.
| For questions
For actions
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
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}/targetlist | Gets targets of given instruction | For questions
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: Example Request {
"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 |