Creating and updating device data using the REST API

The OT- Base Asset Center's REST API offers a great deal of flexibility when it comes to managing your device inventory. Not only can you retrieve information about existing devices, but you can also use the API to create brand new entries in the inventory. This is incredibly useful when you need to add new devices to your inventory, such as when you're adding new equipment to your network. Additionally, the API also allows you to update existing inventory entries, which can be very helpful when you need to make changes to device information. This could include updating the device's name, description, or location, for example.

 

Required access rights

In order to create or update device entries, the account used for authenticating at OT-BASE must be a member of a role with the permission to import data.

Creating or updating a single device resource

In order to create or update a single device entry, the device resource to be created or modified is specified by its Device ID in a HTTP POST command:

POST ot-base/api/v1/devices/{deviceId}

The content of the POST command contains device details according to the Portable Inventory Data format without the envelope. Note that device data may be incomplete. For example, if you only want to update the description of a particular device, it would be sufficient to use the following content:

{
     "description":"My new description"
}

A special case is to assign a new device ID to a device. This is accomplished by specifying the new device ID in the "deviceId" field, which can otherwise be omitted in the content. Example:

POST ot-base/api/v1/devices/OldDeviceId
{
     "deviceId":"NewDeviceId"
}

When creating an entry for a new device, the following fields must be set: hardware.vendor, hardware.model, and hardware.type.

Creating or updating multiple devices

Multiple devices can be created or updated in a bulk operation by writing to the devices resource with no device ID specified.

POST ot-base/api/v1/devices

The content of this command contains one or many device entries in an array. Each entry must specify a deviceID. Example:

[
     { "deviceId":"KWR-10.Desktop1", "description":"Engineering Station 5" },
     { "deviceId":"KWR-10.PLC5", "context":{"otSystem":"Scrapper control"} }
]

 

You can also use the devices object in the content, which allows you to directly use data that originates from an OT-BASE GET API request, or from an OT-BASE JSON data dump:

{
  "devices": [
     { "deviceId":"KWR-10.Desktop1", "description":"Engineering Station 5" },
     { "deviceId":"KWR-10.PLC5", "context":{"otSystem":"Scrapper control"} }
  ]
}

Mandatory fields

When creating entries for new devices, the following fields must be set: hardware.vendor, hardware.model, and hardware.type. It is recommended to set the field "stage" to the proper value; if no value is set, the value "installed" will be used as a default.

Fields that cannot be updated

For devices that are monitored by OT-BASE Asset Discovery, the following fields cannot be updated via the REST API because they can exclusively be set by Asset Discovery:

• Hardware vendor, model, and version
• Network connections, including network addresses
• Installed software and firmware
• Installed hardware modules
• Location ID

An attempt to change the content of these fields will be ignored.

Response message for single device resources

After completion of the request, OT-BASE will send a response message with information about success or failure. When updating single device resources, the response message has the following format:

{
         "action":action_type,
         "log":[{log_type:log_text}, ...]
 }

• action_type may be any of the following: "inserted", "updated", "unchanged", "skipped".
• log_type may be any of the following: "ERROR", "WARNING", "INFO".
• log_text is a descriptive Text.

Example:

{
         "action":"updated",
         "log":[
                 {"WARNING":"No connection changes. Monitored by Asset Discovery"},
                 {"WARNING":"No software changes. Monitored by Asset Discovery"},
                 {"WARNING":"No module changes. Monitored by Asset Discovery"}
         ]
 }

In this example, a device resource was updated, but some fields are unchanged because the device is monitored by OT-BASE Asset Discovery, in which case settings for connections, installed software, and installed hardware modules can only be changed by Asset Discovery.

Response message for bulk updates

When updating multiple device resources in a bulk operation (i.e. referencing the "devices" resource with no device ID given), the response message has the following format:

{
         "total":count,
         "inserted":count,
         "updated":count,
         "unchanged":count,
         "skipped":count,
         "results": [
                 {"deviceId":device_id,
                  "action":action_type,
                  "log":[{log_type:log_text}, ...]},
                 ...]
 }

• count is the number of total / inserted / updated or skipped devices
• device_id is the device ID of the device for which results are reported
• action_type may be any of the following: inserted, updated, unchanged, and skipped.
• log_type may be any of the following: ERROR, WARNING, and INFO.
• log_text is a descriptive Text.

Example:

{
         "total":3,
         "inserted":1,
         "updated":1,
         "unchanged":0,
         "skipped":1,
         "results":[
                 {
                         "deviceId":"LANGNER.Desktop1",
                         "log":[
                                 {"WARNING":"No connection changes. Monitored by Asset Discovery"},
                                 {"WARNING":"No software changes. Monitored by Asset Discovery"},
                                 {"WARNING":"No module changes. Monitored by Asset Discovery"}
                         ],
                         "action":"updated"
                 },
                 {
                         "deviceId":"LANGNER.Desktop2",
                         "log":[],
                         "action":"inserted"
                 },
                 {
                         "deviceId":"LANGNER.Desktop3",
                         "log":[{"ERROR":"Device is decommissioned"}],
                         "action":"skipped"
                 }
         ]
 }

In this example, three devices were attempted to be updated using a bulk request. The device LANGNER.Desktop1 was partially updated; some fields were left unchanged because the device is monitored by OT-BASE Asset Discovery. The device LANGNER.Desktop2 didn't exist in the database and was successfully added. The device LANGNER.Desktop3 was skipped because while it was found in the database, it is decommissioned and therefore cannot be updated.

Video