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

agrirouter.feed.response. MessageQueryResponse

A list of messages as result of a request for messages

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.

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.