Related instance specification
TypeScript type: RelatedInstanceSpecification.
Related instance specification is used in content and hierarchy specifications to "join" the primary instance with its related instance and allow using the related instance for:
- Filtering, when used in
instanceFilter
. - Customization, when used in customization rules.
- Grouping, when used in grouping rules.
Attributes
Name | Required? | Type | Default |
---|---|---|---|
relationshipPath |
Yes | RelationshipPathSpecification |
|
alias |
Yes | string |
|
isRequired |
No | boolean |
false |
Attribute: relationshipPath
Specifies a chain of relationship path specifications that forms a path from the primary instance to the related instances.
Type | RelationshipPathSpecification |
Is Required | Yes |
Attribute: alias
Specifies an an alias that given to the related instance. The alias can be used to reference the instance in instance filter and customization rules.
Note: The value must be unique per hierarchy specification. If there are multiple related instance specifications using the same alias, the library uses the first one and ignores the rest of them.
Type | string |
Is Required | Yes |
Attribute: isRequired
Specifies whether to omit the primary instance from the result if the other end of relationshipPath
does not yield any related instances.
Type | boolean |
Is Required | No |
Default Value | false |
Examples
Using related instances in instance filter
// This ruleset defines a specification that returns content for `bis.ViewDefinition` instances. In addition,
// there's a related instance specification, that describes a path to a related display style, and an
// instance filter that filters using its property.
const ruleset: Ruleset = {
id: "example",
rules: [{
ruleType: "Content",
specifications: [
{
specType: "ContentInstancesOfSpecificClasses",
classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
relatedInstances: [{
relationshipPath: {
relationship: { schemaName: "BisCore", className: "ViewDefinitionUsesDisplayStyle" },
direction: "Forward",
},
alias: "display_style",
isRequired: true,
}],
instanceFilter: `display_style.CodeValue ~ "%View%"`,
},
],
}],
};
Result | |
---|---|
Without instance filter | |
With instance filter |
Using related instances for customization
// This ruleset defines a specification that returns nodes for `meta.ECClassDef` instances. In addition,
// there's a related instance specification, that describes a path to the schema that the class belongs to.
// Finally, there's an extended data rule that sets full class name on each of the nodes. Full class name consists
// of schema and class names and the schema instance can be referenced through the alias specified in related
// instance specification.
const ruleset: Ruleset = {
id: "example",
rules: [{
ruleType: "RootNodes",
specifications: [
{
specType: "InstanceNodesOfSpecificClasses",
classes: { schemaName: "ECDbMeta", classNames: ["ECClassDef"] },
groupByClass: false,
groupByLabel: false,
relatedInstances: [{
relationshipPath: {
relationship: { schemaName: "ECDbMeta", className: "SchemaOwnsClasses" },
direction: "Backward",
},
alias: "schema",
isRequired: true,
}],
},
],
customizationRules: [{
ruleType: "ExtendedData",
items: {
fullClassName: `schema.Name & "." & this.Name`,
},
}],
}],
};
// Every node should have its full class name in extended data
const nodes = await Presentation.presentation.getNodes({
imodel,
rulesetOrId: ruleset,
});
expect(nodes.length).to.eq(417);
nodes.forEach((node) => {
const fullClassName = node.extendedData!.fullClassName;
const [schemaName, className] = fullClassName.split(".");
expect(schemaName).to.not.be.empty;
expect(className).to.not.be.empty;
});
Using related instances for grouping
// This ruleset defines a specification that returns nodes for `meta.ECClassDef` instances. In addition,
// there's a related instance specification, that describes a path to the schema that the class belongs to.
// Finally, there's a grouping rule that requests grouping on `ECSchemaDef.Name` property. Because
// the `ECClassDef` instances are "linked" to related `ECSchemaDef` instances, the grouping takes effect
// and classes get grouped by related schema names.
const ruleset: Ruleset = {
id: "example",
rules: [{
ruleType: "RootNodes",
specifications: [
{
specType: "InstanceNodesOfSpecificClasses",
classes: { schemaName: "ECDbMeta", classNames: ["ECClassDef"] },
groupByClass: false,
groupByLabel: false,
relatedInstances: [{
relationshipPath: {
relationship: { schemaName: "ECDbMeta", className: "SchemaOwnsClasses" },
direction: "Backward",
},
alias: "schema",
isRequired: true,
}],
},
],
customizationRules: [{
ruleType: "Grouping",
class: { schemaName: "ECDbMeta", className: "ECSchemaDef" },
groups: [{
specType: "Property",
propertyName: "Name",
createGroupForSingleItem: true,
}],
}],
}],
};
Result | |
---|---|
Without related instance specification | |
With related instance specification |
Last Updated: 24 January, 2023