19. 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.
19.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.
Syntax |
Type |
Description |
---|---|---|
|
string |
The name of the adapter this request originated from |
|
string |
The provider ID of the channel that the request originated in |
|
[]string |
Tokenized command parameters |
|
int64 |
A unique requestID |
|
time.Time |
The time this request was triggered |
|
string |
The provider ID of user making this request |
|
string |
The email address associated with the user making the request |
|
string |
The Gort username of the user making the request |
19.2. .Request.Bundle
The .Request.Bundle
object represents the bundle that owns the
command.
19.3. .Request.Command
The .Request.Command
object represents the command definition.
19.4. .Response
The .Response
object contains the response text emitted by an
executed command.
Syntax |
Type |
Description |
---|---|---|
|
[]string |
The command output (from both stdout and stderr) as a string slice, delimitted along newlines. |
|
string |
The command output as a single block of text, with lines joined with newlines. |
|
bool |
|
|
string |
A title. Usually only set by the relay for certain internally-detected errors. Generally a short description of the result. |
19.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.
Syntax |
Type |
Description |
---|---|---|
|
time.Duration |
Duration is how long the command required to execute. |
|
int16 |
ExitCode is the exit code reported by the command. |
|
error |
Error is set by the relay under certain internal error conditions. |
19.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",
"Results":[
{
"Name":"Bond",
"Reviews":523,
"Description":"Bond paper is stronger and more durable than the average sheet of paper.",
"Image":"https://dunder-mifflin/bond.jpg"
}, {
"Name":"Gloss coated",
"Reviews":1234,
"Description":"Gloss paper is typically used for flyers and brochures as it has a high shine.",
"Image":"https://dunder-mifflin/gloss-coated.jpg"
}
]
}
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
.