Sorting rule

TypeScript type: SortingRule.

Sorting rules provide a way to either disable sorting or sort instances by specific properties. There are 2 types of sorting rules for both of these scenarios.

Property sorting rule

Rule to configure sorting for certain ECInstances in the hierarchy and/or content. It is possible to configure different sorting for different types of ECInstances.

Multiple sorting rules may be applied for the same instances - in this case the instances are first sorted by the highest priority rule and then the lower priority ones.

Note: This rule is not meant to be used to sort grouping nodes, custom nodes or other non ECInstance type of nodes.

Attributes

Name Required? Type Default
Filtering
requiredSchemas No RequiredSchemaSpecification[] []
priority No number 1000
condition No ECExpression ""
class No SingleSchemaClassSpecification All classes in current context
isPolymorphic No boolean false
Sorting
propertyName Yes string
sortAscending No boolean true

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 `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there is a customization rule to sort
// instances by `Pitch` property. Sorting rule requires `BisCore` schema to be higher than 1.0.2.
// If this requirement is not met sorting rule does not take effect.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
    propertyName: "Pitch",
  }],
};
Result
minVersion: 1.0.2 Example of using required schemas condition
minVersion: 2.0.2 Example of using required schemas condition

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.

Type number
Is Required No
Default Value 1000
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are two customization rules to sort
// instances by `Roll` and `Pitch` properties. 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: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    priority: 1,
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    propertyName: "Roll",
  }, {
    ruleType: "PropertySorting",
    priority: 2,
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    propertyName: "Pitch",
  }],
};

Example of using priority attribute

Attribute: condition

Defines a condition which needs to be met in order for the rule to be used. The condition is an ECExpression which has to evaluate to a boolean value.

Type ECExpression
Is Required No
Default Value ""
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances by `Pitch` property.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    condition: "TRUE",
    propertyName: "Pitch",
  }],
};
Condition evaluation result Result
true Example of using rule condition
false Example of using rule condition

Attribute: class

Specifies ECClass whose ECInstances should be sorted.

Type SingleSchemaClassSpecification
Is Required No
Default value All classes in current context
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// `bis.SpatialViewDefinition` instances by `Pitch` property
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    propertyName: "Pitch",
  }],
};

Example of using class attribute

Attribute: isPolymorphic

Specifies that class attribute defined in this rule should be handled polymorphically.

Type boolean
Is Required No
Default Value false
// This ruleset lists `bis.SpatialViewDefinition` instances with their `Roll` and `Pitch` properties as instance
// labels. Sorting rule targets `bis.ViewDefinition3d`, the base class of `bis.SpatialViewDefinition`, so to
// sort instances of the derived classes, `isPolymorphic` attribute needs to be `true`.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    class: { schemaName: "BisCore", className: "ViewDefinition3d" },
    isPolymorphic: true,
    propertyName: "Pitch",
  }],
};
Result
isPolymorphic: true Example of using isPolymorphic attribute
isPolymorphic: false Example of using isPolymorphic attribute

Attribute: propertyName

Specifies name of the property which should be used for sorting.

Type string
Is Required Yes
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances of any class by `Pitch` property.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    propertyName: "Pitch",
  }],
};

Example of using propertyName attribute

Attribute: sortAscending

Specifies whether instances should be sorted in ascending order or descending.

Type boolean
Is Required No
Default Value true
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are customization rule to sort
// instances by `Pitch` property in descending order
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    propertyName: "Pitch",
    sortAscending: false,
  }],
};
Result
sortAscending: true Example of using isPolymorphic attribute
sortAscending: false Example of using isPolymorphic attribute

Disabled sorting rule

Rule to disable sorting for certain ECInstances in the hierarchy and/or content.

Note: Disabling sorting increases performance

Attributes

Name Required? Type Default
Filtering
requiredSchemas No RequiredSchemaSpecification[] []
priority No number 1000
condition No ECExpression ""
class No SingleSchemaClassSpecification All classes in current context
isPolymorphic No boolean false

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 `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there is a customization rule to sort
// instances by `Pitch` property. Sorting rule requires `BisCore` schema to be higher than 1.0.2.
// If this requirement is not met sorting rule does not take effect.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    requiredSchemas: [{ name: "BisCore", minVersion: "1.0.2" }],
    propertyName: "Pitch",
  }],
};
Result
minVersion: 1.0.2 Example of using required schemas condition
minVersion: 2.0.2 Example of using required schemas condition

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.

Type number
Is Required No
Default Value 1000
// The ruleset has root node rule that returns `bis.SpatialViewDefinition` instances with labels
// consisting of `Roll` and `Pitch` property values. Also there are two customization rules to sort
// instances by `Roll` property and to disable `bis.SpatialViewDefinition` instances sorting.
// The disabled sorting rule has higher priority and it is handled first.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["SpatialViewDefinition"] },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " x ",
      parts: [
        { spec: { specType: "Property", propertyName: "Roll" } },
        { spec: { specType: "Property", propertyName: "Pitch" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    priority: 1,
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
    propertyName: "Pitch",
  }, {
    ruleType: "DisabledSorting",
    priority: 2,
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
  }],
};

Example of using priority attribute

Attribute: condition

Defines a condition which needs to be met in order for the rule to be used. The condition is an ECExpression which has to evaluate to a boolean value.

Type ECExpression
Is Required No
Default Value ""
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of `CodeValue` property value. Also there are customization rule to disable
// instances sorting.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "ViewDefinition" },
    values: [{
      specType: "Property",
      propertyName: "CodeValue",
    }],
  }, {
    ruleType: "DisabledSorting",
    condition: "TRUE",
  }],
};
Condition evaluation result Result
true Example of using rule condition
false Example of using rule condition

Attribute: class

Specifies ECClass whose instances should not be sorted.

Type SingleSchemaClassSpecification
Is Required No
Default value All classes in current context
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of class name and `CodeValue` property value. Also there two are customization rules to sort
// instances by `CodeValue` property and to disable `bis.SpatialViewDefinition` instances sorting.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "ViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " - ",
      parts: [
        { spec: { specType: "ClassName" } },
        { spec: { specType: "Property", propertyName: "CodeValue" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    priority: 1,
    class: { schemaName: "BisCore", className: "ViewDefinition" },
    propertyName: "CodeValue",
    isPolymorphic: true,
  }, {
    ruleType: "DisabledSorting",
    priority: 2,
    class: { schemaName: "BisCore", className: "SpatialViewDefinition" },
  }],
};

Example of using class attribute

Attribute: isPolymorphic

Specifies that class attribute defined in this rule should be handled polymorphically.

Type boolean
Is Required No
Default Value false
// The ruleset has root node rule that returns `bis.ViewDefinition` instances with labels
// consisting of class name and `CodeValue` property value. Also there are two customization rules to sort
// instances by `CodeValue` property and to disable `bis.ViewDefinition2d` instances sorting polymorphically.
const ruleset: Ruleset = {
  id: "example",
  rules: [{
    ruleType: "RootNodes",
    specifications: [{
      specType: "InstanceNodesOfSpecificClasses",
      classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
      groupByClass: false,
      groupByLabel: false,
    }],
  }, {
    ruleType: "InstanceLabelOverride",
    class: { schemaName: "BisCore", className: "ViewDefinition" },
    values: [{
      specType: "Composite",
      separator: " - ",
      parts: [
        { spec: { specType: "ClassName" } },
        { spec: { specType: "Property", propertyName: "CodeValue" } },
      ],
    }],
  }, {
    ruleType: "PropertySorting",
    priority: 1,
    class: { schemaName: "BisCore", className: "ViewDefinition" },
    propertyName: "CodeValue",
    isPolymorphic: true,
  }, {
    ruleType: "DisabledSorting",
    priority: 2,
    class: { schemaName: "BisCore", className: "ViewDefinition2d" },
    isPolymorphic: true,
  }],
};
Result
isPolymorphic: true Example of using isPolymorphic attribute
isPolymorphic: false Example of using isPolymorphic attribute

Last Updated: 24 January, 2023