Skip to content

Loading objects dynamically

Some platform objects need to be loaded once the platform is already running. This is about objects that are not essential for the platform to function initially, but will be necessary to use the platform to its fullest potential.

Only data that cannot be added through the API will be covered here.

Which objects can be loaded dynamically

We will cover adding:

  • Interfaces
  • Codecs
  • Channels
  • Device types

How to add objects dynamically

Whether the Management API is started or not, you can add data as long as the database is running. For this we will use a SQL script.

This section will explain how you can add each type of object that was mentioned in the previous section. Please keep in mind that these commands have only been tested using a MS-SQL server.

You could edit existing data in the platform, however be careful with it. For example, editing an Interface could break an existing Channel Configuration for some devices. If possible, avoid editing objects but prefer to delete and recreate instead.

Executing SQL scripts

You can execute SQL scripts on the database using DBeaver, or Azure Data Studio, or mssql-cli, or any other SQL client that will work for you with MS-SQL databases.

Interfaces

You can add a new Interface using:

INSERT INTO interface (name, type, configuration)
VALUES ('new interface name', 'iot-hub', '{"hostname":"my-iot-hub.azure-devices.net"}');
  • name should be unique
  • type can only be one of : ['iot-hub']
  • configuration should be valid JSON. Its content varies accordingly to the Interface type:
  • if it is iot-hub: JSON should be {"hostname":"your iot hub hostname"}

If you want to support a new Interface type of connection, there are several steps to follow:

  • Add the new type to the enumeration used in the Interface TypeORM entity in file management-api/src/channels/models/interface.entity.ts
  • Set up the new Interface type to be recognized when provisioning devices in management-api/src/providers/interface-provider.factory.ts by adding a new getter functino for your Interface type.
  • Create a new migration and apply it to your database in order to use the new Enumeration value in your SQL script.

If an Interface type has no implementation provided in the InterfaceProvisioningFactory, any provisioning or deprovisioning on these Interfaces will fail.

Codecs

You can add a new codec using:

INSERT INTO codec (name)
VALUES ('new codec name');
  • name should be unique

Adding a new Codec means adding a new way to decode telemetry. The function implementing the new codec cannot be provided in the database.

Its implementation should be covered in the decoderMapping dictionary defined in azure-functions/decoding/decoders.ts.

If a Codec is used in a Device's Channel Configuration, but the Codec has no implementation, the function responsible for decoding the Device telemetry will fail and the Device's undecoded telemetry will be discarded.

Channels

You can add a new channel using:

INSERT INTO channel (name, interfaceId, codecId)
VALUES ('new channel name', '259c6d04-f96e-4466-95b4-49b13db04ca9', 'ffa4184e-bcab-4fe4-8ba5-34bb17bde3ed');

You can find the Interface and Codec IDs you need by listing them:

SELECT * FROM interface;
SELECT * FROM codec;

When the new Channel is inserted in the database, you can directly use it in the API for new Device Channel Configurations.

Device Types

You can add a new Device Type using:

-- Insert device type info
INSERT INTO device_type (name, description)
VALUES ('new device type name', 'device type description');

-- Insert available channels for the device type
INSERT INTO device_type_available_channels_channel (deviceTypeId, channelId)
VALUES ('bf879eed-46a5-4103-b3a7-08ed3dc080b2', 'bf879eed-46a5-4103-b3a7-08ed3dc080b2');
  • name should be unique

You can find the Device Type and Channel IDs you need by listing them:

SELECT * FROM device_type;
SELECT * FROM channel;

When the new Device Type is inserted in the database, you can directly use it in the API for new Devices.