Skip to main content
Skip table of contents

Asset Import in ThingsHub

This document describes the interface between third-party systems and thingsHub Assets - specifically how to import asset data from third-party systems into ThingsHub.

Introduction

Importing Asset data can be done via the thingsHub REST API. Send your data directly to ThingsHub using the API endpoint POST /api/v4/assets-import

This endpoint can be accessed through the official thingsHub API Swagger Documentation.

image-20250304-074639.png

Assets Import API endpoint

From thingsHub 7.0 onwards, all the /v3/assets endpoints have been transferred to /v4/assets with enhanced functionality.
This also includes the /v3/assets-import to /v4/assets-import

If you have been using the thingsHub v3 asset import API, please follow this document to understand how the v4 asset import works and adapt your system accordingly if needed.

For further information on other breaking changes, please consult the breaking changes document for thingsHub 7.0: Breaking Changes in thingsHub 7.0

Importing Assets into ThingsHub

Before starting your import, please ensure that any custom fields in the data are created beforehand.

To find out in detail about Business Object Fields and how to create and manage them, please consult the official thingsHub documentation: Managing Fields

Data and Data Requirements

Basic Requirements

  1. Prepare your data as an array of JSON entries.

  2. Make sure that the array has from 1 to 50000 entries. ThingsHub currently supports importing a maximum of 50000 records at a time.

  3. Primary ID (Required):
    Each asset object must include a unique identifier. By default, the system will look for id or uid keys in the JSON to use as the ID for an asset.
    The ID value also must conform to the ThingsHub ID specification for it to be treated as a valid id. For more details on what a valid thingsHub ID is, consult the documentation:Business Objects ID

  4. Name (Optional):
    By default, the system will use the name field as the asset's name. If no name field is found in the data, the system will use the Primary ID as the name.
    The Name value must conform to the ThingsHub Name specification. This includes:

    1. The name must not be empty or only white spaces.

    2. The name can contain up to 255 characters.

  5. Custom Fields:
    All other keys in the JSON will be added as custom field values to the asset. However, please make sure that the Business Object Field is created in thingsHub beforehand.
    To learn in detail about Business Object Fields and how to manage them, please consult the official thingsHub documentation: Managing Fields

Setting a custom Primary ID and Name

If you want to use a custom primary ID and Name, you can also provide query parameters to explicitly specify the fields in the JSON to use as the ID and the name.
The relevant query parameters are:

  1. id_mapping_field → The json key to use as the ID

  2. name_mapping_field → The json key to use as the name

e.g. If the asset data contains a vin field as the ID and car_description as the name, and you want to use these as the ID and the name, you should set id_mapping_field to vin and name_mapping_field to car_description

After you make sure the data fulfills the above requirements, you can send a POST request to the API endpoint /v4/assets-import with your JSON data array in the body to initiate the import.

Example Scenario 1
  • CODE 
    [
  {
    "id": "prod-123",
    "name": "Premium Coffee Beans, 1lb bag",
    "price": 12.99,
    "stock_quantity": 100
  },
  {
    "id": "prod-456",
    "name": "Organic Green Tea, 20 bags",
    "price": 8.50,
    "stock_quantity": 50
  }
]

  • Query Parameters:

    • not provided

  • Explanation:

    • The API will use the id field ("prod-123", "prod-456") as the unique ID for each asset, since the id_mapping_field query parameter is not provided.

    • The API will use the name field ("Premium Coffee Beans, 1lb bag", "Organic Green Tea, 20 bags") as the name for each asset, since the name_mapping_field query parameter is not provided.

Example Scenario 2 (Using custom id and name)
  • CODE 
    [
  {
    "product_code": "prod-123",
    "detailed_description": "Premium Coffee Beans, 1lb bag",
    "price": 12.99,
    "stock_quantity": 100
  },
  {
    "product_code": "prod-456",
    "detailed_description": "Organic Green Tea, 20 bags",
    "price": 8.50,
    "stock_quantity": 50
  }
]

  • Query Parameters:

    • id_mapping_field=product_code

    • name_mapping_field=detailed_description

  • Explanation:

    • The API will use the product_code field ("prod-123", "prod-456") as the unique ID for each asset.

    • The API will use the detailed_description field ("Premium Coffee Beans, 1lb bag", "Organic Green Tea, 20 bags") as the name for each asset.

Import Validation

ThingsHub first performs validation on a few record samples of the import, and will start the import only if these sample entries fulfill the following criteria:

  • The entries must be valid UTF-8 JSON.

  • The entries must not contain any system field keys. The list of system fields for assets can be found in the Business Objects management section of the Tenant Settings: Managing Fields | Viewing-Field-Information

  • The custom field must not have values that do not match the type, e.g. you can’t have a Text character as a value for a Number field.
    e.g. "Operator_Count": "abcd" is not allowed if Operator_Count is a Number field.
    However, "Operator_Count": "13" is still allowed as the string 13 represents a valid number.

  • The data array must contain at least 1 element.

  • The ID and Name of the entries must comply with ThingsHub ID and Name standards.

  • The data array must not contain more than 50,000 records.

The import process will start only if the samples fulfill this validation.

Once started, the import status can be checked by using the corresponding GET api/v4/assets-import endpoint.

The import creates a new asset, or updates the existing assets if the id already exists. It never deletes any assets.

Checking the Import Progress

Import Status

The GET v4/api/assets-import endpoint can be used to get the current status of the import.

image-20250304-074853.png

The asset import status endpoint

The response will include:

  • config: The keys that are used for the asset ID and name.

  • status: The import status (NOT_STARTED, RUNNING or COMPLETED).

  • stats: The Aggregate counts of records whose imports were successful, in-progress, failed, or caused a warning.

  • import_duration: This field is only present for completed imports, and is the total time it took for the import to complete.

  • import_started_at and import_ended_at for the start and end times of the import.

Example response:

CODE 
{
  "config": {
    "id_mapping_field": "mynewid",
    "name_mapping_field": "mynewid"
  },
  "import_duration": "1.144891s",
  "import_ended_at": "2025-03-04T03:21:44.846Z",
  "import_id": 94,
  "import_started_at": "2025-03-04T03:21:43.701Z",
  "resource": "assets",
  "stats": {
    "failed_count": 2,
    "in_progress_count": 3,
    "success_count": 10,
    "total_count": 15,
    "warning_count": 5
  },
  "status": "COMPLETED"
}

Full Import Detail

With the full report endpoint, you can drill down into the status of the exact import entry, identify and resolve warnings and errors with the import.

Use the /assets-import/full-report endpoint for a detailed, paginated report of each record's status. You can filter the records by the status, and also paginate through the report with the limit and page parameters.

image-20250304-075124.png

The full import report endpoint

Warnings

Warnings will occur in the following cases:

  1. If the entry contains a system field as a key.

  2. If the entry contains mismatched data types for custom fields.

If an entry has only warnings, the record will still be imported.
However, the keys in the record that caused the warnings will not be imported.

Errors/Failed

Errors occur when an entry fails to import. The report will show FAILED status and the corresponding error message as to why the import failed.

Example response

CODE 
{
  "collection": [
    {
      "entry_num": 1,
      "status": "SUCCESS"
    },
    {
      "entry_num": 2,
      "message": "mynewname: field with name: mynewname: not found",
      "status": "WARNING"
    },
    {
      "entry_num": 2,
      "status": "SUCCESS"
    },
    {
      "entry_num": 3,
      "status": "SUCCESS"
    },
    {
      "entry_num": 4,
      "message": "Tracker No.: Invalid value found for field 'Tracker No.' of type: 'Number': bad request",
      "status": "WARNING"
    },
    {
      "entry_num": 4,
      "status": "FAILED",
      "message": "Invalid ID found"
    },
    {
      "entry_num": 5,
      "status": "SUCCESS"
    }
  ],
  "count": 10,
  "page": 1,
  "total_count": 20,
  "total_pages": 2
}

Example Asset Import bodies

Example 1 (Warning and Error entries present in data)

  • size is a Number type field

  • is_available is a Checkbox type field

CODE 
[
  {
    "id": "asset-123", 
    "name": "Laptop",
    "brand": "Dell",
    "model": "XPS 13",
    "site_name": "Kathmandu" // Warning: 'site_name' is a system field
  },
  {
    "uid": "asset-456", 
    "name": "Monitor",
    "brand": "Samsung",
    "size": "large" // Warning: 'size' should be a number
  },
  {
    "id": "asset-789",
    "name": "Tablet",
    "operating_system": "Android",
    "is_available": "yes" // Warning: 'is_available' should be a boolean (true/false)
  },
  {
    "name": "Printer", // Failed: Missing ID
    "brand": "HP"
  },
  {
    "id": "Asset 101", // Failed: Invalid ID format (contains a space)
    "name": "Scanner"
  },
  {
    // Valid entry
    "id": "asset-112", 
    "name": "Keyboard",
    "brand": "Logitech",
    "connection_type": "wireless"
  },
  {
    // Valid entry
    "id": "asset-113", 
    "name": "Keyboard",
    "size": 17,
    "connection_type": "wireless"
  },
  {
    // Valid entry
    "id": "asset-114", 
    "name": "Mouse",
    "size": "12",               // '12', although a string, can be converted to a Number
    "connection_type": "wired",
    "is_available": "true"      // 'true' can be converted to a boolean
  }
]

Example 2 (Valid import body)

  • brandis custom field of the SingleLineText type.

CODE 
[
  {
    "id": "asset-001",
    "name": "Laptop 1",
    "brand": "Dell"
  },
  {
    "id": "asset-002",
    "name": "Monitor 1",
    "brand": "Samsung"
  },
  {
    "id": "asset-003",
    "name": "Keyboard 1",
    "brand": "Logitech"
  },
  {
    "id": "asset-004",
    "name": "Mouse 1",
    "brand": "HP"
  },
  {
    "id": "asset-005",
    "name": "Printer 1",
    "brand": "Canon"
  },
  {
    "id": "asset-006",
    "name": "Scanner 1",
    "brand": "Epson"
  },
  {
    "id": "asset-007",
    "name": "Tablet 1",
    "brand": "Apple"
  },
  {
    "id": "asset-008",
    "name": "Smartphone 1",
    "brand": "Samsung"
  },
  {
    "id": "asset-009",
    "name": "Desktop 1",
    "brand": "Lenovo"
  },
  {
    "id": "asset-010",
    "name": "Server 1",
    "brand": "Dell"
  },
  {
    "id": "asset-011",
    "name": "Router 1",
    "brand": "Cisco"
  },
  {
    "id": "asset-012",
    "name": "Switch 1",
    "brand": "Netgear"
  },
  {
    "id": "asset-013",
    "name": "Projector 1",
    "brand": "BenQ"
  }
]
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close