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

Page version: 44, last updated:



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

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.

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.

Requires any permission on any of the instruction sets