Analyse Outbox Results
Decoding Base64
In case, a JSON Object was received, the String inside the Command is a Base64 encoded protobuf object. The app instance has to decode the message into a protobuf object then.
The Base64 string should be convertible to a byte stream that includes a ResponseEnvelope and a ResponsePayLoadWrapper.
Delimiting Envelope and Payload
Envelope and payload of each message are packaged into one delimited message. Separating those parts requires the delimiting functionality of protobuf. To know the format for the payload, the envelope has to be decoded first
Envelope
The envelope is a protobuf object that can be found in message agrirouter.response.ResponseEnvelope
Parameters are:
| # | Name | Type | Description |
|---|---|---|---|
1 |
response_code |
int64 |
A HTTP-like response code indicating the result |
2 |
type |
ResponseBodyType |
An indicator of the correct decoding protobuf description |
3 |
application_message_id |
String |
the corresponding message that this answer is assigned to. |
4 |
message_id |
String |
The agrirouter internal message ID used to be written to the agrirouter log and for confirmation. |
5 |
timestamp |
TimeStamp |
The timestamp of the Result creation |
response_code
The response code indicates success or failure of a request.
| HTTP Response Code | Description |
|---|---|
200 |
request processed/received successfully. Also used with PUSH-Notifications |
201 |
request processed/received and data created (this would be valid in cases for response to subscriptions, capabilities, teamset context messages, etc) |
400 |
validation of request failed, messages in the body specifies the type of request failure |
413 |
request too large |
503 |
request cannot be processed at the moment, probably due to temporary overload |
ResponseType
The type is required to determine the correct schema for the body.
The following List shows the corresponding Protobuf schemata for each ResponseType:
| ResponseBodyType | Schema (.proto) | Comment |
|---|---|---|
MESSAGES |
obsolete |
This type is not used |
ACK |
There is no Schema for this, the payload will just have a size of 0 bytes |
An acknowledgment of a message |
ACK_WITH_MESSAGES |
agrirouter.commons.Messages |
An acknowledgment with messages; e.g. warnings. |
ACK_WITH_FAILURE |
agrirouter.commons.Messages |
Represents a failure response in correlation to a message sent to the agrirouter |
ACK_FOR_FEED_HEADER_LIST |
agrirouter.feed.response.HeaderQueryResponse |
Used for acknowledgments for feed envelope requests |
ACK_FOR_FEED_MESSAGE |
agrirouter.feed.response.MessageQueryResponse |
Used for acknowledgments for feed payload requests. |
ACK_FOR_FEED_FAILED_MESSAGE |
agrirouter.feed.response.FailedMessageQueryResponse |
Response for failed requests to feed queries |
ENDPOINTS_LISTING |
agrirouter.response.payload.account.ListEndpointsResponse |
Used for a response which contains the endpoint listing |
CLOUD_REGISTRATIONS |
agrirouter.cloud.registration.OnboardingResponse |
The result of a Virtual CU registration |
PUSH_NOTIFICATION |
agrirouter.feed.push.notification |
An actively pushed message. See push notifications. |
Analysing the results is described in the specific chapters of process description for the relevant commands.
VAL_00004 vs. VAL_00005
While VAL_00004 indicates that no one was able to receive your message at all, VAL_00005 only reports that one of the recipients you intended to send a message to was unable to receive your message. There is no specific error message if you just publish a message and no one has subscribed to it.
application_message_id
Indicates to which request this response is to be mapped (app message id is provided by sending application)
message_id
The message_id is a unique ID of this message on the agrirouter. Use this id for the confirmation or deletion request.
|
Deletion and/or confirmation is only required for messages (no matter if requested from feed or actively pushed), not for commands |
timestamp
Time point, when this message was created by the sender.
Payload
There are several possible payload protobuf formats. Specific messages will be described in the following chapter, in this chapter we will only describe general payload answers.
Messages
The agrirouter.commons.messages element includes a message as result of a command for ACK_WITH_MESSAGES or ACK_WITH_FAILURE results.
syntax = "proto3";
package agrirouter.commons;
message Message {
string message = 1; // Message text in English Only
string message_code = 2; // Globally defined message code
map<string, string> args = 3; // List of argument names and values which would be inserted into the message text
}
message Messages {
repeated Message messages = 1; // Collection of the Message object listed above used in scenario's when there are multiple messages in a response
}It includes an array of Message:
| # | Name | Type | Description |
|---|---|---|---|
1 |
message |
string |
A human readable description of the message including wildcard fields |
2 |
message_code |
string |
A standardized code to analyse by a program |
3 |
args |
map<string,string> |
A map of field+value pairs to add specific information to a standardized message |
To display the message, replace all fields in the message with the corresponding values from the map.
The possible codes can be found in the error code list, specific values will be described in more detail within the corresponding Commands chapter.