Skip to content

Entity references

Entities can be referenced in two ways.

Id reference

An id reference takes the form <entity type>!<entity id>. For example, signal!-C-ijvJcu2BUg8hfjsCe9WKG5YE references the signal entity with id -C-ijvJcu2BUg8hfjsCe9WKG5YE.

Note that an id must match the regex /^[-A-Za-z0-9][A-Za-z0-9_-]{15,63}$/.

Id references are suitable for machine-to-machine interactions and integrations. Id references are immutable.

Slug reference

Every entity will have an associated human-readable, unique identifier called a slug. It is automatically generated by the system.

Slugs are a more convenient way to reference entities for people. For example, the corresponding slug reference to signal!-C-ijvJcu2BUg8hfjsCe9WKG5YE is signal.toku-systems.t1000.tip000475.battery-voltage. The latter has more meaning and context compared to an id reference.

A slug references consists of an entity type, followed by a ., and one or more parts seperated by a ..

The number and order of the parts is determined by the entity type.

Note

Slug references are mutable. If you intend to use a slug reference in code, make sure it is unlikely to change or handle case if slug reference points to something else.

"Slugifying" parts

After splitting a string on the . character, each part is "slugified" by using the following procedure.

  1. Replace each non-alphanumeric character with a hyphen, -.
  2. Replace duplicate hyphens with a single hyphen.
  3. Remove leading and trailing hyphens.
  4. Lowercase the result.

Note that when specifying a slug reference, if you surround a part with double or single quotes, Illumass will slugify the part beforehand.

For example, signal."TOKU systems".t1000.tip000475."Battery voltage" will be first converted to signal.toku-systems.t1000.tip000475.battery-voltage.

Note that if you are using a slug reference with quotes in a URL, you will need to URL encode it first.

Entity slug parts

Below are the slug parts and order for each entity type.

Assets

  • asset.<tenant name>.<asset name>

Asset types

  • asset-type.<asset type name>

Countries

  • country.<ISO 3166-1 alpha-2 code>

Devices

  • device.<manufacturer name>.<device model name>.<device serial number>

Device models

  • device-model.<manufacturer name>.<device model name>

Device types

  • device-type.<device type name>

Hardpoints

  • hardpoint.<tenant name>.<asset name>.<hardpoint name>

Measurement types

  • measurement-type.<measurement type name>

Measuring units

  • measuring-unit.<measurement type name>.<measuring unit name>

Signals

  • signal.<manufacturer name>.<device model name>.<device serial number>.<signal name>
  • signal.<tenant name>.<asset name>.<hardpoint name>.<signal name>

Tenants

  • tenant.<tenant name>

Users

Only one of the following will work for each user. When Illumass generates the user slug, it will try each and use the first one that is unique.

  • user.<tenant name>.<user first name and last name>
  • user.<tenant name>.<part of user email before @ symbol>
  • user.<tenant name>.<email>