Skip to main content

1E 23.7 (SaaS)

Responses

Entity - Response

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 delegated 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 Responses API, this implies that the user is not allowed to see the responses for 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 an error will be returned if the specified instruction is not accessible to the invoking user. Emphasis is done on "potentially", meaning that the system does not check whether the set of responses actually contains any response coming from a "forbidden" device, since this would be too costly at runtime. Instead, the system checks which management groups are accessible to the user who sent the instruction, and if this list contains any management group not accessible to the user who queries the responses, then the request is rejected (even if no response was actually received from devices in the forbidden management groups or if the Scope of the instruction prevented such devices from responding).

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.

All of these return a similar collection.

Verb

Request

Notes

Permissions required

POST

/Consumer/Responses/{instructionId}

Allows fetching successful responses based on criteria.

Example Request

{  
   "Filter":{  
      "Operator":"and",
      "Operands":[  
         {  
            "Attribute":"Caption",
            "Operator":"==",
            "Value":"PLDS DVD+-RW DS-8A8SH"
         },
         {  
            "Attribute":"Description",
            "Operator":"like",
            "Value":"Drive"
         }
      ]
   },
   "PageSize":20,
   "Start":"0;0"
}
  • Filter - filter expression. If null then no filter is applied. Searchable columns depends of schema. To learn about how to define filter check Using scope and filter expressions page.

  • Pagesize - number of results to fetch.

  • Start - starting index to support pagination. For the first page it has to be unencoded 0;0 and for the subsequent page it has to be the value returned as the encoded Range value passed back by the previous page request. You will get a base64 encoded string containing something like “1;4,2;2” which is a comma separated list of pairs of ShardId;ResponseId.

Example Response

{
  "Range": "MTsy",
  "Responses": [
    {
        "Id": 1,
        "ShardId": 1,
        "TachyonGuid": "00000000-0000-0000-0000-000000000000",
        "Fqdn": "machine01.fqdn.yourdomain",
        "ExecTime": 25000,
        "CreatedTimestampUtc": "2017-09-07T10:06:43.203Z",
        "ResponseTimestampUtc": "2017-09-07T10:06:41Z",
        "Values": {
            "FirstSchemaField": "someValue",
            "SecondSchemaField": "another value",
            ...
        },
        "Blob": null
    },
    {
        ...
    }
]}
  • Viewer

  • Questioner

  • Actioner

  • Approver

Instruction's owner can also view responses.

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

POST

/Consumer/Responses/{instructionId}/ Aggregate

Allows fetching aggregated successful responses. Only valid for instructions with aggregation capability dictated by the presence of aggregation schema.

Payload should be like the one below.

Example Request

{  
   "Filter":{  
      "Operator":"and",
      "Operands":[  
         {  
            "Attribute":"Caption",
            "Operator":"==",
            "Value":"PLDS DVD+-RW DS-8A8SH"
         },
         {  
            "Attribute":"Description",
            "Operator":"like",
            "Value":"Drive"
         }
      ]
   },
   "PageSize":20
}
  • Filter - filter expression. If null then no filter is applied. Searchable columns depends of schema. To learn about how to define filter check Using scope and filter expressions page.

  • Pagesize - number of results to fetch

  • Viewer

  • Questioner

  • Actioner

  • Approver

Instruction's owner can also view responses.

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

POST

/Consumer/Responses/{instructionId}/ UniqueFQDNs

Returns the list of distinct FQDNs that are present in the Responses table for the specified instruction.

Will fail if invoked on an aggregated instruction that was not configured to keep the Raw data, since the aggregated data does not contain FQDNs.

It is invoked with the same parameters as the "Aggregate" API above.

Returns an array of strings containing the FQDNs.

  • Viewer

  • Questioner

  • Actioner

  • Approver

Instruction's owner can also view responses.

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

GET

/Consumer/Responses/Processed/ {instructionId}

This endpoint is only usable for instructions that have Custom visualization(s) defined.

This endpoint returns response data processed according to defined Custom visualizations and ready to be consumed by whatever visualization engine is to be used.

Return data will vary depending on what visualizations the instruction uses.

  • Viewer

  • Questioner

  • Actioner

  • Approver

Instruction's owner can also view responses.

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

GET

/Consumer/Responses/{instructionId:int}/ Shard/{shardId:int}/Row/{rowId:int}/ Column/{columnName}

Returns the value of a single column in a specific response.

Designed to work with CLOB fields but will work with any data type.

  • instructionId - id of the instruction. This is the same value as the one you'd provide to Responses/{instructionId} endpoint

  • shardId - id of the shard the response is stored in. This value is provided inside the Response object returned by API when asking for non-aggregate responses as ShardId property (see example response above).

  • rowId - id of the row. This value is provided inside the Response object returned by API when asking for non-aggregate responses as Id property (see example response above).

  • columnName - name of the column in the schema you want the value of. This has to match a column in the instruction definition's schema.

  • Viewer

  • Questioner

  • Actioner

  • Approver

Instruction's owner can also view responses.

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