Definitions

πŸ“˜

Subscription requirement

The Custom Fields API is only available to customers on the Evolve & Expand or the Lift & Leap subscription packages.

➑️

OpenAPI Specification for the Custom Fields API domain

Get the OpenAPI Specification (formerly Swagger), which is a standardized format that describes the functionalities, endpoints, parameters, and data models of this API in a JSON file here.

Create a field definition

To define a custom field, you first need to add a definition using the API.

Field typeDescription
BooleanBoolean value that can store true or false.
DateDate field.
DropdownA predefined list of options. Supports both single and multi selects.
E-mailEmail field. Will be rendered with a mailto link in the UI.
MonetaryMonetary values with currency in ISO 4217 standard.
NumberNumeric values. Supports unit conversion between metric and US customary units.
Phone numberPhone number. Validates the format according to country specific rules, but does not validate wheter the phone number actually exists.
Text stringFree text field. Supports limiting length.
Web addressWeb address. Will be shown as a link to open a new window in the UI.

It is possible to control if new fields should show up in appropriate places in the user interface or be an API only field using the uiVisible / uiEditable fields.

Once a definition has been created values can be set using the values API.

Field definition ownership

Custom field definitions can be owned by one of these:

  • Customer account - Customer defined fields will be owned by the customer account and require admin permission in that account to change.
  • Iris App - An app may contribute field definitions when it is installed
  • Trackunit - Trackunit defines a number of standard fields to aid interoperability.

When creating a definition using this API it will always be owned by your customer account. It is however possible to retrieve all 3 types using the API.

Data sharing

Regardless of who owns the definition of a field the values in a field may be shared between accounts.

Scope typeDescription
ACCOUNTValues with account scope will be shared within a single account
ACCOUNT_WRITE_GLOBAL_READUpdating values will be possible within a single account and visible to all accounts (read) with access to the entity.
GLOBALValues with global scope will be shared between all accounts with access to the entity

So that means that if you create a new field definition for an Asset and mark it as scope ACCOUNT_WRITE_GLOBAL_READ then you can add the field to an asset and you are allowed to update the value but in case you share it to other accounts they will only be able to see the value but not change it.

On the other hand if you select the ACCOUNT scope only users within your account will be able to see the values in that field.