Related properties specification

TypeScript type: RelatedPropertiesSpecification.

This specification allows including related instance properties into the content.

Attributes

Name Required? Type Default
propertiesSource Yes RelationshipPathSpecification
instanceFilter No ECExpression ""
handleTargetClassPolymorphically No boolean false
relationshipMeaning No "SameInstance" | "RelatedInstance" "RelatedInstance"
properties No Array<string | PropertySpecification> | "_none_" | "*" "*"
autoExpand No boolean false
skipIfDuplicate No boolean false
nestedRelatedProperties No RelatedPropertiesSpecification[] []
relationshipProperties No Array<string | PropertySpecification> | "_none_" | "*" []
forceCreateRelationshipCategory No boolean false

Attribute: propertiesSource

Specifies a chain of relationship path specifications that forms a path from the content instance to the related instance(s) whose properties should additionally be loaded.

Type RelationshipPathSpecification
Is Required Yes

The path may point to more than one related instance, so the result always stores related properties in a form of a struct-array, where each struct represents a single related instance. However, often there's only one related instance and in that case a UI component displaying the result may choose to "destructure" the struct-array. An example of such component is the Property Grid:

// There's a content rule for returning content of given `bis.Subject` instance. The produced content is customized to
// additionally include properties of parent element by following the `bis.ElementOwnsChildElements` relationship
// in backwards direction.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ElementOwnsChildElements" },
                  direction: "Backward",
                },
              ],
            },
          ],
        },
      ],
    },
  ],
};

Example of using the "properties source" attribute

Here's how the result looks like if there's more than one related instance:

Example of using the "properties source" attribute pointing to multiple related instances

Attribute: instanceFilter

Specifies an ECExpression for filtering instances targeted by the propertiesSource attribute.

// There's a content rule for returning content of given instance. The produced content is customized to
// additionally include properties of child elements by following the `bis.ElementOwnsChildElements` relationship
// in forward direction, but only of children whose `CodeValue` starts with a "Bis" substring.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ElementOwnsChildElements" },
                  direction: "Forward",
                },
              ],
              instanceFilter: `this.CodeValue ~ "Bis%"`,
            },
          ],
        },
      ],
    },
  ],
};
without filter with filter
Example when selecting all related instances Example when filtering related instances

Note: A specification with higher priority and no instance filter overrides a specification with lower priority whether or not it has a filter.

Attribute: handleTargetClassPolymorphically

The attribute tells whether the target class specified through propertiesSource attribute should be handled polymorphically. This means properties of the concrete class are loaded in addition to properties of the target class itself.

Note: There's a difference between loading properties and instances polymorphically. This attribute only controls polymorphism of properties, while instances are always looked up in a polymorphic fashion.

Type boolean
Is Required No
Default Value false
// There's a content rule for returning content of given `bis.Subject` instance. The produced content is customized to
// additionally include properties of parent element by following the `bis.ElementOwnsChildElements` relationship
// in backwards direction. Setting `handleTargetClassPolymorphically` to `true` makes sure that the concrete target class is
// determined and all its properties are loaded.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ElementOwnsChildElements" },
                  direction: "Backward",
                },
              ],
              handleTargetClassPolymorphically: true,
            },
          ],
        },
      ],
    },
  ],
};
handleTargetClassPolymorphically: false handleTargetClassPolymorphically: true
Example of using "handle target class polymorphically" attribute set to "false" Example of using "handle target class polymorphically" attribute set to "true"

Attribute: relationshipMeaning

The attribute describes what the related properties mean to the primary instance whose properties are displayed. There are two possible options:

  • RelatedInstance means that the properties should be distinguished from properties of the primary instance and shown separately to make it clear they belong to another instance. Generally that means they're assigned a separate root category.

  • SameInstance means that the properties should be displayed as if they belonged to the primary instance. Generally that means they assigned a category, that's nested under the default category.

See property categorization page page for more details.

Type "SameInstance" | "RelatedInstance"
Is Required No
Default Value "RelatedInstance"
// There's a content rule for returning content of given `bis.PhysicalModel` instance. The produced content is customized to
// additionally include properties of modeled element by following the `bis.ModelModelsElement` relationship.
// Setting `relationshipMeaning` to `SameInstance` makes sure that all related properties are placed into a category
// nested under the default category.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
                  direction: "Forward",
                  targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
                },
              ],
              relationshipMeaning: "SameInstance",
            },
          ],
        },
      ],
    },
  ],
};
relationshipMeaning: "RelatedInstance" relationshipMeaning: "SameInstance"
Example of using "relationship meaning" attribute set to "related instance" Example of using "relationship meaning" attribute set to "same instance"

Attribute: properties

List of names or definitions of related class properties that should be included in the content. In addition, a couple of special values are allowed:

  • "_none_" means none of the properties should be picked up. Generally this is used in combination with the nestedRelatedProperties attribute.
  • "*" means all properties should be picked up.
Type Array<string | PropertySpecification> | "_none_" | "*"
Is Required No
Default Value "*"
// There's a content rule for returning content of given `bis.PhysicalModel` instance. The produced content is customized to
// additionally include specific properties of modeled Element by following the `bis.ModelModelsElement` relationship.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
                  direction: "Forward",
                  targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
                },
              ],
              properties: ["UserLabel", "Description"],
            },
          ],
        },
      ],
    },
  ],
};

Example of using the "properties" attribute

Attribute: autoExpand

The attribute specifies whether the field containing related properties should be assigned the NestedContentField.autoExpand attribute. The attribute tells UI components showing the properties that they should be initially displayed in the expanded state.

Type boolean
Is Required No
Default Value false
// There's a content rule for returning content of given `bis.Subject` instance. The produced content is customized to
// additionally include all properties of child subjects by following the `bis.SubjectOwnsSubjects` relationship and that
// the properties should be automatically expanded.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "SubjectOwnsSubjects" },
                  direction: "Forward",
                },
              ],
              autoExpand: true,
            },
          ],
        },
      ],
    },
  ],
};
autoExpand: false autoExpand: true
Example of using "auto expand" attribute set to "false" Example of using "auto expand" attribute set to "true"

Attribute: skipIfDuplicate

Specifies whether the specification should be ignored if another higher priority specification for the same relationship already exists.

Type boolean
Is Required No
Default Value false
// There's a content rule for returning content of given `bis.PhysicalModel` instance. There are also two specifications
// requesting to load related properties:
// - the one specified through a content modifier requests all properties of the target class and has `skipIfDuplicate` flag.
// - the one specified through the content specification requests only `UserLabel` property.
// The specification at content specification level takes precedence and loads the `UserLabel` property. The other is completely
// ignored due to `skipIfDuplicate` attribute being set to `true`.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
                  direction: "Forward",
                  targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
                },
              ],
              properties: ["UserLabel"],
            },
          ],
        },
      ],
    },
    {
      ruleType: "ContentModifier",
      class: { schemaName: "BisCore", className: "Model" },
      relatedProperties: [
        {
          propertiesSource: [
            {
              relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
              direction: "Forward",
              targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
            },
          ],
          skipIfDuplicate: true,
        },
      ],
    },
  ],
};
skipIfDuplicate: false skipIfDuplicate: true
Example of using "skip if duplicate" attribute set to "false" Example of using "skip if duplicate" attribute set to "true"

Attribute: nestedRelatedProperties

The attribute allows loading additional related properties that are related to the target instance of this specification.

Type RelatedPropertiesSpecification[]
Is Required No
Default Value []
// There's a content rule for returning content of given `bis.PhysicalModel` instance. There's also a related properties
// specification that loads modeled element properties and properties of `bis.LinkElement` related to the modeled element.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
                  direction: "Forward",
                  targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
                },
              ],
              nestedRelatedProperties: [
                {
                  propertiesSource: [
                    {
                      relationship: { schemaName: "BisCore", className: "ElementHasLinks" },
                      direction: "Forward",
                      targetClass: { schemaName: "BisCore", className: "RepositoryLink" },
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    },
  ],
};

Example of using the "nested related properties" attribute

Attribute: relationshipProperties

Lists ECRelationshipClass properties that should be included in the content. Only the properties from the last relationship of propertiesSource path are accessible. In addition, a couple of special values are allowed:

  • "_none_" means none of the relationship properties should be picked up.
  • "*" means all relationship properties should be picked up.
Type Array<string | PropertySpecification> | "_none_" | "*"
Is Required No
Default Value []
// There's a content rule for returning content of given `meta.ECClassDef` instance. The produced content is customized to
// additionally include a specific relationship property of the `meta.ClassHasBaseClasses` relationship.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "ECDbMeta", className: "ClassHasBaseClasses" },
                  direction: "Forward",
                },
              ],
              properties: ["Name"],
              relationshipProperties: ["Ordinal"],
            },
          ],
        },
      ],
    },
  ],
};

Example of using the "relationship properties" attribute

Attribute: forceCreateRelationshipCategory

Specifies whether a relationship category should be created regardless of whether any relationship properties were included.

Type boolean
Is Required No
Default Value false
// There's a content rule for returning content of given `bis.PhysicalModel` instance. The produced content is customized to
// additionally create a category for the `bis.ModelModelsElement` relationship.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "SelectedNodeInstances",
          relatedProperties: [
            {
              propertiesSource: [
                {
                  relationship: { schemaName: "BisCore", className: "ModelModelsElement" },
                  direction: "Forward",
                  targetClass: { schemaName: "BisCore", className: "PhysicalPartition" },
                },
              ],
              properties: ["UserLabel"],
              forceCreateRelationshipCategory: true,
            },
          ],
        },
      ],
    },
  ],
};
forceCreateRelationshipCategory: false forceCreateRelationshipCategory: true
Example of using the "force create relationship category" attribute set to "false" Example of using the "force create relationship category" attribute set to "true"

Last Updated: 15 May, 2024