Skip to main content

Mapping framework (UBC.map)

Intro​

UBC - Unified Backend Connector comes with a flexible mapping framework component that enables transformation between different message formats and data structures. The mapping framework provides a standardized approach to handle various mapping scenarios within your SAP environment, making cross-system data exchange more manageable.

Mapping​

The UBC.map framework provides multiple approaches to mapping data between different structures and tables. These mapping strategies can be configured to meet specific requirements:

  • Field-specific Mapping: Maps individual fields from source to target structures with precise control over data transformation at the field level.
  • Corresponding Field Mapping: Automatically maps fields with matching names or keys between source and target structures, streamlining the mapping process for similar data models.
  • Table Iteration Mapping: Processes tables by iterating through each line and applying configured mapping rules, enabling complex transformations of tabular data.

These mapping approaches can be used independently or in combination to address various mapping operations, from simple data transfers to complex cross-system transformations.

" Simple structure mapping
DATA: lo_mapping TYPE REF TO /ubc/if_mp_mapping,
      ls_source  TYPE sflight,
      ls_target  TYPE ty_order.

SELECT SINGLE * FROM sflight 
  INTO @ls_source
  WHERE carrid = 'LH' AND connid = '0400'.

TRY.
    lo_mapping = /ubc/cl_mp_mapping=>create_instance( 'Z_FLIGHT_TO_ORDER' ).
    
    lo_mapping->process(
      EXPORTING iv_input  = ls_source
      IMPORTING ev_output = ls_target ).
      
CATCH /ubc/cx_map INTO DATA(lx_error).
    MESSAGE lx_error TYPE 'E'.
ENDTRY.

" Table-to-Table mapping
DATA: lt_flights TYPE TABLE OF sflight,
      lt_orders  TYPE TABLE OF ty_order_item.

SELECT * FROM sflight 
  INTO TABLE @lt_flights
  WHERE carrid = 'LH' 
    AND fldate >= '20250101'.

TRY.
    lo_mapping = /ubc/cl_mp_mapping=>create_instance( 'Z_FLIGHTS_TO_ORDERS' ).
    
    lo_mapping->process(
      EXPORTING iv_input  = lt_flights
      IMPORTING ev_output = lt_orders ).
      
CATCH /ubc/cx_map INTO DATA(lx_tab_error).
    MESSAGE lx_tab_error TYPE 'E'.
ENDTRY.

Mapping Fields​

Field mapping defines the precise relationships between source and target data elements. UBC.map supports several mapping types to accommodate different transformation requirements:

  • Constant Mapping: Assigns a literal value directly to a target field, useful for setting default values or standardizing data across records.
  • Full Source Mapping: Maps an entire source structure to a target field rather than mapping individual elements, enabling complex structure transformations.
  • Full Target Mapping: Maps a source field to an entire target structure, facilitating the population of multiple target fields from a single source element.

Each mapping can optionally incorporate a conversion operation that transforms the data during the mapping process. These conversions can handle type transformations, format standardizations, or complex business logic as required from the mapping operation.

Submappings​

Submappings extend the mapping framework to handle nested data structures and complex hierarchical relationships. When mapping operations require transformation of nested elements, submappings provide a structured approach to defining these relationships.

A submapping is a complete mapping configuration that is associated with a specific mapping field. This allows complex structures to be mapped with the same flexibility and precision as top-level elements, maintaining data integrity throughout the transformation process.

Submappings are particularly valuable when working with:

  • Complex JSON or XML structures with multiple nesting levels
  • Business objects containing child components or line items
  • Mapping operations requiring partial structure transformations within larger data sets

By supporting nested mapping definitions, UBC.map enables comprehensive data transformations regardless of structural complexity.

Mapping submapping configuration

Conversions​

The UBC.map framework provides standardized conversion capabilities that ensure data consistency when transferring information between systems with different formatting requirements:

  • Unit Conversions: Automatically transforms measurement values (i.e. imperial to and from metric) between systems, ensuring consistent data representation across regional boundaries.

  • Datetime Conversions: Handles transformation of timestamp data between various formats, standardizing datetime representations for seamless integration between systems (like erp and mes) with different time handling conventions.

  • Alpha Conversions: Manages alphabetic character set transformations and normalizations, supporting multi-language compatibility and character encoding adjustments across systems.

  • QPPD to SAP Standard Conversions: Converts Quality, Production, Planning and Distribution (QPPD) specific formats to SAP standard formats, enabling smooth integration between specialized industry solutions and core SAP processes.

These conversion capabilities are part of the broader mapping process.

Mapping Process Flow​

Data Grouping​

Data tables can be dynamically sorted and grouped according to fields specified in customizing. UBC.map provides flexible data grouping capabilities that can be configured through grouping IDs in the customizing transaction.

The Data Grouping functionality supports:

  • Grouping by single or multiple fields
  • Automatic sorting of data based on grouping fields
  • Dynamic result structure generation based on input data
  • Access to both the grouped data and grouping metadata

Each grouped result contains:

  • The grouping value (concatenated from the grouping fields)
  • The list of fields used for grouping
  • The subset of data that belongs to that group
info

The grouping result structure is dynamically generated based on the input data structure, with fields for the grouping metadata plus a DATA component containing the grouped records.

This powerful feature enables efficient data organization and processing for downstream operations, particularly useful when dealing with complex hierarchical data structures or when preparing data for batch processing.

" Data grouping with multiple fields
DATA: lt_flights  TYPE TABLE OF sflight,
      lo_grouping TYPE REF TO /ubc/if_bc_data_grouping,
      lo_result   TYPE REF TO data.

FIELD-SYMBOLS: <lt_grouped> TYPE STANDARD TABLE.

SELECT * FROM sflight 
  INTO TABLE @lt_flights
  WHERE carrid IN ('LH', 'AF') 
    AND fldate BETWEEN '20250101' AND '20250131'.

TRY.
    lo_grouping = /ubc/cl_bc_data_grouping=>create_instance( 'Z_FLIGHTS_BY_CARRIER_CONN' ).
    
    DATA(lo_result_type) = lo_grouping->get_result_type( lt_flights ).
    CREATE DATA lo_result TYPE HANDLE lo_result_type.
    ASSIGN lo_result->* TO <lt_grouped>.
    
    lo_grouping->group_data(
      EXPORTING it_data = lt_flights
      IMPORTING et_data = <lt_grouped>
    ).
    
CATCH /ubc/cx_bc_data_grouping INTO DATA(lx_error).
    MESSAGE lx_error TYPE 'E'.
ENDTRY.

Data Grouping Process​

Customizing​

Define and configure your mapping rules through customizing. Similar to other UBC components, mapping configurations can be accessed through the UBC customizing transaction /UBC/MAPPING_C where you can define your mappings, groupings, parsings and assign source and target structures and their relationships. Additionally active and inactive mappings, groupings, conversions can be displayed with /UBC/MAPPING_D.

Mapping Configuration​

Configure mappings by creating a mapping entry with a unique ID. This entry serves as the foundation for all related field mappings and defines the general processing behavior:

  • Table-to-Table Relation: When enabled, the mapping will iterate through each row of the input table and apply field mappings to each record individually. Without this setting, the mapping processes a single structure. This corresponds to the table_to_table flag in the mapping definition.

  • Keep Corresponding Fields: When enabled, the system will automatically use ABAP's CORRESPONDING operator to map fields with matching names before applying your custom field mappings. This is useful for structures with many matching field names to reduce the number of explicit mappings required.

tip

If you're mapping between similar structures with mostly matching field names, enable "Keep Corresponding Fields" and only define mappings for fields that need special handling.

Field Mapping Configuration​

For each mapping ID, define individual field mappings in the field mapping tab. Each field mapping specifies:

  • From Field: The source field in the input structure

  • To Field: The target field in the output structure

  • Mapping Type: Control how the field values are processed:

    • Constant Mapping: The value in "From Field" is treated as a literal constant and assigned directly to the target field without looking up a value in the input structure. Useful for setting fixed values, defaults, or parameters.

    • Full From Mapping: Maps the entire input structure to the specified target field. This assigns the complete input structure reference to a single field in the output structure, useful when storing a complex structure within a single field.

    • Full To Mapping: Maps a single source field to the entire output structure. This is useful when a source field contains data that needs to expand into the entire target structure.

    • Regular Field Mapping: (when none of the above are set) Maps a single field from input to output, applying any specified conversions.

  • Submapping: Specify another mapping ID to process nested structures. When specified, the system creates a new mapping instance for the substructure and applies it to transform the nested data between the source and target fields.

  • Conversion Options:

    • Conversion: Assign a standard conversion (unit, datetime, alpha, QPPD) to transform the data during mapping.
    • Conversion Mapping: Specify a custom conversion method for complex transformations requiring business logic.
warning

When using "Full From" or "Full To" options, ensure that the target/source field can accept the complete structure type. These options bypass normal field-level mapping and work directly with structure references.

Data Grouping Configuration​

Data grouping organizes table data into logical groups based on field values. Configure data grouping in the grouping configuration tab:

  1. Create a grouping entry with a unique grouping ID
  2. Define the fields to be used as grouping criteria in the grouping fields tab

The data grouping functionality is particularly useful for:

  • Processing related records together (e.g., all items for the same order)
  • Creating hierarchical views of flat data
  • Preparing data for reporting or batch processing
  • Organizing data before further transformation steps
tip

When defining grouping fields, arrange them in logical order from general to specific (e.g., Order Number, then Item Number) for optimal sorting and grouping results.

Integration with other UBC components​

UBC.map functions as a critical transformation layer in the UBC ecosystem, positioned as "Data to Process to Data" in the architecture. It serves as a bridge between various UBC components:

  • UBC.act: Transforms data from SAP standard or custom objects into formats needed by other components
  • UBC.flow: Provides data transformations required for workflow processing steps
  • UBC.rest: Converts between external integration formats and internal data structures
  • UBC.io: Supports cross-layer monitoring by ensuring data consistency across the platform

UBC.map handles both transactional data (such as Sales Orders, Financial Documents, Purchase Orders) and master data (Business Partners, Material Masters, Product Specifications) transformations, enabling seamless data flow throughout the system. This component is essential for maintaining data integrity while information moves between different processing stages and system boundaries.