Skip to main content

1E 9.x (on-premises)

InstructionDefinitions

Entity - Instruction Definitions - Interrogates the InstructionDefinition table

Verb

Request

Notes

Permissions required

GET - all

/Consumer/InstructionDefinitions?instructionType={type}

or

/Consumer/InstructionDefinitions (to get all the instruction definitions assigned to the user)

Gets a list of instruction definitions of specified type(s).

Instruction types can be

  • Question

  • Action

More than one type can be asked for. For example, to get both Action and Question types

/Consumer/InstructionDefinitions?instructionType=Action&instructionType=Question

If no type is specified, all instruction definitions are returned.

Only instructions that the user can see as per their permissions are returned.

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

GET - all

/Consumer/InstructionDefinitions/Parent/{parentId}

Minimum API version 3.3.

Gets a list of instruction definition that can be issued as a follow-up to specific instruction. This endpoint will take into account permissions of the parent instruction and calling user's permission to filter out instruction definitions that wouldn't be sent to any devices due to restrictions imposed by management groups.

parentId should be a valid instruction id (not an instruction definition id).

Instruction types can be

  • Question

  • Action

More than one type can be asked for. For example, to get both Action and Question types

/Consumer/InstructionDefinitions?instructionType=Action&instructionType=Question

If no type is specified, all instruction definitions are returned.

Only instructions that the user can see as per their permissions are returned.

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

GET - single

/Consumer/InstructionDefinitions/Id/{id}

Gets an instruction definition by ID.

Example Response

{
  "Id": 21,
  "Name": "Disabled services",
  "Description": "Shows count of disabled services",
  "ProductPackId": 2,
  "InstructionType": 0,
  "ReadablePayload": "Show count of disabled services",
  "Parameters": null,
  "Schema": [
    {
      "Name": "Caption",
      "Type": "string",
      "Length": 256
    }
  ],
  "Aggregation": {
    "Schema": [
      {
        "Name": "Caption",
        "Type": "string",
        "Length": 256,
                "RenderAs": "preformatted" },
      {
        "Name": "Count",
        "Type": "int32",
        "Length": 0
      }
    ],
    "GroupBy": "Caption",
    "Operations": [
      {
        "Name": "Count",
        "Type": "count"
      }
    ]
  },
  "Category": "Operating System",
  "InstructionTtlMinutes": 60,
  "ResponseTtlMinutes": 120,
  "MinimumInstructionTtlMinutes": 10,
  "MaximumInstructionTtlMinutes": 1440,
  "MinimumResponseTtlMinutes": 10,
  "MaximumResponseTtlMinutes": 10080,
  "IsLicensed" = true,
  "NumberOfTimesExecuted": 7
}

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

GET-single by name

/Consumer/InstructionDefinitions/Name/{name}

Gets an instruction definition by name.

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

GET- list by search terms

/Consumer/InstructionDefinitions/Search/{searchString}?instructionType={type}

Gets a list of instruction definitions of specified type matching search terms in description and readable payload.

For example:

/Consumer/InstructionDefinitions/Search/windows network?type=Question

It will return instruction definitions of Question type matching search terms "windows" and "network"

More than one type can be mentioned in the query string.

If no type is mentioned, all instruction definitions matching search terms are returned regardless of their types.

API versions 3.1 and later: the searchString must be encoded as Base64. This was needed because otherwise the server threw errors whenever the search string contained some special characters such as a dot.

The API understands both strict Base64 and URL-safe Base64. It is recommended that you use the latter, since otherwise there are some possible search strings that would result in malformed URLs when the Base64-encoded text is appended.

For backwards compatibility, if the version specified in the API call is earlier than 3.1, the API expects the search string to NOT be encoded in Base64.

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

GET- list by search terms

/Consumer/InstructionDefinitions/Parent/{parentId}/Search/{base64SearchString}?instructionType={type}

Minimum API version 3.3

Gets a list of instruction definitions of specified type matching search terms in description and readable payload that can be issued as a follow up to given instruction. This endpoint will take into account permissions of the parent instruction and calling user's permission to filter out instruction definitions that wouldn't be sent to any devices due to restrictions imposed by management groups.

parentId should be a valid instruction id (not an instruction definition id).

More than one type can be mentioned in the query string.

If no type is mentioned, all instruction definitions matching search terms are returned regardless of their types.

The API understands both strict Base64 and URL-safe Base64. It is recommended that you use the latter, since otherwise there are some possible search strings that would result in malformed URLs when the Base64-encoded text is appended.

Questions

  • Questioner

  • Actioner

Actions

  • Actioner

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

POST

/Consumer/InstructionDefinitions/Search

Minimum API version 4.0

This endpoint allows searching for instruction definitions based on criteria along with sorting and pagination.

This endpoint is designed to be used when managing instruction definitions and instruction sets, not when issuing instructions because it will return all instruction definitions in the system, not just the ones calling user has permissions on.

Example request payload

{  
   "filter":{
       "Operator": "and",
       "Operands":[
            {  
                "Attribute":"Name",
                "Operator":"LIKE",
                "Value":"What%"
            },
            {  
                "Attribute":"Licensed",
                "Operator":"==",
                "Value":"true"
            }
        ]
    },
   "start":10,
   "pageSize":100,
   "sort":[
       {
            "Column":"Name",
            "Direction":"ASC"
       }
    ]
}

Required 'Read' permission on 'InstructionSetManagement'

DELETE

/Consumer/InstructionDefinitions/Name/{instructionName}

Minimum API version - 3.1

Removes instruction definition with a given name.

Will fail if there are pending instructions based on that definition

Requires 'Delete' permission on Instruction set management

DELETE

/Consumer/InstructionDefinitions/Id/{instructionId}

Minimum API version - 3.1

Removes instruction definition with a given id.

Will fail if there are pending instructions based on that definition

Requires 'Delete' permission on Instruction set management

DELETE

/Consumer/InstructionDefinitions

Minimum API version - 3.1

Deletes multiple instruction definitions defined by name or Id. You cannot use a mix of names and Id. Has to be one or the other.

Payload JSON

{
        "Ids": [],
        "Names": []
}

Provide a JSON with either 'Ids' or 'Names' array filled in

Requires 'Delete' permission on Instruction set management

GET

/Consumer/InstructionDefinitions/InstructionSet/Name/{setName}

Minimum API version - 3.1

Returns instruction definitions from a specific set by set name

Requires 'Read' permission on instruction set management

GET

/Consumer/InstructionDefinitions/InstructionSet

Minimum API version - 3.1

Returns all instruction definitions that are assigned to an instruction set

Requires 'Read' permission on instruction set management

GET

/Consumer/InstructionDefinitions/All

Minimum API version - 3.1

Returns all instruction definitions. Includes both assigned and unassigned instruction definitions

Requires 'Read' permission on instruction set management

GET

/Consumer/InstructionDefinitions/InstructionSet/Id/{setId?}

Minimum API version - 3.1

Returns instruction definitions from a specific set by set id. If no Id is provided all unassigned instruction definitions are returned.

Requires 'Read' permission on instruction set management

POST

/Consumer/InstructionDefinitions/Id/{defId:int}/InstructionSet/{setId:int}

Minimum API version - 3.1

Adds instruction definition with given Id to an instruction set with a specific Id

Requires 'Add' permission on instruction set management

DELETE

/Consumer/InstructionDefinitions/Id/{defId:int}/InstructionSet/{setId:int}

Minimum API version - 3.1

Removes instruction definition with given Id from an instruction set with a specific Id

Requires 'Delete' permission on instruction set management

GET

/Consumer/InstructionDefinitions/Name/{name}/export

Minimum API version - 3.1

Exports instruction definition with a given name to Xml that can be downloaded from the API as an Xml file (MIME application/xml)

Requires 'Read' permission on instruction set management

GET

/Consumer/InstructionDefinitions/Id/{id:int}/export

Minimum API version - 3.1

Exports instruction definition with a given Id to Xml that can be downloaded from the API as an Xml file (MIME application/xml)

Requires 'Read' permission on instruction set management

POST

/Consumer/InstructionDefinitions/Export

Minimum API version - 3.2

Exports a collection of instruction definitions into a ZIP archive.

Request payload

{
        "Ids": [],
        "Names": []
}

You can provide an array of instruction definition Ids or names, but not both.

All Ids or names must be valid.

Requires 'Read' permission on instruction set management

GET

/Consumer/InstructionDefinitions/ManagementGroup/{id:int?}

From 5.0 onwards:

/Consumer/InstructionDefinitions/ManagementGroup/{id:int?}?includeAllDevices=true/false

Minimum API version - 3.3

Returns Management Groups calling user is allowed to access. 'All Devices' management group will not included in the results even if calling user has permission to it. See below for details.

Optionally, an Instruction Definition Id can be supplied.

If it is supplied, only Management Groups accessible for that Instruction Definition will be returned.

If it is not supplied, all Management Groups will be returned regardless of which Instruction Definition they are accessible for.

From version 5.0 onwards this endpoint supports an optional query string parameter called includeAllDevices.

If this parameter is supplied and its value is 'true', 'All Devices' management groups will be returned in the search results (obviously if calling user can access it). Omitting this parameter or setting any other value will result in this management group being removed from the search results.

New for API version 8.0: When returning the Management Groups, the API also includes those that are inferred from the Management Group inheritance hierarchy, in addition to those directly assigned to the specified instruction definition.

This endpoint does not require specific permissions but will return an empty array if the user has no permissions to access Management Groups.

GET

/Consumer/InstructionDefinitions/ManagementGroup/Search/{base64SearchString}

Minimum API version - 3.3

Returns Management Groups calling user is allowed to access whose Names are at least a partial match for specified search string.

'base64SearchString' must be the base64 encoded search string.

All Management Groups will be returned regardless of which Instruction Definition they are accessible for.

New for API version 8.0: When returning the Management Groups, the API also includes those that are inferred from the Management Group inheritance hierarchy, in addition to those directly assigned to the specified instruction definition.

This endpoint does not require specific permissions but will return an empty array if the user has no permissions to access Management Groups.

GET

/Consumer/InstructionDefinitions/ManagementGroup/{id:int}/Search/{base64SearchString}

Minimum API version - 3.3

Returns Management Groups calling user is allowed to access whose Names are at least a partial match for specified search string.

'base64SearchString' must be the base64 encoded search string.

'id' is the Id of an Instruction Definition in whose context you want to get the Management Groups Only Management Groups accessible for that Instruction Definition will be returned.

New for API version 8.0: When returning the Management Groups, the API also includes those that are inferred from the Management Group inheritance hierarchy, in addition to those directly assigned to the specified instruction definition.

This endpoint does not require specific permissions but will return an empty array if the user has no permissions to access Management Groups.

GET - list by product pack id

/Consumer/InstructionDefinitions/ProductPackId/{productPackId}

REMOVED IN 3.1

Gets all instruction definitions belonging to a product pack by its id.

  • Read - ProductPackManagement

Returns Unauthorized (401) if user does not have the required permission.

GET - list by product pack name

/Consumer/InstructionDefinitions/ProductPackName/{productPackName}

REMOVED IN 3.1

Gets all instruction definitions belonging to a product pack by its name.

  • Read - ProductPackManagement

Returns Unauthorized (401) if user does not have the required permission.

In this section: