Add custom data

Explanation on how to create custom data channels and on how to update the data via the mobile phone.

If you have relevant information available on the asset where the tracker is attached to in another system (for example, your company's ERP system), it can be meaningful to push this data also to the tracker information that is available on the platform. This information can for example contain the shipment information of the asset.

Custom data can also be used to add information uploaded via the mobile app. For example, when you want to add a picture of a damaged asset or a signature via the Sensolus mobile app.

To be able to add custom data to the trackers on the Sensolus platform you should first create custom data channels. A channel is the definition of the business data elements and structure.

Following items can be defined in a channel:

Data structure: define the fields and their type (number, text, enumeration, list, image ..)
Validation rules: define the valid values of a field
Default values: define the default value for a field
Labels: define how the label of the fields that will be used in the interfaces, search filters, etc.

All injected data will be validated against the schema to ensure compliance with the business rules.

Go to Admin → Developers → custom data to add custom data channels to your trackers.

Select

to create a new custom data channel. The following screen appears:

Fill in the following fields:

Table 1.
Field name	Description
Description	The meaningful name you give to the channel (for example: shipment data, repair signoff, ..)
Categories	Select one of the two types: Device Infrastructure
Channel	The channel key is automatically assigned when you create a new channel.
JSON schema	The JSON schema. For more information on the JSON schema, see below
User can push data to channel via UI	Selection box to give users the right to push data to the channel via UI. This is related to the use of the Sensolus mobile app to for example add a signature after maintenance is done. Or to attach a picture of damage to the asset via the mobile app (via a mobile form) Note: If this box is checked, all organization editors and administrators have the rights to update 3rd party data (viewers don't) Note: Create a custom user profile if you want channel update rights on user specific users. The roles related to custom channel rights are: BUSINESS_DATA_VIEWER_ORGANISATION: BUSINESS_DATA_EDITOR_ORGANIZATION:
Always do a location check-in on mobile when this channel is edited.	When you select this function the tracker will always look for a location fix when the user pushes data to the channel via UI (which means via the mobile phone).

Do not forget to click to to save the created custom data channel.

A JSON field contains the following property fields:

"description": description
"title": label
"type": type of the field: boolean, string, number, integer, enum, image
"order": order in the property list
"minimum": in case of number - minimum value
"maximum": in case of number - maximum value
"exclusieMinimum": in case of number - maximum value

Note:

Example to report on the container load and transport via mobile app

Example JSON schema to use to add custom data channel to report information on the container load and transport via the mobile app.


{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Container Information",
  "additionalProperties": false,
  "title": "Container Information",
  "type": "object",
  "properties": {
    "Container Number": {
      "description": "Container Number",
      "type": "string",
      "order": 1
    },
    "Container Location": {
      "type": "string",
      "enum": [
        "Transport Av",
        "Victoria Road"
      ],
      "description": "The Container Location",
      "order": 2
    },
    "Condition": {
      "type": "string",
      "enum": [
        "Full",
        "Empty",
        "Maintenance"
      ],
      "description": "The Condition",
      "order": 3
    },
    "Gross Weight": {
      "description": "Gross Weight",
      "type": "integer",
      "order": 4
    },
    "Loaded On The Train": {
      "type": "string",
      "enum": [
        "Yes",
        "No"
      ],
      "description": "Loaded on the train",
      "order": 5
    }
  },
  "required": [
    "Container Number",
    "Container Location",
    "Condition"
  ]
}

On the mobile phone the interaction looks like this:

In this screen the 'mobile form' as formulated in the 3rd party channel is shown. By clicking on Edit you can fill in the form:

Don't forget to click to save the information

Once you have filled in the form the information is shown as following on the asset status page:

Example to report on the container damage via mobile app

Example JSON schema to use to add 3rd party channel to report on container damage via the mobile app.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Damaged Container Reporting",
  "title": "Damaged Container Reporting",
  "type": "object",
  "properties": {
    "Base repair required": {
      "description": "Container that requires base repair",
      "type": "boolean",
      "order": 4
    },
    "Cleaning required": {
      "description": "Container that requires cleaning",
      "type": "boolean",
      "order": 3
    },
    "Shelf damage": {
      "description": "Container with shelf damage",
      "type": "boolean",
      "order": 5
    },
    "Damage cosmetic": {
      "description": "Container with cosmetic damage",
      "type": "boolean",
      "order": 1
    },
    "Damage functional": {
      "description": "Container with functional damage",
      "type": "boolean",
      "order": 2
    },
    "Side panel damage": {
      "description": "Container with side panel damage",
      "type": "boolean",
      "order": 6
    },
    "Lid damage": {
      "description": "Container with lid damage",
      "type": "boolean",
      "order": 7
    },
    "Comment": {
      "description": "Describe the damage",
      "type": "string",
      "order": 8
    }
  },
  "required": [
    "Damage cosmetic",
    "Base repair required",
    "Damage functional",
    "Shelf damage",
    "Cleaning required",
    "Side panel damage",
    "Lid damage"
  ]
}

When you open the form on the mobile phone it looks like this:

Don't forget to click to save the information

Once filled in it will be shown on the asset details page:

Example to upload images via mobile app

Sometimes you want to add a picture to your asset information. For example, to show the damage to an asset so the maintenance team already has some information on what they should do before the asset arrives in the maintenance hall. This is example code to add pictures via the mobile phone:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Pictures",
  "title": "Pictures",
  "type": "object",
  "properties": {
    "Picture1": {
      "contentMediaType": "image/png",
      "description": "picture 1",
      "contentEncoding": "base64",
      "type": "string",
      "signature": false,
      "order": 1
    },
    "Picture2": {
      "contentMediaType": "image/png",
      "description": "picture 2",
      "contentEncoding": "base64",
      "type": "string",
      "signature": false,
      "order": 2
    },
    "Picture3": {
      "contentMediaType": "image/png",
      "description": "picture 3",
      "contentEncoding": "base64",
      "type": "string",
      "signature": false,
      "order": 3
    },
    "Picture4": {
      "contentMediaType": "image/png",
      "description": "picture 4",
      "contentEncoding": "base64",
      "type": "string",
      "signature": false,
      "order": 4
    }
  },
  "required": [
    "Picture1"
  ]
}

On the mobile phone the interaction looks like this. You are asked to upload pictures form your device of take a picture with the camera on your device:

Don't forget to click to save the information

Once filled in it will be shown on the asset details

Example to add signature via mobile app

Example JSON schema to use to add custom data channel to do a sign-off / set a signature via the mobile app.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Container Repair Sign-off",
  "title": "Container Repair Sign-off",
  "type": "object",
  "properties": {
    "Signature": {
      "contentMediaType": "image/png",
      "description": "Signature",
      "contentEncoding": "base64",
      "type": "string",
      "signature": true,
      "order": 3
    },
    "Damage repaired": {
      "description": "Confirm damage repair",
      "type": "boolean",
      "order": 1
    },
    "Name": {
      "type": "string",
      "order": 2
    }
  },
  "required": [
    "Damage repaired",
    "Name"
  ]
}

On the mobile phone the form looks as following:

When you click the camera in the signature field the following screen opens:

Here you can draw your signature using a digital pen or your finger. click the button to save the signature.

The signature is shown as following on the form after saving it: :

Don't forget to click to save the information

On the asset page the information is looking like this:

Internationalization of custom data

Custom data is available for different languages. To make this available Sensolus provides internationalization support, also for third party enum types. In the visual below you see an example how to define an internationalized enum property in the channel descriptor. The enum_18 field should contain the translations of the set of enum values in the designated languages.

The property that should be internationalized is modeled as an ‘object’ with “i18n:true”.

The transplantation will be processed as follows:

Find the title/description of property in the language of the user if defined, other ways the language of the organization
If not found use the default label of the property

Note: Always use the same property type for each language.

This looks as following in the user interface:

Clickable URL's in custom data fields

The format type for clickable URL's is "URL".

Users can push a URL to this field and the UI will render it as a link.

The convention for a nice render with the following format [label](link "tooltip") :

link has to follow the format URI in RFC-2396 <https://www.ietf.org/rfc/rfc2396.txt>
label as string will show as replace of the link (optional)
tooltip shows when hovering to the link (optional)

Example to add clickable URL to custom data field

Example JSON schema to use to add custom data channel to do add an URL.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "description": "Shipment information RTP",
    "title": "Shipment information",
    "type": "object",
    "properties": {
        "LogisticsProvider": {
            "description": "Logistics provider",
            "type": "string",
            "order": 3
        },
        "Address": {
            "description": "Delivery address",
            "type": "string",
            "order": 2
        },
        "Link": {
            "description": "link to website",
            "type": "string",
            "format": "url",
            "order": 5
        },
        "Content": {
            "description": "Content",
            "type": "string",
            "order": 4
        },
        "ShipmentNumber": {
            "description": "Shipment number",
            "type": "string",
            "order": 1
        }
    },
    "required": [
        "LogisticsProvider",
        "ShipmentNumber",
        "Address",
        "Content",
        "Link"
    ]
}

Or only a link:

{
    "LogisticsProvider": "Google test",
    "Address": "HCMC",
    "Content": "shipment info",
    "ShipmentNumber": "1234",
    "Link": "https://google.com"
}

This results in the following output: