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.

Where to find

As API/As Developer

The value is delivered with the authentication request. The value is also part of the billing metrics

As End User

The value can be found in the agrirouter UI endpoint Information.

512
Figure 1. agrirouter account ID

applicationId

Description

A UUID identifying an application regardless of the software version.

Where to find

As API

The value cannot be found by the api, it has to be entered into the application by the developer.

The developer can find the ID in his developer account:

application ID (marked [1])
Figure 2. application ID (marked [1])

As End User

The value can be found in the agrirouter UI endpoint information

image49
Figure 3. applicationID = endpoint software ID

capabilityAlternateId

Description

This is a value required by the IoT Gateway of the agrirouter. It has no further meaning for the endpoint or app instance and shall just be delivered with requests.

Where to find

As API

The value is delivered with the onboarding request

As End User

The value cannot be found by an end user and has no meaning for him.

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.

Where to find

As API

The value cannot be found by the API. It has to be entered by the developer.

The developer can find the certificationVersionID in his endpoint software overview:

certificationVersionId (see below the title)
Figure 4. certificationVersionId (see below the title)

As End User

The value can be found in the agrirouter UI endpoint Information

image49
Figure 5. certificationVersionId = endpoint software version ID

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.

Where to find

As API

The value is delivered with the onboarding request and used by the app instance to communicate with its endpoint.

As End User

This ID cannot be found in the UI by the end user

endpointId

Description

The endpointID is the unique address of an Application Instance on the agrirouter. It’s used to address the outbox and inbox.

An endpoint can be an Application, a CU or a Telemetry platform.

Where to find

As API

The value is delivered with the onboarding request.

As End User

The value can be found in the agrirouter UI endpoint Information

512
Figure 6. agrirouter endpoint ID

endpointId = sensorAlternateId

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.

Where to find

As API

see above

As End User

see above

sensorAlternateId

Description

The sensorAlternateID is the address of an app instance at the agrirouter that marks the source of a message and can be used to directly address messages to this specific app instance or Virtual CU.

Where to find

As API

The own sensorAlternateId of an app instance is delivered with the onboarding request.

The value of other app instances is delivered with any agrirouter message, marking the source of the message.

As End User

The id is an endpointID and can be found like the endpoint Id.

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.

Where to find

As API

The TeamsetContextId is sent in the envelope of every message. This information is forwarded through agrirouter so that it can be received by an app instance receiving this message.

As End User

An end user cannot see this value.