Onboarding App Instances

General Overview

The onboarding workflow is needed to onboard app instances and create endpoints in the agrirouter. The result of the onboarding process has to be stored.

General onboarding workflow
Figure 1. General onboarding workflow

Before any data flow can happen, the very first command sent by the endpoint has to be the Capabilities command.

Workflow for Farming Software and Telemetry Systems

Telemetry systems and Farming Software need to assign their own userID to the accountID of the user at the agrirouter. Therefore, a verification should be performed before onboarding.

onboarding Workflow for a farming software or telemetry platform
Figure 2. onboarding Workflow for a farming software or telemetry platform

Workflow for CUs

agrirouter onboarding process for a CU
Figure 3. agrirouter onboarding process for a CU

The CU onboarding mechanism needs less steps than the Farming Software and Telemetry software, but it does not give any information on the account before onboarding is performed.

The following parts of onboarding are not required for CU onboarding:

  • Authentication

    • Entering certificates in the agrirouter UI

    • Adding one or more redirect URLs in the agrirouter UI

  • Verification

  • onboarding with a Signed request

Workflow for Virtual CUs

Onboarding virtual CUs through a telemetry platform is done using a command. This is described in Cloud solution commands.

From the end user’s perspective, it is mostly dependent on the telemetry platform if there is any selection mechanism or if it is done automatically.

Creating a registration code

Using the agrirouter UI

The registration code for a new CU can be created by the end user clicking "+ Connection" in agrirouter’s control center. He gets a 10-digit code consisting of letters and numbers. A CU needs an interface to input this registration code. Registration Codes are independent of Application ID

Requesting a registration code in agrirouter UI
Figure 4. Requesting a registration code in agrirouter UI
registration code for a CU
Figure 5. registration code for a CU

As result of the authorization

If the authorization process is done using parameter response_type=onboard, the result will include a regcode. This regcode is a registration code.

Telemetry Platforms

A telemetry platform has to be onboarded using the authorization process. Once it is onboarded, it can onboard virtual CUs by itself. Therefore, it can use a special command. This is described in Cloud solution commands.

Collecting and setting up relevant information

The onboarding request requires several different information:

ApplicationID and X-Agrirouter-ApplicationID

Both IDs are the same, they can be found in the agrirouter software endpoint UI of the developers account:

Finding the applicationID (marked [1])
Figure 6. Finding the applicationID

CertificationVersionID

The CertificationVersionID is the ID unique to this specific app certification. It can be found when clicking on the required Endpoint Software Version:

Finding the certificationVersionID
Figure 7. Finding the certificationVersionID

Setting up private and public key

This step is not required for CUs

As the requests need to be signed, the public key has to be stored within the agrirouter. This can be done, calling "Edit" on the Endpoint Software Management Screen. The agrirouter UI offers the possibility to create a key pair, you can however create your own one and just store the public key on agrirouter.

Generating Private and Public Key in the agrirouter UI
Figure 8. Generating Private and Public Key in the agrirouter UI

External Id

The external Id - to be seen in the Body Information of the onboarding request (only called id there) - needs to be a URN, which fits to the definitions in the general conventions.

For farming software and telemetry platforms the external Id should be directly related to a user account in your platform. For privacy purposes, it would also be ok to hash or encrypt the user id so it is not visible to agrirouter. The uniqueness of external ID is limited to the tenant and the application to prevent potential issues caused by namespace collision.

Examples for valid external IDs are:

urn:myfarmingsoftware:[email protected]
urn:mytelemetryplatform:userid-123
urn:fancyfarming:3e9156eb-efc1-4742-b820-ca3bf0eecdf0
urn:greattelemetry:kuQn0KfwEY0s0lT1fQIAWdqlaezuUHfLV/uNC0dvqKk=

onboarding Endpoint URLs

The endpoint URL differs, depending on your desired geolocation and the Quality Assurance or Productive Environment.

The request must be a HTTP Post request to the URL found here.

Like every URL in this document, these URLs might change in the future or there might be additional ones for new Areas.

Signing requests

For onboarding, the agrirouter must be sure that the requests actually come from an instance of the app specified in the request. Therefore, the payload must be signed with the applications private key. The corresponding public key must be maintained by the developer in agrirouter per application, see above.

A Payload encryption is not needed since all communication is encrypted with TLS

All signatures used for the onboarding and revocation process shall be created by:

  • hashing the request body (SHA256)

  • then using the private key to create an RSA signature of the hash

  • Create HEX representation of this hash

  • Add the hex string as "X-Agrirouter-Signature" to the header of the HTTP call

agrirouter will look up the public key for the app id specified and verify the signature.

Verification Request

The verification request is used to actually check if the endpoint is for the desired application and account before actually onboarding it.

General

The address for the verification request is as follows:

Method Address

POST

api/v1.0/registration/onboard/verify

Request Information

The app instance has to send a HTTP Post request.

Header Information

For CU onboarding

For CUs, this is not required or available

For Farming Software and Telemetry Platform onboarding

The Request shall include the following header information:

Name Type Description

Authorization

String

"Bearer "+ the registration code

Content-Type

String

application/json

X-Agrirouter-ApplicationId

String

[Application Id]

X-Agrirouter-Signature

[Signature]

see Signing requests

Body Information

The request body includes the same parameters as the onboarding requests body:

The request body is a JSON object including the following Parameters:

# Name Type Description

1

id

String

The unique ID of the endpoint; we advise to create a URN

2

applicationId

String

The application ID for the application, provided in the agrirouter developer UI

3

certificationVersionId

String

The ID of the certification software version provided in the agrirouter developer UI

4

gatewayId

String

The desired communication protocol after onboarding

2: MQTT

3: REST

Example: "2"

5

certificateType

String

Type of the desired certificate;

Possible values: PEM,P12

6

UTCTimestamp

String

A Timestamp like this: 2018-06-20T07:29:23.457Z

7

timeZone

String

A TimeZone like this: "+03:00"

EXAMPLE

{
  "id": "urn:myapp:snr00003234",
  "applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "gatewayId": "3",
  "UTCTimestamp": "2018-06-04T12:00:03.000Z",
  "timeZone": "+02:00"
}

Verification Result

The result is a HTTP response code with a JSON object in the Body

Result codes

There are different result HTTP Status codes indicating the result

Code Description

200

The validation was successful

400

There was an error in the request

401

The request was unauthorized; the provided registration code was unknown

Body Information

Success

For a successful result, the body will include a JSON object like this:

{
  "accountId": "4823443c-fd0d-44a7-81a6-06104455945a"
}

It includes the accountId, so that an app provider can check if this accountId might already be known. For apps that can be onboarded only once (like an FMIS, where it doesn’t make any sense to have 2 of the same kind), this would mean that onboarding is not needed.

Failure

In case of Failure, an error message is provided. Possible ErrorMessages can be found here.

Onboarding Request

To onboard a new endpoint, the endpoint has to send an onboarding request providing the registration code to agrirouter.

The request is a HTTP POST request.

There is no MQTT onboarding mechanism, so onboarding always has to be done using REST.

Request information for signed onboarding

This is the onboarding request for Farming Software and Telemetry platforms, not for CUs.

General

The address for the onboarding request is as follows:

Method Address

POST

api/v1.0/registration/onboard/request

Header Information

For Farming Software and Telemetry Platform onboarding

The Request shall include the following header information:

Name Type Description

Authorization

String

"Bearer "+ the registration code Remark: There is a space between bearer and registration code!

Content-Type

String

application/json

X-Agrirouter-ApplicationId

String

[Application Id]

X-Agrirouter-Signature

[Signature]

The signature, see Signing requests

Body Information

The request body is a JSON object including the following Parameters:

# Name Type Description

1

id

String

The unique and persistent ID of the endpoint; we advise to create a URN

2

applicationId

String

The application ID for the application, provided in the agrirouter developer UI

3

certificationVersionId

String

The ID of the certification software version provided in the agrirouter developer UI

4

gatewayId

String

The desired communication protocol after onboarding

2: MQTT

3: REST

Example: "2"

5

certificateType

String

Type of the desired certificate;

Possible values: PEM,P12

6

UTCTimestamp

String

A Timestamp like this: 2018-06-20T07:29:23.457Z

7

timeZone

String

A TimeZone like this: "+03:00"

 
{
  "id": "mydeviceid",
  "applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "gatewayId": "3",
  "UTCTimestamp": "2018-06-04T12:00:03.000Z",
  "timeZone": "+02:00"
}

Request information for CU onboarding

This is the onboarding request for CUs.

General

The address for the onboarding request is as follows:

Method Address

POST

api/v1.0/registration/onboard

Header Information

The Request shall include the following header information:

Name Type Description

Authorization

String

"Bearer "+ the registration code

Content-Type

String

application/json

Body Information

The request body is a JSON object including the following Parameters:

# Name Type Description

1

id

String

The unique and persistent ID of the endpoint; we advise to create a URN

2

applicationId

String

The application ID for the application, provided in the agrirouter developer UI

3

certificationVersionId

String

The ID of the certification software version provided in the agrirouter developer UI

4

gatewayId

String

The desired communication protocol after onboarding

2: MQTT

3: REST

Example: "2"

5

certificateType

String

Type of the desired certificate;

Possible values: PEM,P12

Example:

{
  "id": "mydeviceid",
  "applicationId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "certificationVersionId": "e0eb00ff-e2ef-4429-85f5-2559aceedd6d",
  "gatewayId": "3",
}

Response

Response code

The request has several possible response codes indicating Success or Failure:

Code Possible problem

201

Success; Analyse onboarding result to get started

400

The Request was invalid

401

Unauthorized; meaning that one of the given header parameters is wrong. Refer to the error message

Success

On success, the HTTP response code will be 201.

The result is a json object including the information required for onboarding.

# Name Type Description

1

authentication

Object

Includes all authentication information

1.1

certificate

String

The certificate required for communication; Public AND Private Key

1.2

secret

String

The passkey for the certificate

1.3

type

String

Type of Certificate; PEM or P12 (short for PKCS#12)

2

capabilityAlternateId

String

A value that just has to be saved and sent in several scenarios

3

connectionCriteria

Object

Includes all information required for further communication

3.1

gatewayId

String

Assigned gateway; 2= MQTT, 3=REST

3.2

host

String

MQTT only: The broker address

3.3

port

Integer

MQTT only: The broker port

3.4

measures

String

Endpoint URL of the inbox or Topic, when using MQTT

3.5

commands

String

Endpoint URL of the outbox or Topic, when using MQTT

3.6

clientId

String

MQTT only: The ClientID of the endpoint

4

deviceAlternateId

String

The device ID used to mark the source of a message from this device and as endpointId

5

sensorAlternateId

String

The deviceID used to mark the source of the communication from this device

Example for onboarding an REST endpoint:

{
  "authentication": {
    "certificate": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END ENCRYPTED PRIVATE KEY-----\n-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "secret": "77R8cjOGi9yTCBt2",
    "type": "PEM"
  },
  "capabilityAlternateId": "7bc8ab05-a0de-40db-a259-7deefb1265e9",
  "connectionCriteria": {
    "gatewayId": "3",
    "measures": "https://dke-qa.eu10.cp.iot.sap/iot/gateway/rest/measures/c067272a-d3a7-4dcf-ab58-5c45ba66ad60",
    "commands": "https://dke-qa.eu10.cp.iot.sap/iot/gateway/rest/commands/c067272a-d3a7-4dcf-ab58-5c45ba66ad60"
  },
  "deviceAlternateId": "c067272a-d3a7-4dcf-ab58-5c45ba66ad60",
  "sensorAlternateId": "5564ce96-385f-448a-9502-9ea3c940a259"
}

Example for onboarding an MQTT Endpoint

{
  "deviceAlternateId": "341cb230-83a7-45a1-a023-34cc1f1d58f5",
  "capabilityAlternateId": "bb8e66c9-e8e1-4a06-959e-f3a1940a68e0",
  "sensorAlternateId": "19e90568-9275-4023-879d-432c379081fe",
  "connectionCriteria": {
    "gatewayId": "2",
    "measures": "measures/341cb230-83a7-45a1-a023-34cc1f1d58f5",
    "commands": "commands/341cb230-83a7-45a1-a023-34cc1f1d58f5",
    "host": "dke-qa.eu10.cp.iot.sap",
    "port": "8883",
    "clientId": "341cb230-83a7-45a1-a023-34cc1f1d58f5"
  },
  "authentication": {
    "type": "PEM",
    "secret": "xC6zMirxXHDsXDXFR4gE42qq79l7AheIvqiW",
    "certificate": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...-----END CERTIFICATE-----\n"
  }
}

Save all those information, you’ll need them for communication with the agrirouter.

Failure

On Failure, a JSON object including an error message is received, e.g.:

{
  "error": {
    "code": "0110",
    "message": "Signing header is invalid, the request has timedout, or UTCTimestamp is not provided",
    "target": "",
    "details": []
  }
}

Possible Error codes can be found in the error list

Onboarding Result in the agrirouter UI

When a new endpoint is onboarded, its name consists of the name of the application and the onboarding timestamp. .Endpoint name including timestamp image::general/endpointName.png[Endpoint name including timestamp]

Handling Signature Issues

If you experience problems with an invalid signature, (Code 107), try the following:

  • make sure you encoded the whole body

  • compare the signature with the result of the node server tool delivered with the postman collection

  • check the timestamp. If your local time is ahead of or too far behind agrirouter servers time, it will not recognize the signature as valid. The agrirouter HTTP answer includes a timestamp reporting agrirouter’s server time.