SmartREST templates

Introduction

SmartREST templates are a collection of request and response templates used to convert IoT Extension data and IoT Extension Rest API calls. For example, you can use SmartREST templates to easily add devices to the platform instead of manually writing the requests each time.

To ease the device integration, IoT Extension supports static templates that can be used without the need for creating your own templates. These templates focus only on the most commonly used messages for device management.

Open the SmartREST template list from the "Device Types" menu in the navigator.

For each template, the following information is provided:

  • "Template name", e.g. Camel

  • "Template ID", e.g. 99

  • "Number of send messages"

  • "Number of responses"

There are two ways to add a SmartRest template:

  • Import an already existing template.

  • Create a new template.

Import an existing SmartREST template

  1. Click "Import" at the right of the top menu bar.

    132015961227.png
  2. In the upcoming window, choose a file to upload by browsing for it.

  3. Enter a template name and a unique template ID (both mandatory fields).

  4. Click "Import" to import the template.

    126029670283.png


Create a new SmartREST template

  1. Click "New Template" at the right of the top menu bar.

    132016190731.png
  2. In the upcoming window, enter a template name and a unique template ID (both mandatory fields).

  3. Click "Continue" to proceed adding messages or responses.

    126035162507.png

Add a message

The message template contains all necessary information to convert the SmartRest request into a corresponding Rest API call which is then sent to the platform.

132016202635.png

To add a new message, navigate to the "Messages" tab in your desired SmartREST template and click "Add message".

Thereafter, complete the following fields:

Field

Description

Message ID

Unique integer that will be used as a message identifier. It must be unique among all message and response templates.

Name

Name for the message. The is a mandatory requirement.

Target REST API

REST API for the target. Dropdown list. May be one of "Measurement", "Inventory", "Alarm", "Event", "Operation".

Method

Request method. May be one of "POST", "PUT", "GET", depending on the selected Target REST API.

Include Responses

Select this checkbox if you want to process the results of the request with response templates.

REST API built-in fields

These fields are optional and vary depending on the target REST API selected. In case no value is provided, a device will be able to set it when sending an actual message.

REST API custom fields

Additional fields can be added by clicking Add field. Enter the API key and select the desired data type.

132018646539.png

In the "Preview" you can see the preview of your request message.

Click "Save" to save your settings.

To delete a message, open it and click "Remove" at the bottom.

Add a response

A response template contains the necessary information to extract data values from a platform REST API call response, which is then sent back to the client in a IoT Extension data format.

To add a new response, navigate to the "Response" tab in your desired SmartREST template and click "Add response". Complete the following fields:

132018761099.png

Field

Description

Response ID

Unique integer that will be used as a response identifier.

Name

Name for the response. Mandatory.

Base Pattern

Base pattern for the response.

Condition

Condition value of the response.

Pattern

At least one pattern is required. Click Add pattern and enter a pattern value.

Click "Save" to save your settings.

To delete a response, open it and click "Remove" at the bottom.

Edit or delete a SmartREST template

To edit a SmartREST template, either click the desired template or click the menu icon and in the context menu click "Edit".

To delete a SmartREST template, click "Remove" in its context menu.

Export a SmartREST template

To export a SmartREST template, click the menu icon and in the menu click "Export". The template will automatically be downloaded.

To export a SmartREST template as IoT Extension file follow these steps:

  1. Open the template of your choice and select the IoT Extension preview tab.

  2. In the IoT Extension preview tab which provides additional information on messages and responses, click "Export IoT Extension".

  3. In the upcoming window, specify the preferred options for the field separator, decimal separator and character set.

  4. Click "Download" to download the template as IoT Extension file.

132018952203.png