Commands to control the feed
These commands are used to control the delivery of messages from the feed to the app instance through the outbox. See also architecture of an Endpoint
Paging
Due to the huge number of messages that could be delivered with a single call for messages, it would be a bad idea to deliver all those message headers in one big package. Therefore, a paging mechanism was introduced to split the whole list of messages or message headers into several pages, each including a maximum number of messages or a maximum overall size of the result. The maximum number of messages per page is 25, the total size of a messages in a page is 1 MB.
If not all messages have been delivered from feed to the outbox with the first call, the endpoint has to poll for messages again after either confirming the ones that were on the first page or adjusting the filter criteria.
Message Query and Filtering
Reading the messages, the message headers from the feed or deleting messages from the feed can be done using a message filter including the following parameters:
| # | Name | Type | Description |
|---|---|---|---|
1 |
message_ids |
String (repeated) |
A list of agrirouter message IDs |
2 |
senders |
String (repeated) |
A list of message senders |
3 |
validity_period |
Validity Period |
A time span that the messages were sent in |
The validity Period has following parameters.
| # | Name | Type | Description |
|---|---|---|---|
1 |
sentFrom |
google.protobuf.Timestamp |
Begin of the time span |
2 |
sentTo |
google.protobuf.Timestamp |
End of the time span |
A message with id, source and timestamp fits the filter if
-
(id is part of messageIDs or messageIDs is empty) AND
-
(source is part of senders or senders is empty) AND
-
(timestamp is within validity_period or validity_period is empty)
Metadata
With release 1.2, messages can be extended by metadata to provide further information about the message itself.
The metadata field includes the following fields:
| # | Name | Type | Description |
|---|---|---|---|
1 |
file_name |
string |
The corresponding name of the file that is sent; relevant e.g. if multiple TaskDataSets are sent. |
Metadata are part of the MessageQueryResponse and the MessageHeaderQueryResponse; see below.
The command can include one or more filter criteria. If one filter is not provided, this means that this filter is ignored.
Call for Message Header List
Definition
To receive the Message ids of all available messages or a specific filtered list of available message IDs, an App Instance can call for the message headers available in the feed to be delivered to the Outbox
Command
The command includes filters for Message IDs, senders and a validity period.
Command |
dke:feed_header_query |
Protobuf Schema |
agrirouter.feed.request.MessageQuery |
TypeURL |
types.agrirouter.com/agrirouter.feed.request.MessageQuery |
For parameter description see Message Query and Filtering.
| # | Name | Type | Description |
|---|---|---|---|
1 |
message_id |
string |
The message ID to request, delete or confirm the message |
2 |
technical_message_type |
string |
The technical message type of the message |
3 |
team_set_context_id |
string |
The teamset ID to assign the message to the correct context. |
4 |
chunk_contextID |
string |
The chunk context corresponding to the chunk list |
5 |
payload_size |
int64 |
The size of the payload |
6 |
sent_timestamp |
google.protobuf.Timestamp |
The timestamp that was provided by the sender. It should be the time when the message orignally was sent |
7 |
sequence_number |
int64 |
The sequence number to determine the correct order for messages that were recorded at the same time point |
Result
The response includes only the message headers without the payload.
|
The result is sorted ascending by the senderID. Within the sender-receiver package, the messages are sorted first by the timestamp and then by the sequence number. |
ResultCode |
ACK_FOR_FEED_HEADER_LIST |
Protobuf Schema |
agrirouter.feed.response.HeaderQueryResponse |
TypeURL |
types.agrirouter.com/agrirouter.feed.response.HeaderQueryResponse |
In general, the result has the following layers
⇒ Technical information ("How many responses etc.")
=⇒ Sender-Receiver-Tuple ("Who sent to whom")
==⇒ Message Header ("Type, ID, Date, etc…")
The topmost protobuf is a list of technical information on the result itself.
| # | Name | Type | Description |
|---|---|---|---|
1 |
queryMetrics |
QueryMetrics |
A summarize of the response |
2 |
page |
Page |
The current page of the message |
3 |
chunk_contexts |
ChunkComponent (repeated) |
A list of all chunk contexts |
4 |
feed |
Feed (repeated) |
A list of messages from and for a specific endpoint |
5 |
String |
Pending Message Ids (repeated) |
A list of all pending messages ======= |
4 |
feed |
Feed (repeated) |
A message from the feed |
5 |
String |
Pending Message Ids (repeated) |
A list of all pending messages (deprecated) |
|
With release of the active push functionality, the pending messages list is deprecated and will no longer be filled. Messages can now be confirmed as bundles over a longer period of time. |
The Query metrics informs about several result parameters:
| # | Name | Type | Description |
|---|---|---|---|
1 |
total_messages_in_query |
int32 |
The total number of all messages headers in the response |
2 |
max_count_restriction |
int32 |
The maximum count of messages per page |
The Paging information is included in the page parameter:
| # | Name | Type | Description |
|---|---|---|---|
1 |
number |
int32 |
The index of the current page |
2 |
total |
int32 |
The total number of pages |
The chunk context is an Array of available chunk contexts within this messages. If there are multiple of them, this means that there are multiple chunked messages to be realigned.
The chunk context is described in chunking big messages .
The feed includes an array of message headers that describe sender and receiver by their IDs.
| # | Name | Type | Description |
|---|---|---|---|
1 |
sender |
string |
Endpoint ID of the sender |
2 |
receiver |
string |
Endpoint ID of the receiver |
3 |
header |
Header (repeated) |
An array of message headers |
It includes the list of headers which again includes the following information:
| # | Name | Type | Description |
|---|---|---|---|
1 |
message_id |
string |
The message ID to request, delete or confirm the message |
2 |
technical_message_type |
string |
The technical message type of the message |
3 |
team_set_context_id |
string |
The teamset ID to assign the message to the correct context. |
4 |
chunk_contextID |
string |
The chunk context corresponding to the chunk list |
5 |
payload_size |
int64 |
The size of the payload |
6 |
sent_timestamp |
timestamp |
The timestamp that was provided by the sender. It should be the time when the message orignally was sent |
7 |
sequence_number |
int64 |
The sequence number to determine the correct order for messages that were recorded at the same time point |
|
As a telemetry platform can receive messages for multiple Virtual CUs, the receiver field is used to determine the correct virtual CU. |
| # | Name | Type | Description |
|---|---|---|---|
1 |
message_id |
string |
The message ID of the message |
2 |
technical_message_type |
string |
The technical message type of the message |
3 |
team_set_context_id |
string |
The teamset ID assigned with the message. |
4 |
chunk_contextID |
string |
The chunk context corresponding to the chunk list |
5 |
payload_size |
int64 |
The size of the payload |
6 |
sent_timestamp |
google.protobuf.Timestamp |
The timestamp that was provided by the sender. |
7 |
sequence_number |
int64 |
The sequence number to determine the correct order for messages that were recorded at the same time point |
8 |
current_chunk |
int64 |
The chunk counter of the current chunk |
9 |
created_at |
google.protobuf.Timestamp |
The time at which the message was inserted into the endpoints feed within the agrirouter |
10 |
metadata |
agrirouter.commons.Metadata |
Additional metadata information helping to differentiate between messages of the same type. |
Call for messages
Definition
Every app Instance can request a single or a list of messages to be forwarded from the feed to the outbox by its message ids
Command
Command |
dke:feed_message_query |
Protobuf Schema |
agrirouter.feed.request.MessageQuery |
TypeURL |
types.agrirouter.com/agrirouter.feed.request.MessageQuery |
For parameter description see Message Query and Filtering.
Result
The result includes all information like the HeaderQueryResponse plus the actual payload of the message.
ResultCode |
ACK_FOR_FEED_MESSAGE |
Protobuf Schema |
agrirouter.feed.response.MessageQueryResponse |
TypeURL |
types.agrirouter.com/agrirouter.feed.response.MessageQueryResponse |
In general, the result has the following layers
⇒ Technical information ("How many responses etc.")
=⇒ Message Header + Payload ("Type, ID, Data, etc…")
The topmost protobuf is a list of technical information on the result itself.
| # | Name | Type | Description |
|---|---|---|---|
1 |
queryMetrics |
QueryMetrics |
A summarize of the response |
2 |
page |
Page |
The current page of the message |
3 |
messages |
FeedMessage (repeated) |
A message from the feed |
The Query metrics informs about several result parameters:
| # | Name | Type | Description |
|---|---|---|---|
1 |
total_messages_in_query |
int32 |
The total number of all messages headers in the response |
2 |
max_count_restriction |
int32 |
The maximum number of messages per page |
The Paging information is included in the page parameter:
| # | Name | Type | Description |
|---|---|---|---|
1 |
number |
int32 |
The index of the current page |
2 |
total |
int32 |
The total number of pages |
The messages include an array of messages
| # | Name | Type | Description |
|---|---|---|---|
1 |
header |
Header |
The header of the message |
2 |
content |
any |
The payload in the corresponding protobuf format |
The header includes the whole envelope of a message
| # | Name | Type | Description |
|---|---|---|---|
1 |
receiver_id |
string |
The receiver; might be a secondary endpoint like a virtual CU behind a telemetry platform. |
2 |
technical_message_type |
string |
The technical message type of the message. |
3 |
team_set_context_id |
string |
The teamset ID to assign the message to the correct context. |
4 |
chunk_context |
agrirouter.commons.ChunkComponent |
The chunk component. |
5 |
payload_size |
int64 |
The size of the payload. |
6 |
sent_timestamp |
google.protobuf.Timestamp |
The timestamp that was provided by the sender. It should be the time when the message was originally sent. |
7 |
sequence_number |
int64 |
The sequence number to determine the correct order for messages that were recorded at the same time point. |
8 |
sender_id |
string |
The endpoint ID of the sender. |
9 |
created_at |
google.protobuf.Timestamp |
The timestamp, when this message was added to the receiving endpoints feed. |
10 |
message_id |
String |
Internal agrirouter message ID representing this message and its payload. |
11 |
metadata |
agrirouter.commons.Metadata |
Additional metadata information helping to differentiate between messages of the same type. |
|
The result is sorted ascending by the senderID. |
Within the sender-reciever package, the messages are sorted primary by the timestamp and secondary by the sequence number.
Errors
If the message was incorrect, an ACK_WITH_FAILURE will be reported. For specific error messages, see the error list.
Chunked messages
Messages sent to the agrirouter can be split into multiple chunks if the message format is not EFDI.
Only those message that were not created by the agrirouter and that are not of type EFDI or GPS:INFO can be chunked.
Recognizing chunked messages in the feed
To recognize chunked messages, request the message header query and see if you find different chunk contexts.
Call for message deletion
Definition
An app instance can delete message from its feed if it does not want to consume them. Therefore, it sends a list of message IDs or a validity period or a list of senders to the inbox.
Command
Command |
dke:feed_delete |
Protobuf Schema |
agrirouter.feed.request.MessageQuery |
TypeURL |
types.agrirouter.com/agrirouter.feed.request.MessageQuery |
See Message Query and Filtering for parameters and Filtering.
Result
ResultCode |
ACK_WITH_MESSAGE |
Protobuf Schema |
message |
TypeURL |
types.agrirouter.com/agrirouter.commons.Messages |
In case of success, you receive VAL_000209 and a list of MessageIDs that could be deleted.
Errors
If the message was incorrect, an ACK_WITH_FAILURE will be reported. For specific error messages, see the error list.
Call for message list confirmation
To make sure that no message gets lost due to e.g. a loss of internet connection while delivering a message, the app instance has to confirm the receival of every message.
Definition
Once a message was downloaded from the outbox, the Client has to confirm that it properly received this message/those messages.
|
When a message is confirmed, it will be deleted from the feed. As long as it is not confirmed, it will be delivered in a FeedRequest or FeedHeaderRequest again if there is no specific filter to avoid this. Messages shall always be confirmed to avoid Emails to customers about old messages in the endpoints feed. The old behavior, where a message was delivered over and over again with a FeedMessageRequest, even though it was not specifically requested, was removed with the introduction of push notifications. |
Command
Command |
dke:feed_confirm |
Protobuf Schema |
agrirouter.feed.request.MessageConfirm |
TypeURL |
types.agrirouter.com/agrirouter.feed.request.MessageConfirm |
MessageConfirm is simply an array of message IDs.