Defining a Custom Field

Suggest Edits

🚧

Beta

This is a beta version and subject to change without notice. Pricing, terms, conditions and availability may change in the final version.

To define a custom field, you need to add a customFieldDefinitions array to your iris app manifest:

  customFieldDefinitions: [
    {
      type: 'STRING',
      entityType: 'ASSET',
      key: 'myKey',
      title: 'String Field',
      uiEditable: true,
      uiVisible: true,
      scopeType: ScopeType.ACCOUNT
    }
  ]

  1. type defines the custom field type (see below for all options).

  2. entityType defines what type of entity a custom field can be used on. The following types are available:

  • ACCOUNT
  • ASSET
  • GROUP
  • SITE

  1. key defines the programmatic name of the field and cannot be changed after it has been created.

  2. title defines the UI visible name of the field.

  3. uiEditable / uiVisible controls how the field will be shown in the Manager UI. This does not limit how the field is used inside the Iris App.

  4. scopeType controls who can access the field values. Default is only within the users account.

Apart from the these standard properties, some field types have extra properties defined below.

All custom fields defined by an Iris App will be owned by the Iris App, and the Iris App developer should consider existing data when changing field definitions.

Custom field types

Field typeDescriptionExtra properties
BOOLEANBoolean value that can store true or false.
DATEDate stored in ISO8601 format.
DROPDOWNA predefined list of options. Supports both single and multi selects.allValues, multiSelect, dropDownValueReplacements
EMAILEmail field. Will be rendered with a mailto link in the UI.
NUMBERNumeric valuesminimum, maximum, isInteger
PHONE_NUMBERPhone number stored in E.164 format. Validated using Google libphonenumber.
STRINGFree text fieldminimumLength, maximumLength, pattern
WEB_ADDRESSWeb address. Will be shown as a link to open a new window in the UI.
JSONJSON values.
MONETARYMonetary values with currency in ISO 4217 standard.minimum, maximum

Scope types

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)
GLOBALValues with global scope will be shared between all accounts with access to the entity

Type specific properties

PropertyField typeRequiredDescription
maximumNUMBERNoMaximum numeric value
minimumNUMBERNoMinimum numeric value
unitSiNUMBERNoUnit used for users using SI Customary system of measurement
unitUsNUMBERNoUnit used for users using US Customary system of measurement
isIntegerNUMBERNoDisallow decimal values. Can't be true if unitSi or unitUs is specified
maximumLengthSTRINGNoMaximum length of the text
minimumLengthSTRINGNoMinimum length of the text
patternSTRINGNoThe allowed regular expression. Syntax is documented here.
allValuesDROPDOWNYesAll allowed values
multiSelectDROPDOWNNoAllow multiple options to be selected. Default false
valueReplacementsDROPDOWNNoMap from old values no longer allowed to new values. Used for updating existing data
currencyMONETARYyesCurrency in ISO 4217 standard

📘

Nice to know

All custom fields defined by an app will be owned by the app, and the app developer should consider existing data when changing field definitions.

Updated 2 months ago