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
minVersion: 2.0.2

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

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
false

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

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
isPolymorphic: false

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

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
sortAscending: false

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
minVersion: 2.0.2

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

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
false

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

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
isPolymorphic: false