Version: 36
restore

Contents

Page version: 36, last updated: .

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

VerbRequestNotesPermissions Required
GET - single

/Consumer/Instructions /{instructionId}

 

 

Gets an individual question or action by an Id.

Example Response
{
    "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.

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"
        }
    ]
}
  • 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 Defintion 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, action or event.

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

  • 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.

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.

  • 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:

 

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.