Business Key Mappings

This document explains how business keys are defined in various data vault objects. Business keys are the unique identifiers for your core business concepts and are crucial for the integrity and functionality of your Data Vault.

Business Key Mapping Types

There are two primary methods for defining business key mappings, depending on the availability of the business key columns directly in your source data:

1. business_key_mapping: Used when the source columns that form the business key are directly available in the source system feeding the Data Vault object.
2. lookup_mapping: Used when the business key source columns are not directly available in the source. In this scenario, a join (or "lookup") operation is required with other related source data (typically from a hub's source) to obtain the necessary business key values.

Usage by Object Type

The applicability of these mapping types varies across Data Vault object types:

Strictly business_key_mapping: Used exclusively in Hubs and Reference Tables. For these objects, business keys are always derived directly from their primary source.

Both Mapping Types (business_key_mapping and lookup_mapping): Applicable in Hub Satellites (if the satellite's source doesn't directly feed the associated hub, so called satellite only), Links, and Non-Historized Links. These objects might need to look up business keys from related hubs if they are not directly present in their own source.

Business key mapping (business_key_mapping)

Key Considerations:

• source_business_key: This property is used to differentiate identical business key values originating from distinct source systems, addressing multi-master scenarios. It's typically part of the business key formation when you're integrating data from multiple systems where the same natural key might exist in different contexts. The property must be used only together with business_key_mapping.

• Reference Tables Exception: For References, the source_business_key property is omitted from the business_key_mapping. This is because reference tables typically do not integrate data from multiple, conflicting sources in a multi-master fashion, thus removing the need to distinguish identical keys by source.

Example: Direct Business Key Mapping

The example below illustrates mapping a source column (MATERIAL_PK) directly to a business key (MATERIAL_ID).

entity_sources:
- urn:s2v:hub_source:src_1:
    entity_source: '(SOURCE_DATA, MATERIAL)'
    source_filter: ''
    source_system_configuration_urn: 'urn:s2v:source_setting:yaml_interface'
    business_key_mapping:
    - MATERIAL_ID:
      - 'MATERIAL_PK'
    source_business_key: '' # Empty if not a multi-master scenario or not needed

Hub might have multiple business keys same as it can map multiple columns into one or more business keys. two examples below maps the same source columns towards one (concatenate_business_keys set to true) and multiple (concatenate_business_keys set to false) business keys.

tip

When defining business key mappings for Links or Satellites Only, it's highly recommended to have the definitions of the connected Hubs open. This helps you correctly match the business key mapping in the link with the specific business keys defined in its connected Hubs, preventing errors and ensuring proper key resolution. Specifically, the business key name defined in the business_key_mapping (e.g., MATERIAL_ID) must exactly match the business key name used in the Hub it connects to.

Example: Concatenating Multiple Source Columns into One Business Key

A Hub can derive its business key from multiple source columns, potentially concatenating them into a single business key. In the example below, SALES_ORDER_ID is formed by concatenating VBELN and POSNR from the VBAP source, assuming concatenate_business_keys is set to true for the associated hub.

entity_sources:
- urn:s2v:hub_source:SAP_SE:
    entity_source: '(SAP_SE, VBAP)'
    source_filter: ''
    source_system_configuration_urn: 'urn:s2v:source_setting:SAP'
    business_key_mapping:
    - SALES_ORDER_ID:
      - 'VBELN'
      - 'POSNR'
    source_business_key: ''

Example: Mapping Multiple Source Columns to Multiple Business Keys

Alternatively, if concatenate_business_keys is set to false, multiple source columns can be mapped to distinct business keys within the same object. This is useful when a single source record contains identifiers for different entities.

entity_sources:
- urn:s2v:hub_source:SAP_SE:
    entity_source: '(SAP_SE, VBAP)'
    source_filter: ''
    source_system_configuration_urn: 'urn:s2v:source_setting:SAP'
    business_key_mapping:
    - SALES_ORDER_HEADER:
      - 'VBELN'
    - SALES_ORDER_ITEM:
      - 'POSNR'
    source_business_key: ''

Lookup Mapping (lookup_mapping)

A lookup_mapping is utilized when the business keys for a target object (like a Link or a Hub Satellite) are not directly present in its immediate source data. Instead, these business keys must be obtained by joining with another source (typically the source of a connected Hub).

To achieve this, you define:

• entity_source_join_columns: Columns from the current object's source that will be used in the join condition.
• hub_source_join_columns: Columns from the associated Hub's source that will be used in the join condition.
• hub_source_urn: This property points to the specific Hub's source configuration, identifying which source table to join against.

In this scenario, you can't specify source_business_key within the lookup mapping itself, as the process directly obtains the already prepared business key value, ready for hashing.

Example: Lookup Mapping

This example shows a lookup_mapping where the CUSTOMER_FK from the link's CUSTOMER_ADDRESS source is joined with CUSTOMER_PK from a Hub's source (identified by hub_source_urn) to derive the necessary business key. Notice that link's hub_source_urn value urn:s2v:hub_source:master_data_customer matches hub's source name as highlighted below.

### Example of link's entity_sources definition
entity_sources:
- urn:s2v:hub_source:cust_addr_link_src: 
    entity_source: '(SOURCE_DATA, CUSTOMER_ADDRESS)'
    source_filter: ''
    use_source_cdc_flag: true
    source_system_configuration_urn: 'urn:s2v:source_setting:SAP'
    lookup_mapping:
      hub_source_urn: 'urn:s2v:hub_source:master_data_customer' # This URN defines which Hub's source to join with
      entity_source_join_columns:
        - 'CUSTOMER_FK' # Join column(s) from the current entity's source
      hub_source_join_columns:
        - 'CUSTOMER_PK' # Join column(s) from the hub's source

### Example of connected hub's entity_source we join with
entity_sources:
- urn:s2v:hub_source:master_data_customer:
    entity_source: '(SOURCE_DATA, CUSTOMER)'
    source_filter: ''
    source_system_configuration_urn: 'urn:s2v:source_setting:SAP'
    business_key_mapping:
    - CUSTOMER_ID:
      - 'CUSTOMER_ID'
    source_business_key: 'SAP_SE'