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",
        },
      ],
    },
  ],
};

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: "",
        },
      ],
    },
  ],
};

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",
        },
      ],
    },
  ],
};

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" } }],
        },
      ],
    },
  ],
};

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",
          },
        ],
      },
    ],
  };
  

  

• 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",
          },
        ],
      },
    ],
  };
  

  

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",
        },
      ],
    },
  ],
};

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",
        },
      ],
    },
  ],
};

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",
        },
      ],
    },
  ],
};

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",
        },
      ],
    },
  ],
};

Related instance label 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",
          },
        },
      ],
    },
  ],
};