Creating and Updating Device Data

The OTbase Inventory'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.

Required access rights

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

Create a single device resource

In order to create a single device entry, the device object to be created is specified by its device id in a POST request. The body of the POST request contains device details in accordance with the Portable Inventory Data format but without the envelope.

Mandatory fields

When creating entries for new devices, the following fields are required:

• 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.

POST ot-base/api/v1/devices/deviceID

{   
        'description': 'enterDescription',
        'hardware': { 
              'model': 'enterDeviceModel', 
              'type': 'enterDeviceType',
              'vendor': 'enterVendorName'
        }
        
}

import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID
data = {
    'description': 'enterDescription', # Enter a description between the qoutes
    'hardware': {
      'model': 'enterDeviceModel', # Enter the device model between the qoutes
      'type': 'enterDeviceType', # Enter the device type between the qoutes
      'vendor': 'enterVendorName' # Enter the vendor's name between the qoutes
      }
}
response = requests.post(url, json=data, auth=auth) 
print(response.status_code)         
print(response.text)

Update a single device resource

Updating a single device entry is done by using a device id in a POST request. The body of the POST request contains device details in accordance with the Portable Inventory Data format but without the envelope.

Note: 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 as in the case below.

POST ot-base/api/v1/devices/deviceID

{
     "description":'enterNewDescription'
}

import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter a device id between the quotes.
deviceID = 'enterDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+deviceID

data = {'description': 'enterNewDescription'}

response = requests.post(url, json=data, auth=auth) 
print(response.status_code)         
print(response.text)

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.

POST ot-base/api/v1/devices/enterOldDeviceID

{
     "deviceId":'enterNewDeviceId'
}

import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

# Enter the old device id between the quotes.
oldDeviceID = 'enterOldDeviceID'

url = 'https://'+hostname+'/ot-base/api/v1/devices/'+oldDeviceID

data = {
 'deviceId': 'enterNewDeviceId'
 }

response = requests.post(url, json=data, auth=auth)
print(response.status_code)         
print(response.text)
        

Create or update 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

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

import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'

data = [
    {
        'deviceId': 'KWR-10.Desktop1',
        'description': 'Engineering Station 5'
    },
    {
        'deviceId': 'KWR-10.PLC5',
        'context': { 'otSystem': 'Scrapper control'}
    }
     # etc ...
]

response = requests.post(url, json=data, auth=auth)
print(response.status_code)
print(response.text)

You can also use the devices object in the content, which allows you to directly use data that came from an OTbase GET response, or from an OTbase JSON data dump.

Request Body:

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

Fields that cannot be updated

For devices that are monitored by OTbase Discovery, the following fields cannot be updated via the REST API because they are exclusively set by OTbase Discovery:

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

Note: The system will ignore any attempt to change the content of these fields.

Response message for single device resources

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

Response:

{
         "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 more detailed description about the specific log type.

Example:

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

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

Response message for bulk updates

When updating multiple device resources in a bulk operation your request body should be comprised of a list. For example:

POST ot-base/api/v1/devices

{
  "devices": [
     { "deviceId":"{{deviceID1}}", "description":"{{descriptionUpdate1}}" },
     { "deviceId":"{{deviceID2}}", "context":{"otSystem":"{{otSystemName2}}"} }
      ...
  ]
}

import requests
# Enter your hostname (for example: myserver.com or 127.0.0.1) between the quotes. 
hostname = 'enterHostnameOrIP'

# Replace username and password with your username and password credentials.
auth=('username', 'password')

url = 'https://'+hostname+'/ot-base/api/v1/devices/'

data = {
    'devices': [
        {
            'deviceId': 'deviceID1',
            'description': 'descriptionUpdate1'
        },
        {
            'deviceId': 'deviceID2',
            'context': { 'otsystem': 'otSystemName2' }
        }
       # etc ...
    ]
}
response = requests.post(url, json=data, auth=auth)
print(response.status_code)
print(response.text)
        

the response message has the following format:

Response:

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

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

Detailed Response Example:

{
         "total":3,
         "inserted":1,
         "updated":1,
         "unchanged":0,
         "skipped":1,
         "results":[
                 {
                         "deviceId":"LANGNER.Desktop1",
                         "log":[
                                 {"WARNING":"No connection changes. Monitored by OTbase Discovery"},
                                 {"WARNING":"No software changes. Monitored by OTbase Discovery"},
                                 {"WARNING":"No module changes. Monitored by OTbase 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 OTbase 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