18. The Response Envelope

The response envelope encapsulates all of the data and metadata around a command request, execution, and response. It’s passed into the templating engine, where it can be accessed directly by templates.

The response envelope consists of four major components:

  • .Request – This describes the original request used to execute the command, and contains all of the original command values, and some data about the user and adapter.

  • .Response – Contains the textual response emitted by the command.

  • .Data – This object contains metadata about the command execution, including its duration and exit status.

  • .Payload – If the command output is valid JSON, it will be unmarshalled and placed here to be accessed by templates. Non-JSON output will also be placed here, as a plain string.

These components (and any sub-components, where relevant) are detailed below.

18.1. .Request

The .Request object represents the original command request used to execute the command. It contains the original command values as well as the user and adapter data.






The name of the adapter this request originated from



The provider ID of the channel that the request originated in



Tokenized command parameters



A unique requestID



The time this request was triggered



The provider ID of user making this request



The email address associated with the user making the request



The Gort username of the user making the request

18.2. .Request.Bundle

The .Request.Bundle object represents the bundle that owns the command.

18.3. .Request.Command

The .Request.Command object represents the command definition.

18.4. .Response

The .Response object contains the response text emitted by an executed command.






The command output (from both stdout and stderr) as a string slice, delimitted along newlines.



The command output as a single block of text, with lines joined with newlines.



true if the command output is valid JSON. If so, then it also be unmarshalled as .Payload; else .Payload will be a string (equal to .Response.Out).



A title. Usually only set by the relay for certain internally-detected errors. Generally a short description of the result.

18.5. .Data

The .Data object contains data about the command execution, including its duration and exit status. If the relay sets an an explicit internal error, it will be here as well.






Duration is how long the command required to execute.



ExitCode is the exit code reported by the command.



Error is set by the relay under certain internal error conditions.

18.6. .Payload

.Payload includes the command output. It’s a very special animal, because its contents can very according to the contents and format of the response returned by the command.

Specifically, if the command output is formatted as structured JSON, the output will be unmarshalled and made accessible via .Payload as if were any other object. Additionally, the value of .Response.Structured will be true.

For example, if the contents of the command response are as follows:

   "User":"Michael Scott",
   "Company":"Dunder Mifflin",
         "Description":"Bond paper is stronger and more durable than the average sheet of paper.",
      }, {
         "Name":"Gloss coated",
         "Description":"Gloss paper is typically used for flyers and brochures as it has a high shine.",

So a template containing the instructions {{.Payload.User}}, {{.Payload.Company}} would resolve as Michael Scott, Dunder Mifflin.

If the response isn’t structured, .Response.Structured will be false, and .Payload will be a standard string equal to .Response.Out.