Version: Next

How to build a Link?

This tutorial will guide you through building a complete Link object YAML definition step-by-step. A Link establishes relationships between two or more Hubs.

We'll build a Link named LNK_SALES_ORDER that represents an item on an order, connecting HUB_SALES_ORDER, HUB_MATERIAL , HUB_PROFIT_CENTER and HUB_CUSTOMER.

Link Name (name): This is the unique identifier for your Link object.
```
name: 'LNK_SALES_ORDER' # 1. Link Name
```

Entity Type (entity_type): Specifies that this object is a Link.

name: 'LNK_SALES_ORDER'
entity_type: 'link'            # 2. Entity Type

Enable Refresh (enable_refresh): A boolean flag indicating whether the link receives new data. Set to true if the object can receive new data, set to false if the object contains only historical records.
```
name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: true         # 3. Enable Refresh
```
Enable Status Tracking (enable_status_tracking): A boolean flag indicating whether an additional object for tracking Link effectivtiy shall be added. This entity tracks validity of incoming data as a "single to be queried object" to get any valida relationship at a given point in time. This flag can be set to false if there are Satellites attached to the Link. Otherwise it must be set to true.
```
name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: true
enable_status_tracking: true # 4. Enable Status Tracking
```
Connected Hubs (connected_hubs):

This property defines the hubs a link connects, specified as a list of key-value pairs.
- Key: Represents the hub's alias, or the specific name of the relationship. This is necessary because a link can connect to the same hub multiple times, requiring unique aliases to distinguish each connection. The hub alias must be unique within the connected_hubs list.
- Value: Represents the actual name of the hub, which must refer to an existing hub definition.
- First, we define the list:
```
name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: true
enable_status_tracking: true

connected_hubs:                             # 5. Connected Hubs
  - CUSTOMER: 'HUB_CUSTOMER'                # <Alias>: <Hub Name>
  - SALES_ORDER: 'HUB_SALES_ORDER'
  - PROFIT_CENTER: 'HUB_PROFIT_CENTER'
  - MATERIAL: 'HUB_MATERIAL'
```

Entity Sources (entity_sources): This property defines the source(s) that feed data into this Link. For Links, it's a list, meaning a Link can be populated from multiple sources. We'll define one source for this example.

6.1. Source URN Identifier: This is the unique URN key for this specific source definition within the list. The prefix often indicates the DV object type (e.g., hub_source, link_source).

name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: true
enable_status_tracking: true

connected_hubs:
  - CUSTOMER: 'HUB_CUSTOMER'
  - SALES_ORDER: 'HUB_SALES_ORDER'
  - PROFIT_CENTER: 'HUB_PROFIT_CENTER'
  - MATERIAL: 'HUB_MATERIAL'
entity_sources:                   # 6. Entity Sources
  - urn:s2v:link_source:SAP_OE:   # 6.1. Source URN Identifier

6.2. Source Location (entity_source): Specifies the physical location of this source's data.
- For multiple source databases, use a triple: (source_database, source_schema, source_table).
- For a single source database context: (source_schema, source_table).

# ... (previous properties)
entity_sources:
  - urn:s2v:link_source:SAP_OE:
      entity_source: '(SAP_OE, 2LIS_11_VAITM)' # 6.2. Source Location

6.3. Source Filter (source_filter): An optional SQL condition applied to the source data. You can use any valid SQL code that can be inserted into a WHERE clause. Leave it empty if no filters are required.

# ... (previous properties)
entity_sources:
  - urn:s2v:link_source:SAP_OE:
      entity_source: '(SAP_OE, 2LIS_11_VAITM)'
      source_filter: ''             # 6.3. Source Filter

6.4. Source System Configuration URN (source_system_configuration_urn): Links this specific source to its system-wide settings. The connection is established via a URN following the fixed format: urn:s2v:source_setting:<SETTING_NAME>.

# ... (previous properties)
entity_sources:
  - urn:s2v:link_source:SAP_OE:
      entity_source: '(SAP_OE, 2LIS_11_VAITM)'
      source_filter: ''
      source_system_configuration_urn: 'urn:s2v:source_setting:SAP' # 6.4. Source System Configuration URN

6.5. Connected Hub Relations (connected_hub_relations): This crucial property defines how the business keys for each connected Hub (defined in step 3) are sourced from this specific entity source. It's a list, and each item corresponds to a Hub alias from the connected_hubs property.

For each Hub alias, you define its business_key_mapping. This maps the Hub's business key (as named in connected_hubs) to the corresponding column(s) in the current source table (SD_SALES_ORDERS in this case). In case the source table doesn't contain source columns that might be directly mapped to the Hub's business key, use lookup_mapping. Read more about differences in [TBD REFERENCE].

name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: true
enable_status_tracking: true

connected_hubs:
- CUSTOMER: 'HUB_CUSTOMER'
- SALES_ORDER: 'HUB_SALES_ORDER'
- PROFIT_CENTER: 'HUB_PROFIT_CENTER'
- MATERIAL: 'HUB_MATERIAL'
entity_sources:
  - urn:s2v:link_source:SAP_OE:
      entity_source: '(SAP_OE, 2LIS_11_VAITM)'
      source_filter: ''
      source_system_configuration_urn: 'urn:s2v:source_setting:SAP'
      connected_hub_relations:        # 6.5 Connected Hub Relations
        - CUSTOMER:                   # Corresponds to alias in connected_hubs
            business_key_mapping:
              - CUSTOMER_BK:          # Hub's business key name
                  - 'KUNNR'           # Source column from CUSTOMER_BK
            source_business_key: ''   # Optional: for multi-master scenarios
        - SALES_ORDER:
            source_business_key: 'SAP_OE_SD'
            business_key_mapping:
              - SALES_ORDER_BK:
                  - 'VBELN'
                  - 'POSNR'
        - PROFIT_CENTER:
            source_business_key: ''
            business_key_mapping:
              - PROFIT_CENTER_BK:
                  - "PRCTR"
                  - "KOKRS"
        - MATERIAL:
            source_business_key: ''
            business_key_mapping:
              - MATERIAL_BK:
                  - 'MATNR'

Complete Link YAML

Here is the complete YAML definition for our LNK_SALES_ORDER Link:

name: 'LNK_SALES_ORDER'
entity_type: 'link'
enable_refresh: True
enable_status_tracking: true

connected_hubs:
  - CUSTOMER: 'HUB_CUSTOMER'                 # <Alias>: <Hub Name>
  - SALES_ORDER: 'HUB_SALES_ORDER'
  - PROFIT_CENTER: 'HUB_PROFIT_CENTER'
  - MATERIAL: 'HUB_MATERIAL'

entity_sources:
  - urn:s2v:link_source:SAP_OE:                   # Unique URN for this source
      entity_source: '(SAP_OE, 2LIS_11_VAITM)'    # Source: (Schema, Table)
      source_filter:                              # Optional filter
      source_system_configuration_urn: 'urn:s2v:source_setting:SAP' # Link to global source settings
      connected_hub_relations:
        - CUSTOMER:
            source_business_key: '' # Optional source system identifier
            business_key_mapping:
              - CUSTOMER_BK:        # Business key name from HUB_CUSTOMER
                  - 'KUNNR'         # Source column KUNNR participating in business key
        - SALES_ORDER:
            source_business_key: 'SAP_OE_SD'
            business_key_mapping:
              - SALES_ORDER_BK:
                  - 'VBELN'
                  - 'POSNR'
        - PROFIT_CENTER:
            source_business_key: ''
            business_key_mapping:
              - PROFIT_CENTER_BK:
                  - "PRCTR"
                  - "KOKRS"
        - MATERIAL:
            source_business_key: ''
            business_key_mapping:
              - MATERIAL_BK:
                  - 'MATNR'

Complete Link YAML​

Complete Link YAML