IDs, IDs, IDs and which is which
Overview
The agrirouter API uses several IDs, which can be a little confusing. But don’t worry, here is a short description, which ID is used for what:
Name | Description |
---|---|
accountId |
A UUID describing the account of an end user. In one account, there can be multiple endpoints. One account however has one set of login credentials for the agrirouter |
applicationId |
A UUID identifying an application regardless of the software version |
capabilityAlternateId |
This is an Id that is delivered with the onboarding Request and has to be delivered with any message |
certificationVersionId |
A UUID representing a Certification for one app. An app has to be certified every time, a new version with changed capabilities against agrirouter are implemented. |
deviceAlternateId |
The Id of the endpoint of an application instance. It’s used to address the outbox and inbox. |
endpointId |
The endpointId is the unique address of an Application Instance on the agrirouter. It’s used to directly address an endpoint from a different endpoint and to mark the source of a message. |
gatewayId |
This is a simple enumeration to determine the protocol type of the communication. It’s either 2=MQTT or 3=REST |
sensorAlternateId |
The endpointId equals the sensorAlternateId |
Ids in different Environments
It is important to keep in mind that all Ids including applicationId and certificationVersionId will differ between QA and Productive environments.
Practical differentiation between SensorAlternateId and DeviceAlternateId
sensorAlternateID and deviceAlternateId seem to be pretty equal, but the context differs. Here are some practical examples
You will find "=" signs in the following sub chapters. In this context, = does NOT mean that the values of the ids are equal, but that they represent the same device |
A Farming Software sends a TaskData
For apps, the solution is pretty easy:
sensorAlternateId = deviceAlternateId = The endpoint representing the users account within the app.
A CU sends a TaskData
Assume, a CU wants to send a taskdata.zip. Even though, it could include machine data - perhaps of multiple machines, the source of this taskdata is the CU. Therefore:
sensorAlternateId = deviceAlternateId = The CU
A telemetry Platform sends a TaskData from a virtual CU
The virtual CU as well as the telemetry platform are endpoints in the agrirouter. The platform wants to mark the virtual CU as source of the taskdataset.
deviceAlternateId: The telemetry platform is source of the message
sensorAlternateId: The virtual CU is source of the content of the message
sensorAlternateId != deviceAlternateId
accountId
Description
The Unique Identifier for an endusers or developers account. Relevant for billing.
The account ID is used for invoicing. Therefore it should be saved with the onboarding reponse together, so the check of the invoice is possible. If the account ID is missing comparing the items on the invoice is not possible, since the invoicing is based on the account ID. |
A UUID describing the account of an end user. In one account, there can be multiple endpoints. One account however has one set of login credentials for the agrirouter UI.
applicationId
capabilityAlternateId
certificationVersionId
Description
A UUID representing a certification for one app version. An app has to be certified every time, a new version with changed capabilities against agrirouter are implemented.
deviceAlternateId
Description
The deviceAlternateID represents the source of an agrirouter command, but not necessarily the source of the message itself. E.g. a telemetry platform would mark itself as deviceAlternateId and the virtual CU as source of message (content). The deviceAlternateId is the id of the endpoint.
endpointId
gatewayId
Description
The gatewayId is an enumeration to determine the used protocol for all communication after the onboarding:
2= MQTT
3=HTTP
Switching GatewayID MQTT <→ HTTP works, but it may only be used for migration from one gateway to the other.
Data loss might occur, contact the agrirouter support for further information. |
sensorAlternateId
TeamsetContextId
Description
The TeamsetContextId is used to describe a unique combination of different machines and CUs attached to a CU or Virtual CU.
The scope of the TeamsetContextId is the account of the user.
Usually, the TeamsetContextId is a UUID, but it could also be a hash value derived form the Device Description.
For further requirements, please see the notes in the description for EFDI messages.