Skip to main content

GetAssociationTargets@1

Node GetAssociationTargets@1 is used to find entities associated with a given entity based on specified criteria. This node queries the associations in OctoMesh's Entity Repository to retrieve related entities.

Adapter Prerequisites​

Node Configuration​

For fields path, targetPath, targetValueWriteMode, and targetValueKind, see Overview.

transformations:
  - type: GetAssociationTargets@1
    targetPath: $.associatedEntity           # Path where the associated entity should be stored in the payload
    targetValueKind: Simple                  # The target value kind; should be 'Object' to store a single entity
    targetValueWriteMode: Overwrite          # The target value write mode; should be 'Overwrite' to set the value
    sourceRtId: 5fc8fda18b2fc75f925e21af     # The runtime ID of the source entity
    sourceRtIdPath: $.sourceEntityId         # The path to the source runtime ID in the payload; any valid JSON path is allowed
    sourceCkId: Industry.Energy/Photovoltaic.Module  # The CK type ID of the source entity
    sourceCkTypeIdPath: $.sourceCkTypeId     # The path to the source CK type ID in the payload; any valid JSON path is allowed
    targetCkId: Industry.Energy/Photovoltaic.Inverter # The CK type ID of the target entity to find
    targetCkTypeIdPath: $.targetCkTypeId     # The path to the target CK type ID in the payload; any valid JSON path is allowed
    associationRoleId: Industry.Entity/ConnectedTo    # The CK association role ID defining the association
    associationRoleIdPath: $.associationRoleId        # The path to the association role ID in the payload; any valid JSON path is allowed
    graphDirection: Outbound                 # The direction of the association graph traversal; 'Inbound', 'Outbound', or 'Any'
    graphDirectionPath: $.graphDirection     # The path to the graph direction in the payload; any valid JSON path is allowed
    sortOrders:                            # Attribute-based filters to refine the results
    - attributeName: name
      sortOrder: Descending

Configuration Properties​

  • sourceRtId (OctoObjectId?): The runtime ID of the source entity.

  • sourceRtIdPath (string?): The JSON path to the source runtime ID in the payload. This property can be defined instead of the sourceRtId property.

  • sourceCkId (CkId<CkTypeId>?): The CK type ID of the source entity.

  • sourceCkTypeIdPath (string?): The JSON path to the source CK type ID in the payload. This property can be defined instead of the sourceCkId property.

  • targetCkId (CkId<CkTypeId>?): The CK type ID of the target entity to find.

  • targetCkTypeIdPath (string?): The JSON path to the target CK type ID in the payload. This property can be defined instead of the targetCkId property.

  • associationRoleId (CkId<CkAssociationRoleId>?): The CK association role ID defining the association between the source and target entities.

  • associationRoleIdPath (string?): The JSON path to the association role ID in the payload. This property can be defined instead of the associationRoleId property.

  • graphDirection (GraphDirectionsDto?): The direction in which to traverse the graph to find the associated entity. Options are 'Inbound', 'Outbound', or 'Any'.

  • graphDirectionPath (string?): The JSON path to the graph direction in the payload. This property can be defined instead of the graphDirection property.

  • fieldFilters (ICollection<FieldFilterDto>?): A collection of attribute-based filters to refine the results. Use these filters to return only those associated entities whose attributes match specified criteria (e.g., a particular status or threshold value).

  • sortOrders (ICollection<SortOrderDto>?): A collection of sort specifications to order the returned associated entities based on their attributes (e.g., sort by name ascending, or by capacity descending).

Usage Example​

Here's an example of how you might use the GetAssociationTargets@1 node in a transformation pipeline:

transformations:
  - type: GetAssociationTargets@1
    targetPath: $.parentEntity                   # Store the found associated entity in this path in the payload
    targetValueKind: Object                      # Store a single entity
    targetValueWriteMode: Overwrite              # Overwrite any existing value at the target path
    sourceRtIdPath: $.currentEntity.rtId         # Source entity runtime ID from the payload
    sourceCkTypeIdPath: $.currentEntity.ckTypeId # Source entity CK type ID from the payload
    targetCkId: System/Entity                    # The CK type ID of the target entity we are looking for
    associationRoleId: System/ParentChild        # The CK association role ID defining the 'HasParent' relationship
    graphDirection: Outbound                     # Traverse outbound associations from the source entity
    sortOrders:                                  # Sort the results by name attribute in ascending order     
      - attributeName: "name"
        sortOrder: Ascending

In this example:

  • Objective: Find a parent entity associated with the current entity.
  • Graph Direction: Set to 'Outbound', indicating traversal of outbound associations from the source entity.
  • Source Identifiers: Extracted from the payload using JSON paths ($.currentEntity.rtId and $.currentEntity.ckTypeId).
  • Target CK Type ID: Specifies the type of entity we are looking for (Industry.Entity/ParentEntityType).
  • Association Role ID: Specifies the type of association between the entities (System/ParentChild).
  • SortOrders: The sortOrders property is used to sort the retrieved results based on a specified attribute. In this case, it ensures that if multiple matching entities are found, they will be returned in ascending order by their name attribute.

Notes​

  • Property Precedence: If both the direct value and the corresponding path are provided for a property (e.g., both sourceRtId and sourceRtIdPath), the direct value (sourceRtId) takes precedence.
  • Mandatory Identifiers: Ensure all necessary IDs (runtime IDs, CK type IDs, association role IDs) are provided either directly or via JSON paths. Missing identifiers will result in an error, and processing for that item will terminate.
  • Graph Direction Options:
    • 'Inbound': Traverse associations pointing to the source entity.
    • 'Outbound': Traverse associations originating from the source entity.
    • 'Any': Traverse associations in any direction.
  • Result Handling: The node retrieves associated entities that match the specified target CK type ID and association role ID. Only the first matching entity is retrieved; if no matching entities are found, an error is logged.
  • Target Value Configuration: Set targetValueKind to 'Object' and targetValueWriteMode to 'Overwrite' to store the retrieved entity at the specified targetPath.

By configuring and using the GetAssociationTargets@1 node, you can effectively query and retrieve entities associated with a given entity based on specified criteria within your data pipeline.