Integrating the DigiCMR Android App

Introduction

The DigiCMR App for the Android platform, can be used by App builders to add the e-CMR signing process to their existing Apps. The DigiCMR App can provide the following functionality to your Apps:

  • Show the e-CMR details for a passed CMR number.
  • Start the signing process for a passed CMR number.

Quickstart

1. Get your client credentials.

To be able to call and integrate the DigiCMR App from your own Android Apps, you need to obtain client credentials by registering your App. To register your app and retrieve the necessary client credentials, please contact support at support@pionira.be

2. Launching the DigiCMR App.

You can start the DigiCMR from your App using an Intent. Starting the App requires an Intent action to be set. DigiCMR can be started in 2 modes. (see a list of Intent filter actions) One of which is to show the “Consignment Note” and the other is to start the “Sign Off” procedure.

To properly start the application, it is necessary to always pass the client credentials as intent extras (see Intent extras) The Consignment Note Number and the user id or identification can be passed as As non required Intent extra is the User Id.

3. Select action

Depending on the action the user wants to perform, view the e-CMR details or initiate the “Sign Off” process, the intent needs to use an intent action as shown in the table below.

4. Provide the consignment note number as an intent extra.

Use the be.pionira.digicmr.extras.CONSIGNMENT_NOTE_NUMBER intent extra to pass the consignment note number to view or sign. When this parameter is not passed, the application will start an the driver will be able to browse or search completed consignment notes.

5. Sync with the user from your apps

Once the DigiCMR App is started the user must authenticate. This is done the first time by registering once using the credentials the user used to register at the Xynaps site. After sign in the user can provide a PIN code to secure the access to the App. This means that everytime the App will be started standalone or via an intent the App will ask the user to sign in using his PIN code.

This means that each time the user starts the DigiCMR App from your application to sign or view a consignment note, he will need to enter his PIN code. To have a better user experience, your App can pass a value, using the be.pionira.digicmr.extras.USER_ID intent extra, that identifies the user in your App. When we receive this identification, we will perform a lookup to see if that user has already signed into the App once. If we can lookup the indentification and find the user properties, we can automatically sign in the user without asking the PIN code. If we cannot find an identification, we will ask the user to sign in and after succesful sign in we will link the identification with his properties. As a result he will not be asked for his PIN code during future use of the App.

Intent filter actions

Action
Description
be.pionira.digicmr.action.SHOW_CONSIGNMENT_NOTE
Show the consignment note
be.pionira.digicmr.action.START_SIGNOFF_CONSIGNMENT_NOTE
Starts “sign off” of the
consignment note

Intent extras

Extra Required Description
be.pionira.digicmr.extras.CLIENT_ID Yes
Client id provided
by Pionira
be.pionira.digicmr.extras.CLIENT_SECRET Yes
Client secret provided
by Pionira
be.pionira.digicmr.extras.CONSIGNMENT_NOTE_NUMBER No
Consignment note id
be.pionira.digicmr.extras.CONSIGNMENT_NOTE_ID No
Internal DigiCMR id
of the consignment note
be.pionira.digicmr.extras.CONSIGNMENT_NOTE_EXTERNALID No
External id (id provided by an external system)
of the consignment note
be.pionira.digicmr.extras.USER_ID No
User id
be.pionira.digicmr.extras.TENANT_KEY No
Tenant key of the organisation

6. Creating the Intent

Create a new Intent that has one of the two actions previously specified and pass the necessary intent extras, then start the Intent through ‘startActivityForResult’.

7. Return values

Use the Activity.onActivityResult to handle the return values after the DigiCMR Activity finished. See the table below for specific codes.

Activity Results

Code Result
1001 INVALID_CLIENT_CREDENTIALS
1002 CONSIGNMENT_NOTE_NOT_FOUND
1003 CONSIGNMENT_NOTE_SIGNED_FOR_PICKUP
1004 CONSIGNMENT_NOTE_SIGNED_FOR_DELIVERY

8. Passing data to the DigiCMR App

Apps can transfer data to the DigiCMR App using the be.pionira.digicmr.extras.CONSIGNMENT_NOTE_DATA intent extra parameter. The data can contain information about:

  • Pickup and delivery wait times.
  • Registration of empties returned.
  • Changes or additions to the goods transported.
  • Change of the driver
  • Change of truck or trailer

Depending on the state of the consignment note, the consignment note will be enriched wit the passed data if possible. For example, after signing the document for pickup of the goods, it will no longer be possible to pass wait times for pickup.

The extra data must be passed as a json object serialized as a string value, and is structured as follows (intendation and newlines are only for readability):

{
    "reservation": {},
    "pickup": {},
    "delivery": {},
    "empties": [
    ],
    "goods": [
    ],
    "goodsText": "",
    "transportExecution": {}
}
Property Mandatory Description
reservation No
Reservations made by the driver. See the TransportDocumentComment
type in the API specification for a
description of the structure of the data.
empties No
An array of the empties returned
See the EmptiesItem type in the API specification
for a description of the structure of the data.
goods No
An array of the goods transported
See the Product type in the API specification for a
description of the structure of the data.
goodsText No
Formatted text representing the goods transported
transportExecution No
Add driver, truck and trailer information. See TransportExecution
type in the API specification for a
description of the structure of the data.