Presentation › customization › Instance Label Override

Instance label override

TypeScript type: InstanceLabelOverride.

Instance label override rule provides a way to set instance label to one of its property values, other attributes and/or combination of them.

Attributes

Name	Required?	Type	Default
Filtering
`requiredSchemas`	No	`RequiredSchemaSpecification[]`	`[]`
`priority`	No	`number`	`1000`
`onlyIfNotHandled`	No	`boolean`	`false`
`class`	Yes	`SingleSchemaClassSpecification`
Overrides
`values`	Yes	`InstanceLabelOverrideValueSpecification[]`

Attribute: `requiredSchemas`

A list of ECSchema requirements that need to be met for the rule to be used.


Type	`RequiredSchemaSpecification[]`
Is Required	No
Default Value	`[]`

// The ruleset has root node rule that returns `Generic.PhysicalObject` instances and
// customization rule to override label using related `bis.ExternalSourceAspect` property.
// `bis.ExternalSourceAspect` ECClass was introduced in BisCore version 1.0.2, so the rule needs
// a `requiredSchemas` attribute to only use the rule if the version meets the requirement.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "Generic", classNames: ["PhysicalObject"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
      class: { schemaName: "Generic", className: "PhysicalObject" },
      values: [
        {
          specType: "Property",
          propertySource: {
            relationship: { schemaName: "BisCore", className: "ElementOwnsMultiAspects" },
            direction: "Forward",
            targetClass: { schemaName: "BisCore", className: "ExternalSourceAspect" },
          },
          propertyName: "Identifier",
        },
      ],
    },
  ],
};

Attribute: `priority`

Defines the order in which rules are handled - higher priority means the rule is handled first. If priorities are equal, the rules are handled in the order they're defined. The attribute may be especially useful when combined with onlyIfNotHandled attribute.


Type	`number`
Is Required	No
Default Value	`1000`

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and two
// customization rules to override labels. The rules have different priorities and
// higher priority rule is handled first.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      priority: 1000,
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "Model A",
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      priority: 2000,
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "Model B",
        },
      ],
    },
  ],
};

Example of using priority attribute

Attribute: `onlyIfNotHandled`

When true, the rule takes effect only when all other instance label overrides with higher priority are ruled out. This attribute is most useful for defining fallback rules.


Type	`boolean`
Is Required	No
Default Value	`false`

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and two
// customization rules to override label. The first label override rule has lower priority and
// `onlyIfNodeHandled` attribute, which allows it to be overriden by higher priority rules. Even
// if rule with higher priority does not provide value for label rule with lower priority is not used.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      priority: 1000,
      onlyIfNotHandled: true,
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "Model A",
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      priority: 2000,
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "",
        },
      ],
    },
  ],
};

Example of using onlyIfNotHandled attribute

Attribute: `class`

Specifies the ECClass to apply this rule to.


Type	`SingleSchemaClassSpecification`
Is Required	Yes

// The ruleset has root node rule that returns `bis.Model` instances.
// Also there is customization rule to override label only for `bis.GeometricModel3d` instances.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["Model"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "Geometric Model Node",
        },
      ],
    },
  ],
};

Example of using class attribute

Attribute: `values`

Specifications of values used to override label. The first non-empty value is used as the actual label. There are 8 types of supported value specifications:

Composite value specification
Property value specification
String value specification
Class name value specification
Class label value specification
BriefcaseId value specification
LocalId value specification
Related instance label value specification


Type	`InstanceLabelOverrideValueSpecification[]`
Is Required	Yes

Composite value specification

Specification allows creating a label value composited using multiple other specifications.

Name	Required?	Type	Default	Meaning
`parts`	Yes	`Array<{ spec: InstanceLabelOverrideValueSpecification; isRequired?: boolean }>`		Parts of the value. If any of the parts with `isRequired` flag evaluate to an empty string, the result of this specification is also an empty string.
`separator`	No	`string`	Space character	Separator to use when joining the parts.

// The ruleset has root node rule that returns `bis.GeometricElement3d` instances and
// customization rule to override instance label composed of string "ECClass" and instance ECClass name.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "Composite",
          separator: "-",
          parts: [{ spec: { specType: "String", value: "ECClass" } }, { spec: { specType: "ClassName" } }],
        },
      ],
    },
  ],
};

Example of using composite value specification

Property value specification

Specification uses property value as the label content.

Name	Required?	Type	Default	Meaning
`propertyName`	Yes	`string`		Name of the property whose value should be used.
`propertySource`	No	`RelationshipPathSpecification`	Empty path	Specification of the relationship path from `InstanceLabelOverride.class` to class of the property.

Two types of properties can be used to override label:

Direct instance properties.

// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances and
// customization rule to override instance label using `Pitch` property value.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
      values: [
        {
          specType: "Property",
          propertyName: "Pitch",
        },
      ],
    },
  ],
};

Example of using property value specification

Properties of related instance.

// The ruleset has root node rule that returns `meta.ECEnumerationDef` instances and
// customization rule to override instance label using `Alias` property value of
// `meta.ECSchemaDef` instance that is containing `meta.ECEnumerationDef` instance.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "ECDbMeta", classNames: ["ECEnumerationDef"] },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "ECDbMeta", className: "ECEnumerationDef" },
      values: [
        {
          specType: "Property",
          propertySource: {
            relationship: { schemaName: "ECDbMeta", className: "SchemaOwnsEnumerations" },
            direction: "Backward",
          },
          propertyName: "Alias",
        },
      ],
    },
  ],
};

Example of using related property value specification

String value specification

Specification uses the specified value as the label content.

Name	Required?	Type	Default	Meaning
`value`	Yes	`string`		The value to use as the label content.

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and
// customization rule to override label using string "Model Node".
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "String",
          value: "Model Node",
        },
      ],
    },
  ],
};

Example of using string value specification

Class name value specification

Specification uses ECClass name as the label content.

Name	Required?	Type	Default	Meaning
`full`	No	`boolean`	`false`	Should full (`{schemaName}.{className}`) class name be used.

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and
// customization rule to override instance label using full name of instance ECClass.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: true,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "ClassName",
          full: true,
        },
      ],
    },
  ],
};

	Result
`full: true`
`full: false`

Class label value specification

Specification uses ECClass display label as the label content. It has no additional attributes.

// The ruleset has root node rule that returns 'bis.GeometricModel3d' instances and
// customization rule to override instance label with instance class label.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "ClassLabel",
        },
      ],
    },
  ],
};

Example of using class label value specification

BriefcaseId value specification

Specification returns ECInstance's briefcase ID in base36 format. It has no additional attributes.

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and
// customization rule to override instance label with BriefcaseId value.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "BriefcaseId",
        },
      ],
    },
  ],
};

Example of using briefcaseId value specification

LocalId value specification

Specification returns ECInstance's local ID in base36 format. It has no additional attributes.

// The ruleset has root node rule that returns `bis.GeometricModel3d` instances and
// customization rule to override instance label with LocalId value.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["GeometricModel3d"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "BisCore", className: "GeometricModel3d" },
      values: [
        {
          specType: "LocalId",
        },
      ],
    },
  ],
};

Example of using localId value specification

Specification uses label of another related instance as the label content.

Name	Required?	Type	Default	Meaning
`pathToRelatedInstance`	Yes	`RelationshipPathSpecification`		Specification of the relationship path from `InstanceLabelOverride.class` to class of the related instance.

// The ruleset has root node rule that returns `Generic.PhysicalObject` instances and
// customization rule to override instance label with label of `bis.Model` instance
// containing `Generic.PhysicalObject` instance.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "Generic", classNames: ["PhysicalObject"], arePolymorphic: true },
          groupByClass: false,
          groupByLabel: false,
        },
      ],
    },
    {
      ruleType: "InstanceLabelOverride",
      class: { schemaName: "Generic", className: "PhysicalObject" },
      values: [
        {
          specType: "RelatedInstanceLabel",
          pathToRelatedInstance: {
            relationship: { schemaName: "BisCore", className: "ModelContainsElements" },
            direction: "Backward",
          },
        },
      ],
    },
  ],
};

Example of using related instance label value specification

Last Updated: 03 April, 2024

Found something wrong, missing, or unclear on this page? Raise an issue in our repo.