Skip to content

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.

    Import

  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.

Import the template

Create a new SmartREST template

  1. Click "New Template" at the right of the top menu bar. New template
  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.

    Continue

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.

Add message

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.

Add message

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:

New response

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.

SmartREST template

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.


Last update: May 9, 2022