Skip to main content

Item Service Panel

The Item Service panel allows you visibility into your Schemas, NamedUserCollections and NamedFileCollections in your projects and provides convenient methods for interacting with the Item Service.

Project Commands#

Create New Collection#

Creates either a new NamedUserCollection NamedTelemetryCollection , or NamedFileCollection based on the user's choice.

After clicking 'Create New Collection':

  1. Select either 'NamedUserCollection', 'NamedTelemetryCollection', or 'NamedFileCollection'
  2. Enter the prompted information to create the item
    • if NamedUserCollection, enter name, description, shortName, _userType, and set optional encryption
    • if NamedTelemetryCollection, enter name, description, shortName, _userType, the reading granularity and optionally a reading expiry in seconds
    • if NamedFileCollection select a parent container, then enter name, description, and shortName

After the collection has been created document will open with the collection information.

Schema Folder Commands#

View Schema#

Opens a visual graph view of the Project's schema.

By default the Schema View will hide any collections without _itemTypes defined. You can view all the collections in th graph using the toggle in the left panel of the view.

View Schema JSON#

Opens a JSON document containing the Item Service Schema.

Included in the document will be a list of the Collections as reference for Item Type to Collection relations.

Item Types Folder Commands#

Create Item Type#

Creates a new Item Type in your Item Service schema when given a name and the type definition. The default 'base' type definiton is displayed and can be edited prior to saving the type. A schema may also be generated and modified by selecting a representative sample item from a collection.

Note: Item Type names must be unique.

Creating an Item Type using a Sample Item

  1. Select Create Item Type by right clicking the Item Types folder in the Item Service panel or by right clicking the background in the Visual Schema View
  2. Give the new Item Type a name
  3. Select a collection in the 'Create ItemType from existing collection' dropdown
  4. If the collection contains items, then a random item will be chosen and displayed in the Sample Item tab
    • The Sample Item tab displays the current item index and the total number of items in the collection
    • Clicking the refresh button will select another random item from the collection
    • Clicking the Create Schema button will use the current Sample Item to generate an Item type schema
    • Clicking the clear button will clear the Sample Item and collection
  5. Make any further updates to the schema
  6. Click Save
  7. Since you have a collection selected and created the schema based on an item, you will be prompted if you would like to automatically associate the newly created Item Type schema to the collection

Note: When generating the schema, property types are inferred from the values in the sample item. The generated schema is not perfect and cannot account for properties in the schema that should be defined as 'enums'. These will be generated as 'string' types. It remains up to you to further enhance the generated schema to add the 'enum' data.

Item Type Commands#

Commit Changes#

Commits your local changes to an Item Type to the Item Service Schema. This will also close and delete your local copy of the Item Type.

Note: Changing the _typeName is not supported when editing Item Types. If you change the Item Type _typeName and attempt to commit the change, you will be warned that the _typeName will be set back to it's original value.

Delete Item Type#

The Delete command is available in both the Item Service panel and the Visual Schema View by right clicking on an Item type.

Deletes the Item Type from your schema in the Item Service, and removes any references to the Item Type on Collections and other Item Types.

Discard Changes#

Discards any changes you have made to the Item Type JSON file and removes it from your local disk.

The Discard Changes command is only available when a change has been made.

Manage Reading Types#

Allows you to assign and unassign Reading Types to your Item Types and update your schema in the Item Service.

This command is only available when the Item Type is not local (must have the cloud icon in the tree).

Open#

The Open command is available in both the Item Service panel and the Visual Schema View by right clicking on an Item type.

Opens the Item Type object, from the Item Service schema, in a JSON document for editing.

The Item Type's icon in the Item Service panel will update to show that it has been opened locally. When modified, the icon will update to indicate changes have been made since it was opened.

Reading Types Folder Commands#

Create Reading Type#

Creates a new Reading Type in your Item Service schema when given a name and the type definition. The default 'base' type definiton is displayed and can be edited prior to saving the type.

Note: Reading Type names must be unique.

Creating an Reading Type using a Sample Reading

  1. Select Create Reading Type by right clicking the Reading Types folder in the Item Service panel or by right clicking the background in the Visual Schema View
  2. Give the new Reading Type a name
  3. Select a telemetry collection in the 'Create Reading type from existing item' dropdown
  4. If the collection contains readings, then a random reading will be chosen and displayed in the Sample Reading tab
    • The Sample Reading tab displays the current reading index and the total number of readings in the collection
    • Clicking the refresh button will select another random reading from the collection
    • Clicking the Create Schema button will use the current Sample Reading to generate an Reading type schema
    • Clicking the clear button will clear the Sample Reading and collection
  5. Make any further updates to the schema
  6. Click Save
  7. Since you have a collection selected and created the schema based on a reading, you will be prompted if you would like to automatically associate the newly created Reading Type schema to the Item types associated to the telemetry collection

Note: When generating the schema, property types are inferred from the values in the sample item. The generated schema is not perfect and cannot account for properties in the schema that should be defined as 'enums'. These will be generated as 'string' types. It remains up to you to further enhance the generated schema to add the 'enum' data.

Reading Type Commands#

Commit Changes#

Commits your local changes to an Reading Type to the Item Service Schema. This will also close and delete your local copy of the Reading Type.

Note: Changing the _typeName is not supported when editing Reading Types. If you change the Reading Type _typeName and attempt to commit the change, you will be warned that the _typeName will be set back to it's original value.

Delete Reading Type#

The Delete command is available in both the Item Service panel and the Visual Schema View by right clicking on a Reading type.

Deletes the Reading Type from your schema in the Item Service, and removes any references to the Reading Type on Collections and other Item Types.

Discard Changes#

Discards any changes you have made to the Item Type JSON file and removes it from your local disk.

The Discard Changes command is only available when a change has been made.

Open#

The Open command is available in both the Item Service panel and the Visual Schema View by right clicking on a Reading type.

Opens the Reading Type object, from the Item Service schema, in a JSON document for editing.

The Reading Type's icon in the Item Service panel will update to show that it has been opened locally. When modified, the icon will update to indicate changes have been made since it was opened.

Collections Folder Commands#

Create Collection#

Creates a new NamedUserCollection, NamedTelemetryCollection, or NamedFileCollection in the project.

After the collection has been created a document will open with the collection information.

Collection Commands#

Delete Collection#

Deletes a selected NamedUserCollection.

Delete and Recreate Collection#

Deletes the selected collections and creates it with the same name, description, shortName, and _userType.

This deletes the contents of the collection as well.

After the collection has been recreated a document will open with the collection information.

Get Newest 15 Items#

Get Newest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedUserCollection
  3. The _total count of all items in the NamedUserCollection
  4. The _list of 15 newest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Get Oldest 15 Items#

Get Oldest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedUserCollection
  3. The _total count of all items in the NamedUserCollection
  4. The _list of 15 oldest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Import Items#

Imports items into the latest version of the selected NamedUserCollection or NamedTelemetryCollection from an xlsx file. See the required xlsx format below.

NamedFileCollections are not yet supported for importing items due to required data consistency requirements between the Item and File Service.

To import items:

  1. Right click on the collection to which you want to import items
  2. Select the Import Items menu option
  3. In the Import Items form, click the Browse button and select an xlsx file containing the item information to be imported
  4. If the xlsx contains multiple sheets, you may select a sheet
  5. If the collection has associated item types, you may select the item type for the imported items
  6. A preview of an imported item will be displayed, the refresh icon can be clicked to view a different random item
  7. Click Import to import the items

Note: If many items are being imported this could be a long running operation. Do not close the import form or the IDE while the import is taking place.

xlsx import format#

The import format is designed for simplicity and may not cover all types of item imports.

Download a sample Item Import xlsx file

Header rows The first row (and only the first row) in any sheet should define the item properties on the imported item. The import process supports dot notation in the property names, so you can create nested objects on the final imported item.

Item Rows All rows after the first row represent items to be imported with the columns containing the property values for the item. Be sure to correctly format all cell value types in the xlsx so that their types can be correctly inferred on import.

A note about dates: Excel stores dates as a non-human readble number, though they appear in Excel formatted as you configure. When importing the contents of a cell formatted as a date, the imported property will reflect the human readable text of the date. For all date properties, a new property will be added with the same name appended with _iso containing the ISO date string of the date.

Example xlsx Sheet

firstnamelastnameaddress.street.street1address.street.street2address.city
RichardStark555 South St.Apartment 3Springfield

The xlsx above would import to an item like this:

{   "firstname": "Richard",   "lastname": "Stark",   "address": {      "street": {         "street1": "555 South St.",         "street2": "Apartment 3"      },      "city": "Springfield"   }}

Manage Item Types#

Allows you to assign and unassign _itemTypes to your collections and update your schema in the Item Service.

Relate Items#

The Relate Items command allows for creating relationships between items int he selected collection and the items in one other collection. the two collections must be different. Creating relations betwen items in the same collection is not supported.

To relate items:

  1. Right click on the collection in the Item Service Panel containing the items you wish to be the parent items in the relations you will create
  2. Select 'Relate Items'
  3. In the Relate Items form, select the collection containing the items which will be the child relations
  4. In the Map By section, select the parent item property whose value will be used to match with child items
    • You can inspect sample parent item properties in the Sample Parent Item tab
  5. In the Map By section, select the child item property whose value will be matched with the parent item property
    • You can inspect sample child item properties in the Sample Child Item tab
  6. Click the Relate button

Creating relations may be a long running operation. To ensure all relations are created, do not close the form while the command is running.

Telemetry Collections Folder Commands#

Create New NamedTelemetryCollection#

Creates a new NamedTelemetryCollection in the project given a name, description, shortName, _userType, reading granularity, and optional reading expiry.

After the collection has been created a document will open with the collection information.

Telemetry Collection Commands#

Delete Collection#

Deletes a selected collection.

Delete and Recreate Collection#

Deletes the selected collections and creates it with the same name, description, shortName, and _userType.

This deletes the contents of the collection as well.

After the collection has been recreated a document will open with the collection information.

Get Latest 15 Readings#

Get the latest 15 readings added to the telemetry items. Will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedTelemetryCollection
  3. The _total count of all readings in the NamedTelemetryCollection
  4. The _list of 15 newest readings
  5. The _pageSize of the returned list of readings
  6. The _offset of the returned list of readings

Get Newest 15 Items#

Get Newest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedTelemetryCollection
  3. The _total count of all items in the NamedTelemetryCollection
  4. The _list of 15 newest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Get Oldest 15 Items#

Get Oldest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedTelemetryCollection
  3. The _total count of all items in the NamedTelemetryCollection
  4. The _list of 15 oldest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Import Items#

Imports items into the latest version of the selected NamedUserCollection or NamedTelemetryCollection from an xlsx file. See the required xlsx format below.

NamedFileCollections are not yet supported for importing items due to required data consistency requirements between the Item and File Service.

To import items:

  1. Right click on the collection to which you want to import items
  2. Select the Import Items menu option
  3. In the Import Items form, click the Browse button and select an xlsx file containing the item information to be imported
  4. If the xlsx contains multiple sheets, you may select a sheet
  5. If the collection has associated item types, you may select the item type for the imported items
  6. A preview of an imported item will be displayed, the refresh icon can be clicked to view a different random item
  7. Click Import to import the items

Note: If many items are being imported this could be a long running operation. Do not close the import form or the IDE while the import is taking place.

xlsx import format#

The import format is designed for simplicity and may not cover all types of item imports.

Download a sample Item Import xlsx file

Header rows The first row (and only the first row) in any sheet should define the item properties on the imported item. The import process supports dot notation in the property names, so you can created nested objects on the final imported item.

All items imported to a telemetry collection must have a _sourceId property. This will be used to match readings to the telemetry item.

Item Rows All rows after the first row represent items to be imported with the columns containing the property values for the item. Be sure to correctly format all cell value types in the xlsx so that their types can be correctly inferred on import.

A note about dates: Excel stores dates as a non-human readble number, though they appear in Excel formatted as you configure. When importing the contents of a cell formatted as a date, the imported property will reflect the human readable text of the date. For all date properties, a new property will be added with the same name appended with _iso containing the ISO date string of the date.

Example xlsx Sheet

sourceIdspacemanufacturer
OCC-000012002Lutron

The xlsx above would import to an item like this:

{   "_sourceId_": "OCC-00001",   "space": 2002,   "manufacturer": "Lutron   }}

Import Readings#

Imports readings into the latest version of the selected NamedTelemetryCollection from an xlsx file. See the required xlsx format below.

To import readings:

  1. Right click on the collection to which you want to import readings
  2. Select the Import Readings menu option
  3. In the Import Readings form, click the Browse button and select an xlsx file containing the readings information to be imported
  4. If the xlsx contains multiple sheets, you may select a sheet
  5. If the collection has associated item types with reading types assigned, you may select the reading type for the imported readings
  6. A preview of an imported reading will be displayed, the refresh icon can be clicked to view a different random item
  7. Click Import to import the readings

Note: If many readings are being imported this could be a long running operation. Do not close the import form or the IDE while the import is taking place.

xlsx import format#

The import format is designed for simplicity and may not cover all types of reading imports.

Download a sample Item Import xlsx file

Header rows The first row (and only the first row) in any sheet should define the reading properties on the imported reading. The import process supports dot notation in the property names, so you can create nested objects on the final imported item.

All readings must include columns for a _ts and _tsMetadata._sourceId property. The _ts property must include an ISO datetime string for when the reading was captured. The _tsMetadata._sourceId must match a sourceId on a telemetry item.

Reading Rows All rows after the first row represent readings to be imported with the columns containing the property values for the item. Be sure to correctly format all cell value types in the xlsx so that their types can be correctly inferred on import.

A note about dates: Excel stores dates as a non-human readble number, though they appear in Excel formatted as you configure. When importing the contents of a cell formatted as a date, the imported property will reflect the human readable text of the date. For all date properties, a new property will be added with the same name appended with _iso containing the ISO date string of the date.

Example xlsx Sheet

_ts_tsMetadat._sourceIdpeople_count
2026-03-02T14:40:00-05:00OCC-0000110

The xlsx above would import to a reading like this:

{   "_ts_": "2026-03-02T14:40:00-05:00",   "people_count": 10,   "_tsMetadata": {      "_sourceId": "OCC-00001",      "_telItemId": "<twinit item id>"   }}

Manage Item Types#

Allows you to assign and unassign _itemTypes to your collections and update your schema in the Item Service.

Relate Items#

The Relate Items command allows for creating relationships between items int he selected collection and the items in one other collection. the two collections must be different. Creating relations betwen items in the same collection is not supported.

To relate items:

  1. Right click on the collection in the Item Service Panel containing the items you wish to be the parent items in the relations you will create
  2. Select 'Relate Items'
  3. In the Relate Items form, select the collection containing the items which will be the child relations
  4. In the Map By section, select the parent item property whose value will be used to match with child items
    • You can inspect sample parent item properties in the Sample Parent Item tab
  5. In the Map By section, select the child item property whose value will be matched with the parent item property
    • You can inspect sample child item properties in the Sample Child Item tab
  6. Click the Relate button

Creating relations may be a long running operation. To ensure all relations are created, do not close the form while the command is running.

File Collections Folder Commands#

Create New NamedFileCollection#

Creates a new NamedFileCollection allowing for selecting a parent container and given a name, description, and shortName.

After the collection has been created a document will open with the collection information.

File Collection Commands#

Delete Collection#

Deletes a selected NamedFileCollection.

Get Newest 15 Items#

Get Newest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedUserCollection
  3. The _total count of all items in the NamedUserCollection
  4. The _list of 15 newest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Get Oldest 15 Items#

Get Oldest 15 Items will open a new JSON document containing:

  1. The name of the collection which was peeked at
  2. The NamedUserItem for the NamedUserCollection
  3. The _total count of all items in the NamedUserCollection
  4. The _list of 15 oldest items
  5. The _pageSize of the returned list of items
  6. The _offset of the returned list of items

Relate Items#

The Relate Items command allows for creating relationships between items int he selected collection and the items in one other collection. the two collections must be different. Creating relations betwen items in the same collection is not supported.

To relate items:

  1. Right click on the collection in the Item Service Panel containing the items you wish to be the parent items in the relations you will create
  2. Select 'Relate Items'
  3. In the Relate Items form, select the collection containing the items which will be the child relations
  4. In the Map By section, select the parent item property whose value will be used to match with child items
    • You can inspect sample parent item properties in the Sample Parent Item tab
  5. In the Map By section, select the child item property whose value will be matched with the parent item property
    • You can inspect sample child item properties in the Sample Child Item tab
  6. Click the Relate button

Creating relations may be a long running operation. To ensure all relations are created, do not close the form while the command is running.