Applications

Types of applications

Applications are software products that have implemented an interface to the agrirouter. There are 3 Types of possible applications:

Selecting the application type

It’s not always obvious to which category a new application belongs. To simplify the decision, you can use the following decision tree:

Decision Tree: What type of application do I create?
Figure 1. Decision Tree: What type of application do I create?

For more information on the different types of applications, take a look at the ecosystem.

Register Application

Applications must be certified before they can be provided to the public.

After creating an agrirouter developer account, it is possible to register a communication unit, application or telemetry platform.

agrirouter endpoint software management
Figure 2. agrirouter endpoint software management

The following information should be available to create a communication unit, application or telemetry platform:

# Description Remarks

1

Name

Short name of application

2

Brand

Your company or product brand

3

Type

farming software, communication unit (CU) or telemetry platform

4

Support URL

Your company or product support URL for end user

5

Description

Descriptive text, including main features, supported message in human readable format, required DDIs

6

Provider or product logo

The logo will be visible to end users and should clearly identify your company or product.

The logo must comply with the following rules:

  • Allowed formats: .png, .svg or .gif

  • Maximum size: 512KB

  • Must have a transparent background

7

Certification version

Purpose of this field is to differentiate multiple versions of the application; for each new version with new capabilities, a new certification version must be created.

Version Number of the certification: (Integer (!) version Id) this is a version that requires a DKE certification (typically because the capabilities have changed compared to previous version)

8

Technical message types:

Technical message types the endpoint can send and receive.

  • The applicationCertificationVersion is not the software Version, but just an internal identifier for the DKE certification.

  • An Application can also be the software part of a CU. see Glossary.

All required steps are available in Endpoint Software Management in the section agrirouter for developers (1) in the launch pad:

  • List of existing applications (2)

  • Registration of new application (3)

  • Details on application (4)

  • Application versions (5)

  • Creation of new application version (6)

agrirouter application registration
Figure 3. agrirouter application registration

After a new version has been created, the supported capabilities for this version can be defined. With the button "New", the technical message types supported by this application version can be selected. Finally, the direction (send/receive) of the capabilities must be specified before the version can be submitted.

After submitting, DKE will receive a notification and set the status to Approved for Testing, so that instances of this endpoint can be onboarded. Please also send an email to [email protected], once you created a new software version that shall be approved for testing.

Please be aware of support business hours.
agrirouter warning
Figure 4. agrirouter warning

Once the request has been submitted by the application developer (the status of the certification request changes to submitted),

  • it can no longer be changed by the application developer

  • the agrirouter shall create a unique certification version ID

  • both IDs shall be displayed in the detail view of the certification request

Application certification

Every application (communication unit, farming software or telemetry platform) has to be certified by the DKE or a trusted partner of the DKE. During this certification every application gets a unique certification identifier. This identifier ensures that the certification can only be applied to the single version of the application.

The certification shall disclose name, version information and supported technical message types, in order to allow the agrirouter to check whether the application supports a certain technical message type and to properly display the name of the application as an endpoint in an end-user’s account after registration of an instance of the endpoint.

All information on certification can be found here.

The certification also ensures that there will be a unique ID for the application which the application can send to the agrirouter in order to allow the agrirouter to look up its capabilities.

The certification allows the agrirouter to check the state of the application with a given ID. The agrirouter needs that to make sure that only certified apps communicate with the productive platform.

Workflow for application certification; status flow
Figure 5. Workflow for application certification; status flow

This certification needs to be done initially once for each application before instances of the application may be registered within end-user accounts.

After the initial certification, each time changes to the capabilities are made in subsequent releases, a new certification is required for the new version of the application.

The app provider has to create a new version in the agrirouter user interface. This new version has the initial status New.

Once he selected all the desired capabilities for the new version, he can submit this version and the status changes to submitted.

DKE initially decides if this version can be certified and sets the status to Approved for testing.

An application developer and his listed test customers can now onboard instances of the new application version.

After testing, the app provider can certify his app to set it to approved. Now everyone can onboard instances of the app.

If the app provider decides that an app version is outdated, he can set the status for this app to Blocked and instances of this app will no longer be able to send messages to or receive messages from the agrirouter. If the test fails, the app cannot be approved for testing or an app is finally blocked, the status will be set to Rejected.

  • For communication it is indispensable that this certification id is transmitted with the onboarding request and the capabilities message. The developer is obliged to store this certification id as well as the application id securely in every delivered application or application instance. The storage has to be encrypted.

  • The agrirouter will not provide functionality to validate that applications correctly handle the exchanged data content. Certification partners only certify the capabilities of an application for implementing the agrirouter communication protocol, meeting some requirements. DKE and the agrirouter support team is not allowed to take a look inside the message body.

Approval of the application certification

For all certification requests in status submitted, agrirouter administrators are able to change the status:

  • either to rejected, making further processing impossible, or

  • it can be set to Approved for Testing if the certification request was successful.

In status Approved for Testing, application developers can register farmers’ accounts as test accounts. If a certification version is in status Approved for Testing, instances with this certification version can be registered in these test accounts and an external test can be started. The developers account automatically is an end user account that is a test account. This means that a developer can onboard an endpoint in his account.

Using other accounts is not possible, because the certification version is not yet approved by DKE for public use. When the certification request is in status Approved for Testing, the agrirouter administrator can either finally set the status of the request to Approved in case of successful testing or rejected if testing was not successful.