Models

Models allow you to digitally represent real world assets.

Model Types

Model

{
  organizationId: string,
  id: string,
  name: string,
  createdUtc: datetime,
  updatedUtc: datetime,
  properties: Record<string, Property>
}

caution

Some functions such as getModel() have an optional includeProperties parameter which means properties will be null when false.

CreateModelOptions

{
  name: string,
  attributes: Record<string, string>,
  properties: CreatePropertyOptions[]
}

UpdateModelOptions

{
  name: string,
  attributes: Record<string, string>,
  properties: UpdatePropertyOptions[]
}

ModelQueryOptions

{
  modelIds: string[],
  attributes: Record<string, string>,
  searchFilter: string,
  includeProperties: boolean
}

createModel

Read-only Mode

This function is not available in read-only mode.

Creates a new empty Model or with properties.

createModel(modelId, options)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
options	CreateModelOptions	Options to create the Model with.

Returns The created Model.

Example

// Create a Model without properties
var cnc1 = createModel('cnc-1', {
  name: 'CNC 1'
});

// Create a Model with attributes.
var cnc2 = createModel('cnc-1', {
  name: 'CNC 2',
  attributes: {
    type: 'cnc'
  }
});

// Create a Model with properties
var cnc3 = createModel('cnc-2', {
  name: 'CNC 3',
  properties: [
    {
      id: 'active',
      name: 'Active',
      value: false,
      valueType: PropertyValueType.Boolean
    },
    {
      id: 'speed',
      name: 'Speed',
      value: 0,
      valueType: PropertyValueType.Number
    }
  ]
});

tip

A Model created without attributes or properties can always have them added later.

updateModel

Read-only Mode

This function is not available in read-only mode.

Updates an existing Model and its properties.

updateModel(modelId, options, includeProperties = true)

Parameters

Name	Type	Description	Default
modelId	string	The identifier of the Model to update.
options	UpdateModelOptions	Options to update the Model with.
includeProperties	boolean	Properties to added to the Model.	true

Returns The updated model.

Example

// Update the CNC to be active
var updated = updateModel('cnc-1', {
  properties: [
    {
      id: 'active',
      value: true
    }
  ]
});

deleteModel

Read-only Mode

This function is not available in read-only mode.

Delete a Model and its properties.

deleteModel(modelId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model to delete.

Example

deleteModel('cnc-2');

danger

This performs a hard delete and will not be recoverable afterwards. Delete with caution.

modelExists

Checks whether a Model with an identifier exists.

modelExists(modelId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model to check.

Returns A boolean on whether the Model exists.

Example

var exists = modelExists('refrigeration-unit');

if (exists) {
  // The refrigeration unit Model exists
}

getModel

Gets a Model by its identifier.

getModel(modelId, includeProperties = true)

Parameters

Name	Type	Description	Default
modelId	string	The identifier of the Model to retrieve.
includeProperties	boolean	Whether or not to return the Model properties.	true

Returns The Model with the specified modelId identifier.

Examples

Include properties

var model = getModel('hvac-building1');

// Check if the HVAC system is active and if there is a possible
// clog/issue with the condensation pan
if (model.properties['active'].value
  && model.properties['pan-alarm-active'].value) {
  // Integrate with an external system
}

Exclude properties

var model = getModel('hvac-building2', false);

getModels

Gets a collection of Models.

getModels(options)

Parameters

Name	Type	Description
options	ModelQueryOptions	Options for querying Models.

Returns A map of Models which meets the query criteria.

Example

// Query models using identifiers
var models = getModels({
  modelIds: ['hvac-building1', 'hvac-building2']
});

for (var propertyId in models['hvac-building1'].properties) {
  // Iterate over hvac-building1 properties
}

// Query models with a name search filter and attributes
var models = getModels({
  searchFilter: 'panel',
  attributes: {
    type: 'control'
  }
});

// Exclude loading properties when getting models
var models = getModels({
  modelIds: ['hvac-building1', 'hvac-building2'],
  includeProperties: false
});

Properties

Properties define the details of a Model and are used to track the current state of a Model.

Property Types

Property

{
  organizationId: string,
  modelId: string,
  id: string,
  name: string,
  value: string | float | boolean,
  valueType: PropertyValueType,
  scope: PropertyScope,
  timeSeries: boolean,
  createdUtc: datetime,
  changedUtc: datetime,
  updatedUtc: datetime
}

note

The data type of value will differ depending on the property's valueType.

CreatePropertyOptions

{
  id: string,
  name: string,
  value: string | float | boolean,
  valueType: PropertyValueType,
  scope: PropertyScope,
  timeSeries: boolean
}

UpdatePropertyOptions

{
  id: string,
  name: string,
  value: string | float | boolean,
  timeSeries: boolean
}

PropertyValueType

{
  Text = 0,
  Number = 1,
  Boolean = 2
}

PropertyScope

{
  Local = 0,
  System = 1,
  Template = 2
}

addProperty

Read-only Mode

This function is not available in read-only mode.

Adds a new property to a Model.

addProperty(modelId, options)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
options	CreatePropertyOptions	Options to create a new property with.

Returns The property which was added to the Model.

Example

var property = addProperty('control-panel', {
  id: 'status',
  value: 0,
  valueType: PropertyValueType.Number
});

addProperties

Read-only Mode

This function is not available in read-only mode.

Add one or more new properties to a Model.

addProperties(modelId, [options])

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
options	CreatePropertyOptions[]	Options to create new properties with.

Returns The properties which were added to the Model.

Example

var properties = addProperties('control-panel', [
  {
    id: 'active',
    value: true,
    valueType: PropertyValueType.Boolean
  },
  {
    id: 'status',
    value: 0,
    valueType: PropertyValueType.Number
  }
]);

updateProperty

Read-only Mode

This function is not available in read-only mode.

Updates an existing Model property.

updateProperty(modelId, propertyId, options)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
propertyId	string	The identifier of the property.
options	UpdatePropertyOptions	Options to update a property with.

Returns The updated property.

Example

var property = updateProperty('control-panel', 'status', {
  name: 'Control Status',
  value: 1
});

updateProperties

Read-only Mode

This function is not available in read-only mode.

Updates one or more existing Model properties.

updateProperties(modelId, [options])

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
options	UpdatePropertyOptions[]	Options to update a properties with.

Returns The updated properties.

Example

var properties = updateProperties('control-panel', [  
  {
    id: 'active',
    value: false
  },
  {
    id: 'status',
    value: 1
  }
]);

deleteProperty

Read-only Mode

This function is not available in read-only mode.

Delete a property from a Model.

deleteProperty(modelId, propertyId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
propertyId	string	The identifier of the property to delete.

Example

deleteProperty('cnc-2', 'speed');

danger

This performs a hard delete and will not be recoverable afterwards. Delete with caution.

deleteProperties

Read-only Mode

This function is not available in read-only mode.

Delete all properties for a Model.

deleteProperties(modelId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model to delete the properties from.

Example

deleteProperties('cnc-1');

danger

This performs a hard delete and will not be recoverable afterwards. Delete with caution.

propertyExists

Checks whether a property with an identifier exists on a Model.

propertyExists(modelId, propertyId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
propertyId	string	The identifier of the property to check.

Returns A boolean on whether the property exists on a Model.

Example

var exists = propertyExists('control-panel', 'manual-override');

if (exists) {
  // Check if the Model has override capabilities.
}

getProperty

Gets an individual property from a Model by its identifier.

getProperty(modelId, propertyId)

Parameters

Name	Type	Description
modelId	string	The identifier of the Model.
propertyId	string	The identifier of the property to retrieve.

Returns The property with the specified propertyId identifier.

Example

var property = getProperty('hvac-building1', 'air-filter-fault');

if (property.value != 0) {
  // Check if there is a fault with the air filter
}

getProperties

Gets all properties for a Model or specific properties using the specified identifiers.

getProperties(modelId, [propertyIds])

Parameters

Name	Type	Description	Optional
modelId	string	The identifier of the Model.	❌
propertyIds	string[]	The identifier of the properties to retrieve.	✔

Returns The properties with the specified propertyIds identifiers.

Examples

All Model properties

var properties = getProperties('control-panel');

for (var propertyId in properties) {
  // Iterate over properties
}

Collection of Model properties

var propertyIds = ['ahu-enabled', 'room1-occupancy'];
var properties = getProperties('control-panel', propertyIds);