Zum Hauptinhalt springen

GetAssociationTargets@1

Der Node GetAssociationTargets@1 dient dazu, anhand angegebener Kriterien Entitäten zu finden, die mit einer bestimmten Entität assoziiert sind. Dieser Node fragt die Assoziationen im Entity Repository von OctoMesh ab, um verwandte Entitäten abzurufen.

Adapter-Voraussetzungen​

Node-Konfiguration​

Zu den Feldern path, targetPath, targetValueWriteMode und targetValueKind siehe Überblick.

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
    sourceCkTypeId: 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
    targetCkTypeId: 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
    fieldFilters:                         # Collection of attribute-based filters to refine the results
      - attributePath: rtId # The attribute path to filter
        operator: Equals # The operator to use for filtering
        comparisonValue: "6831724cb90d979b8ae5589b" # The value to compare against (when using a direct value)
        comparisonValuePath: $.rtId # The value to compare against (when using a path)

Konfigurationseigenschaften​

  • sourceRtId (OctoObjectId?): Die Runtime-ID der Quellentität.

  • sourceRtIdPath (string?): Der JSON-Pfad zur Runtime-ID der Quellentität in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft sourceRtId definiert werden.

  • sourceCkTypeId (CkId<CkTypeId>?): Die CK-Typ-ID der Quellentität.

  • sourceCkTypeIdPath (string?): Der JSON-Pfad zur CK-Typ-ID der Quellentität in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft sourceCkTypeId definiert werden.

  • targetCkTypeId (CkId<CkTypeId>?): Die CK-Typ-ID der zu findenden Zielentität.

  • targetCkTypeIdPath (string?): Der JSON-Pfad zur CK-Typ-ID der Zielentität in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft targetCkTypeId definiert werden.

  • associationRoleId (CkId<CkAssociationRoleId>?): Die CK-Assoziationsrollen-ID, die die Assoziation zwischen Quell- und Zielentität definiert.

  • associationRoleIdPath (string?): Der JSON-Pfad zur Assoziationsrollen-ID in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft associationRoleId definiert werden.

  • graphDirection (GraphDirectionsDto?): Die Richtung, in der der Graph durchlaufen wird, um die assoziierte Entität zu finden. Mögliche Werte sind 'Inbound', 'Outbound' oder 'Any'.

  • graphDirectionPath (string?): Der JSON-Pfad zur Graph-Richtung in der Payload. Diese Eigenschaft kann anstelle der Eigenschaft graphDirection definiert werden.

  • fieldFilters (ICollection<FieldFilterWithPathDto>?): Eine Sammlung attributbasierter Filter zur Verfeinerung der Ergebnisse. Verwenden Sie diese Filter, um nur diejenigen assoziierten Entitäten zurückzugeben, deren Attribute den angegebenen Kriterien entsprechen (z. B. ein bestimmter Status oder Schwellenwert).

  • sortOrders (ICollection<SortOrderDto>?): Eine Sammlung von Sortierangaben, um die zurückgegebenen assoziierten Entitäten anhand ihrer Attribute zu ordnen (z. B. Sortierung nach Name aufsteigend oder nach Kapazität absteigend).

Anwendungsbeispiel​

Hier ein Beispiel, wie Sie den Node GetAssociationTargets@1 in einer Transformations-Pipeline verwenden könnten:

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
    targetCkTypeId: 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
    fieldFilters:
      - attributePath: rtId # The attribute path to filter
        operator: Equals # The operator to use for filtering
        comparisonValue: "6831724cb90d979b8ae5589b" # The value to compare against

In diesem Beispiel:

  • Ziel: Eine übergeordnete Entität finden, die mit der aktuellen Entität assoziiert ist.
  • Graph-Richtung: Auf 'Outbound' gesetzt, was das Durchlaufen ausgehender Assoziationen von der Quellentität aus bedeutet.
  • Quell-Identifikatoren: Über JSON-Pfade aus der Payload extrahiert ($.currentEntity.rtId und $.currentEntity.ckTypeId).
  • Ziel-CK-Typ-ID: Gibt den Typ der gesuchten Entität an (Industry.Entity/ParentEntityType).
  • Assoziationsrollen-ID: Gibt den Typ der Assoziation zwischen den Entitäten an (System/ParentChild).
  • SortOrders: Die Eigenschaft sortOrders wird verwendet, um die abgerufenen Ergebnisse anhand eines angegebenen Attributs zu sortieren. In diesem Fall wird sichergestellt, dass mehrere gefundene passende Entitäten in aufsteigender Reihenfolge nach ihrem Namensattribut zurückgegeben werden.
  • FieldFilters: Filtert die Ergebnisse so, dass nur Entitäten mit einer bestimmten Runtime-ID enthalten sind.

Hinweise​

  • Vorrang von Eigenschaften: Werden für eine Eigenschaft sowohl der direkte Wert als auch der zugehörige Pfad angegeben (z. B. sowohl sourceRtId als auch sourceRtIdPath), hat der direkte Wert (sourceRtId) Vorrang.
  • Verpflichtende Identifikatoren: Stellen Sie sicher, dass alle notwendigen IDs (Runtime-IDs, CK-Typ-IDs, Assoziationsrollen-IDs) entweder direkt oder über JSON-Pfade bereitgestellt werden. Fehlende Identifikatoren führen zu einem Fehler, und die Verarbeitung dieses Elements wird abgebrochen.
  • Optionen für die Graph-Richtung:
    • 'Inbound': Assoziationen durchlaufen, die auf die Quellentität zeigen.
    • 'Outbound': Assoziationen durchlaufen, die von der Quellentität ausgehen.
    • 'Any': Assoziationen in beliebiger Richtung durchlaufen.
  • Ergebnisbehandlung: Der Node ruft assoziierte Entitäten ab, die der angegebenen Ziel-CK-Typ-ID und Assoziationsrollen-ID entsprechen. Nur die erste passende Entität wird abgerufen; wird keine passende Entität gefunden, wird ein Fehler protokolliert.
  • Konfiguration des Zielwerts: Setzen Sie targetValueKind auf 'Object' und targetValueWriteMode auf 'Overwrite', um die abgerufene Entität am angegebenen targetPath zu speichern.

Verwandte Nodes​

Durch die Konfiguration und Verwendung des Nodes GetAssociationTargets@1 können Sie in Ihrer Datenpipeline effektiv Entitäten abfragen und abrufen, die anhand angegebener Kriterien mit einer bestimmten Entität assoziiert sind.