High-Level Specification

Functional Overview

The objective of this specification is to create a custom integration that facilitates the transmission of Currency Exchange Rate Master data from SAP ECC (PRS, PF2-050) to Icertis so that currency exchange rates can be synchronized smoothly.

The integration ensures that Icertis always has up-to date currency and exchange-rate information essential for contract calculations and validations. This process performs the following functions.

• Receives currency and exchange-rate data from SAP ECC (PRS, PF2-050) through the ERP-110 Interface.
• Maps and transforms the data to align with the structural and validation requirements of the Icertis APIs.
• Orchestrates the end-to-end data flow, including transmission, response handling and error management.

This integration is triggered daily through a job scheduled in ECC to ensure that Icertis consistently receives the most recent exchange-rate information required for contract evaluation and processing.

Scope and Objectives

• Scope:
  This request covers the end-to-end integration required to transform and create/update currency exchange rate data flowing from SAP ECC (PRS, PF2-050) to Icertis. It includes the middleware logic, data mapping, orchestration, and exception handling necessary to ensure accurate and reliable data transmission.
• Objectives:
  • Automate the transfer of currency and exchange rate data from SAP ECC(PRS, PF2-050) to Icertis.
  • Ensure that the data is transformed and mapped according to Icertis API specifications.
  • Handle exceptions, retries and monitoring to ensure the process runs reliably.

Process Flow Diagram

Assumptions

• SAP ECC (PRS, PF2-050) serves as the authoritative source for clean and validated currency and exchange rate data.
• Icertis APIs for currency master data ingestion are fully configured, available, documented, and accessible for integration.
• The middleware platform SAP CPI, reliably supports secure API communication, comprehensive error handling, and transaction-level logging.
• Performance benchmarks are satisfied, ensuring that data transfers complete successfully within the defined batch processing window.

Dependencies

• ERP-110 (Source system interface) and ERP-290 (Target system interface) must be available and operational to facilitate seamless data exchange. 
• Currency and exchange-rate data in SAP ECC(PRS, PF2-050) must be updated in timely manner to ensure accuracy and consistency.
• Scheduled batch job execution in SAP ECC (PRS, PF2-050) must be maintained to support timely data extraction and transmission

Security, Integrity and Controls

• Secure authentication mechanisms are in place at middleware for access to both SAP ECC(PRS, PF2-050) and Icertis systems:
• Secure HTTPS protocol is used for all data transfers between the middleware and SAP ECC, ensuring encrypted communication and protection against unauthorized access.
• OAuth 2.0 authentication is implemented for accessing Icertis APIs via an Azure-registered application, providing token-based security and controlled access
• Audit logging captures all integration transactions, including timestamps, request/response metadata, and error details for traceability and compliance.

Configuration Requirements

• Azure Application Registration

  • Since Icertis relies on Azure Active Directory as its identity provider (IdP), an application must be registered in Azure to enable OAuth 2.0 token generation and validation. This establishes trusted access between the middleware and the Icertis APIs.

  • The application registration includes defining the client ID, client secret, scope, and API permissions required to access the Icertis endpoints.

Design Rationale

This interface is designed to enable seamless integration between SAP ECC (PRS, PF2-050), source system and Icertis the target system for currency and exchange-rate master data. The middleware orchestrates the data flow, ensuring accurate mapping, necessary transformation, and reliable end-to-end delivery.

Data Structure

Source Structure

The following fields will be used to define the required data structure of the interface:

Schema File: ExchangeRateSchemaECC.xsd

Sample Extract from SAP ECC (PRS, PF2-050):

0.8700000000

0.6600000000

The currency conversion data generated by ERP-110 contains all exchange rates. Since Icertis requires only EUR-based rates, CPI filters and extracts only the EUR Direct conversion rates.

<?xml version="1.0" encoding="UTF-8"?>
<ExchangeRates xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ExchangeRate>
        <FromCurrency>USD</FromCurrency>
        <ToCurrency>EUR</ToCurrency>
        <RateIdentifier>USD:EUR</RateIdentifier>
        <ValidFrom>2025-11-10</ValidFrom>
        <Rate>0.8700000000</Rate>
    </ExchangeRate>
    <ExchangeRate>
        <FromCurrency>SGD</FromCurrency>
        <ToCurrency>EUR</ToCurrency>
        <RateIdentifier>SGD:EUR</RateIdentifier>
        <ValidFrom>2025-11-10</ValidFrom>
        <Rate>0.6600000000</Rate>
    </ExchangeRate>
</ExchangeRates>

Target Structure

HasMoreData

Mapping and Calculation

Transformation in CPI (Icertis required format):

HasMoreData

For retrieving the existing currency exchange rate data from Icertis,

below GET API is used

https://{icertis api host name}/api/v1/masterdata/{contractTypeName}

where contractTypeName = ICMCurrencyConversion.

For updating the currency exchange rate master data, the following BULK update API is used 

https://{icertis api host name}/api/v1/bulk/masterdata.

The sample request body for the Icertis bulk upsert is as below.

{
    "Data": {
        "JobItems": [
            {
                "SysId": "96c08d87-3c89-4b7d-b075-e360bb41db07",
                "UseExternalId": "false",
                "NextState": "",
                "EndPointVersion": "3",
                "RequestIdentifier": "1",
                "RequestBody": {
                    "ICMFromCurrency": "USD",
                    "ICMRate": "0.8700000000",
                    "Name": "USD:EUR",
                    "ICMToCurrency": "EUR"
                }
            },
            {
                "SysId": "5449222c-3d3a-4044-baae-a17165381ed1",
                "UseExternalId": "false",
                "NextState": "",
                "EndPointVersion": "3",
                "RequestIdentifier": "2",
                "RequestBody": {
                    "ICMFromCurrency": "SGD",
                    "ICMRate": "0.6600000000",
                    "Name": "SGD:EUR",
                    "ICMToCurrency": "EUR"
                }
            }
        ],
        "HasMoreData": "false",
        "ContractTypeName": "ICMCurrencyExchangeRate"
    }
}

Processing Logic

• SAP CPI receives the inbound currency exchange rate file from SAP ECC (PRS, PF2-050)
• CPI filters exchange rate records with EUR target (To Currency) currency.
• It applies the transformation rules, including mapping the source fields to the target structure required by the Icertis API. 
• The processed data is transmitted to the Icertis API, using secure OAuth2 communication. 
• If any error occurs during transformation or routing, CPI logs the issue and stops further processing.
• The interface follows a full-load approach, either the entire batch is successfully processed or the batch is rejected in full.

Language Requirements

• No multilingual support required for exchange rate data.

Delta or Full Load Requirements

The integration processes all records as a complete batch; if any issue occurs, the entire batch is rejected

Interface Alert & Monitoring

• Alerts should be configured for:
  • API failures
  • Validation errors
• Monitoring tools (middleware logs) should notify:
  • Integration support team
  • Business users (email)
• Retry logic should be in place for transient failures.

User Interface Requirements

Not Applicable

Volumetrics

A daily load of approximately 70 currency pairs will be created or updated in bulk. The initial load will create the currency exchange master data, and all subsequent loads will update the existing master data

Performance Consideration

Scheduling and Execution Window

• Given that the interface processes only around 70 records, no performance impact is expected.

Error Handling

The interface incorporates robust error-handling and monitoring to ensure reliable data processing between SAP ECC and Icertis. If any failure occurs during data load, transformation, or API communication, the entire batch is rejected to maintain data integrity.

Errors are logged with detailed information, and automated alerts are sent to the integration support team for prompt action.

In the event of an error, the subsequent day’s scheduled job will update the latest currency exchange rates.

Testing

Test Conditions and Expected Results

Test Considerations/Dependencies

Development Details

Package

Other Development Objects

Appendix

See also

Insert links and references to other documents which are relevant when trying to understand this decision and its implications. Other decisions are often impacted, so it's good to list them here with links. Attachments are also possible but dangerous as they are static documents and not updated by their authors.

Change log