Skip to main content

GetOrCreateRtEntitiesByType@1

Node GetOrCreateRtEntitiesByType@1 is used to find an existing entity based on specified field filters or create a new entity RtId if none is found. This node helps manage entities within OctoMesh's Entity Repository by ensuring each entity has a unique runtime ID (RtId).

Adapter Prerequisites​

Node Configuration​

transformations:
  - type: GetOrCreateRtEntitiesByType@1
    ckTypeId: Industry.Energy/Photovoltaic.Module  # The CK type ID of the entity to find or create
    fieldFilters:                                  # Field filters used to find the entity
      - path: $.serialNumber                       # The JSON path to the value in the payload
        attributeName: SerialNumber                # The attribute name in the entity
        operator: Equal                            # The operator to use for filtering (e.g., Equal, NotEqual)
      - path: $.manufacturer
        attributeName: Manufacturer
        operator: Equal
    rtIdTargetPath: $.entity.rtId                  # Path where the RtId should be stored in the payload
    ckTypeIdTargetPath: $.entity.ckTypeId          # Path where the CK type ID should be stored in the payload
    modOperationPath: $.entity.modOperation        # Path where the modification operation (Insert/Update) should be stored

Configuration Properties​

  • ckTypeId (CkId<CkTypeId>?) (required): The CK type ID of the entity to find or create.

  • fieldFilters (ICollection<PathFieldFilter>?) (required): A collection of field filters used to find the entity. Each filter includes:

    • path (string): The JSON path to the value in the payload.
    • attributeName (string): The attribute name in the entity to filter on.
    • operator (FieldFilterOperator): The operator to use for filtering (e.g., Equal, NotEqual, Contains).

  • rtIdTargetPath (string): The JSON path where the RtId should be stored in the payload. Default is $.rtId.

  • ckTypeIdTargetPath (string): The JSON path where the CK type ID should be stored in the payload. Default is $.ckTypeId.

  • modOperationPath (string): The JSON path where the modification operation (Insert or Update) should be stored in the payload. Default is $.modOperation.

Usage Example​

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

transformations:
  - type: GetOrCreateRtEntitiesByType@1
    ckTypeId: Industry.Energy/Photovoltaic.Module
    fieldFilters:
      - path: $.data.serialNumber
        attributeName: SerialNumber
        operator: Equal
      - path: $.data.model
        attributeName: Model
        operator: Equal
    rtIdTargetPath: $.entity.rtId
    ckTypeIdTargetPath: $.entity.ckTypeId
    modOperationPath: $.entity.modOperation

In this example:

  • Objective: Find an existing Photovoltaic Module entity based on its serial number and model. If it doesn't exist, create a new RtId for it.

  • Field Filters:

    • Filter by SerialNumber where the value is obtained from $.data.serialNumber in the payload.
    • Filter by Model where the value is obtained from $.data.model in the payload.

  • Output Paths:

    • The found or newly created RtId is stored at $.entity.rtId.
    • The ckTypeId is stored at $.entity.ckTypeId.
    • The modification operation (Insert or Update) is stored at $.entity.modOperation.

Configuration Properties Details​

ckTypeId (required)​

  • Type: CkId<CkTypeId>?
  • Description: The CK type ID of the entity to find or create. This specifies the type of entity in the repository.

fieldFilters (required)​

  • Type: ICollection<PathFieldFilter>?
  • Description: A list of field filters used to search for the entity. Each PathFieldFilter includes:
    • path: The JSON path to the value in the payload.
    • attributeName: The name of the attribute in the entity to filter on.
    • operator: The comparison operator (Equal, NotEqual, Contains, etc.).

rtIdTargetPath​

  • Type: string
  • Default: $.rtId
  • Description: The JSON path where the resulting RtId should be stored in the payload.

ckTypeIdTargetPath​

  • Type: string
  • Default: $.ckTypeId
  • Description: The JSON path where the CK type ID should be stored in the payload.

modOperationPath​

  • Type: string
  • Default: $.modOperation
  • Description: The JSON path where the modification operation (Insert or Update) should be stored in the payload. This indicates whether a new entity was created or an existing one was found.

Notes​

  • Mandatory Properties: Both ckTypeId and fieldFilters are required. The node will log an error and terminate processing for the item if they are not provided.

  • Field Filters: Ensure that the attributeName corresponds to a valid attribute in the CK type specified by ckTypeId.

  • Operators: The operator in field filters can be one of the following:

    • Equal
    • NotEqual
    • Contains
    • StartsWith
    • EndsWith

  • Processing Logic:

    • The node attempts to find an existing entity that matches the specified field filters.
    • If an entity is found:
      • The existing RtId is stored at rtIdTargetPath.
      • The ckTypeId is stored at ckTypeIdTargetPath.
      • The modOperation is set to Update and stored at modOperationPath.
    • If no entity is found:
      • A new RtId is generated and stored at rtIdTargetPath.
      • The ckTypeId is stored at ckTypeIdTargetPath.
      • The modOperation is set to Insert and stored at modOperationPath.

  • Subsequent Processing:

    • The RtId, ckTypeId, and modOperation can be used in subsequent nodes, such as CreateUpdateInfo@1, to create or update the entity in the repository.

By configuring and using the GetOrCreateRtEntitiesByType@1 node, you can effectively manage entities in your data pipeline by ensuring that each entity has a unique runtime ID and determining whether to perform an insert or update operation based on the existence of the entity.