High-Level Specification

Functional Overview

To ensure consistent and automated management of supplier records across systems, a custom integration and job scheduling solution will be implemented. This solution will:

• Automate the synchronization of supplier status data between Ariba and Icertis.
• Ensure alignment of supplier deactivation in Icertis with the current status maintained in Ariba.
• Reduce manual intervention and the risk of data discrepancies between the two platforms.
• Support compliance and operational efficiency by maintaining accurate and up-to-date supplier information across systems.

Scope and Objectives

1. Custom Time-Based Job in Icertis
   A configurable job will be implemented in Icertis to initiate the supplier deactivation synchronization process on a scheduled basis.
   The scheduled job uses a cron expression to control execution frequency and timing, allowing easy adjustments without code changes. 
2. Supplier Status Check in Ariba
   The job will connect to Ariba via API to retrieve supplier records, identify those marked as inactive, and process delta updates accordingly for synchronization.
3. Supplier Deactivation in Icertis
   Inactive suppliers identified from Ariba will be deactivated in Icertis using the Business Bulk API, ensuring data consistency, integrity, and audit traceability.

Objectives

• Automate the synchronization of supplier deactivation status between Ariba and Icertis.
• Ensure daily alignment of inactive supplier records using a configurable time-based job in Icertis.
• Retrieve and process only newly deactivated suppliers from Ariba via API to optimize performance.
• Maintain data integrity and audit traceability during supplier deactivation in Icertis.

Process Flow Diagram

Assumptions

• Supplier status (Active/Inactive) in Ariba is always up-to-date and reflects the correct business decision before synchronization.
• Job should run outside the business hours, parallel job run should be avoided to not impact the performance
• Standard Integration User and Security group is used. If the standard user or group is not available or modified, integrations may fail. No custom security roles or
  other permissions are considered in this design.
• Supplier is deactivted: - Icertis Standard Approach for existing agreements
  • If an agreement is in Draft status and the associated supplier is deactivated, the supplier may be replaced within that agreement.
  • If the agreement status is Approved or Executed, a new agreement must be created to reflect the change.
  • Similarly, if an existing agreement requires an amendment, a new agreement should be initiated rather than modifying the original.
  • Multiparty agreements: in this case the deactivated suppliers needs to be replaced or to be reactivated.

Dependencies

Not Applicable

Security, Integrity and Controls

Not Applicable

Configuration Requirements

1. Technical Configuration - Job Scheduling in Icertis
   Frequency: Daily execution (configurable to weekly or custom intervals).
   Execution Time: Adjustable to align with system maintenance windows or business hours.
   Retry Logic: Define retry attempts* and intervals for failed runs. *) Best practice is a maximum of 3 attempts.
   Notification Settings: Notifications for will be send for job failure event.
2. API Connectivity with Ariba

API Credentials: Secure storage and management of authentication tokens is ensured. Icertis securely stores all configuration data required to invoke Ariba APIs..

Endpoint Configuration: URLs for supplier data retrieval (full list and delta updates).

Special Requirements

Not Applicable

Design Rationale

• Current Gap: Supplier information is not being updated in Icertis, leading to inconsistencies in contract and vendor data.
• Integration Approach: Implement a direct API-based solution to ensure real-time and consistent updates without relying on middleware.
• Simplification Goal: Avoid additional layers of complexity by eliminating middleware.

Data Structure

Source Structure

System Roles: In this integration, SAP Ariba serves as the source and leading system for supplier status, while Icertis acts as the target system, receiving and updating supplier records based on the status maintained in Ariba.

The following field within the payload will be used to provide the required information for this interface:

Target Structure

The following field within the table ICMSupplierMaster will be used to provide the required information for this interface:

Mapping and Calculation

In this integration, the Active field from Ariba (a boolean) will be mapped to the Status field in Icertis (a string). The mapping logic is as follows:

If Active = FALSE, then Status = "Deactivated"

This transformation ensures compatibility between the data models of both systems and supports accurate status representation during synchronization

Processing Logic

Processing within Source

• Initial Full Load: Configuration for first-run logic to deactivate all inactive suppliers.
• Delta Updates: Enable incremental fetch based on last successful "TimeUpdated" timestamp.

Processing within Middleware

Not Applicable

Processing within Target

• Bulk API Settings in Icertis: Batch size limits, concurrency settings for deactivation.

• APIs Used:

  • Ariba Supplier API (for inactive supplier retrieval) : Master Data Retrieval API for Sourcing

  • Icertis Business Bulk API (for supplier deactivation) : POST/v{version}/bulk/masterdata

Ariba Supplier API (for Inactive supplier retrieval) Master Data Retrieval API for Sourcing request looks like below:

Note that this API directly filters the suppliers and provide only inactive suppliers.

curl --location 'https://eu.openapi.ariba.com/api/sourcing-mds-search/v1/prod/entities/organizations?$filter=(Active eq false and TimeUpdated gt 2025-11-25T00:00:00Z)&%24includeInactive=true' \
--header 'Accept-Language: en' \
--header 'X-Realm: 745255310-SS-T' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Your Auth Toke>' \
--header 'apiKey: VJfuIdNt5gi5DqkNOFdXMv92HWGaA81j'

The example looks like:

{
        "DynamicProfileSyncStatus": "0",
        "IsCustomer": "false",
        "MinorityOther": "",
        "MinorityNativeAmerican": "false",
        "CorporatePhone": "",
        "Name_en": "Ariba P2P Test Supplier",
        "CorporateURL": "",
        "SystemID": "sid111",
        "SystemId": "AN11228658404-T",
        "IsOrgApproved": "2",
        "AODMigrationStatus": "0",
        "OrganizationType": "",
        "TimeUpdated": "2025-10-04 00:31:30.811",
        "TimeCreated": "2025-05-25 21:17:29.899",
        "CorporateEmailAddress": "",
        "AODDataSyncScn": "0",
        "HasTradingRelationship": "false",
        "Active": "false",
        "HierarchyPath": "/CCNSAINDMDGykWJ",
        "IsSupplier": "true",
        "StateOfIncorporation": "",
        "CorporateFax": "",
        "IsManaged": "0"
}

Icertis Business Bulk API (for supplier deactivation) : POST /v{version}/bulk/actions/trigger

Sample payload:

{
  "Data": {
    "TypeOfContract": "Masterdata",
    "ContractTypeName": "ICMAccountEntityMaster",
    "JobItems": [
      {
        "RequestIdentifier": "MD123",
        "Id": "739caf5b-2c9b-4ba0-9dc7-b4cfbd0cf4b3",
        "Action": "Deactivate",
        "EndpointVersion": 2,
        "UseExternalId": true,
        "RequestBody": {
          "EntityName": "ICMAccountEntityMaster",
          "Id": "739caf5b-2c9b-4ba0-9dc7-b4cfbd0cf4b3",
          "Note": "Test Bulk Action",
          "IsPrivate": true,
          "ReasonCode": {
            "UniqueValues": [
              "763A18D2-63DB-4E39-8500-0B8BBB3697E7"
            ],
            "DisplayValue": "01",
            "ExternalId": null
          }
        }
      }
    ]
  }
}

Interface Dependency

Not Applicable.

Interface Constraints

Not Applicable.

Delivery Requirements

• Frequency: Daily execution 
• Execution Time: Adjustable to align with system maintenance windows or business hours.

Delta or Full Load Requirements

• Initial Full Load: Configuration for first-run logic to deactivate all inactive suppliers.
• Delta Updates: Enable incremental fetch based on the last successful "TimeUpdated' timestamp. Icertis will include a "SYNC" timestamp in the master data payload of the bulk API.

Interface Alert & Monitoring

No alerts are generated; however, monitoring is managed through the Error Handling process described in the dedicated section below.

Interface Reporting

Not Applicable

Language Requirements

Not Applicable

User Interface Requirements

Not Applicable

Volumetrics

• The integration job runs daily and retrieves only changes (deltas) compared to the previous run, including newly deactivated vendors.
  The Bulk API limits on ICI are 
  

  Resource Type	Max items per job
  Master Data	5000

• Process: The API queries Icertis for vendors deactivated after the last TimeUpdated timestamp. 
  If no changes occurred since the previous day, the API returns an empty set and no updates are processed.

Delta records since the last run job.

Performance Consideration

The execution of the scheduled job in Icertis should be carefully timed to avoid overlap with other system batch processes and to minimize impact during peak business hours. Scheduling should take into account system maintenance windows and existing job loads to ensure optimal performance and reliability. 
Further considerations: Ariba Rate Limit (Requests): 10/sec, 40/minute, 200/hour, 1000/day - The rate limit will consume the bandwidth for the standard MD if both share the same application.

Error Handling

SAP Ariba API Errors
If the API call to SAP Ariba fails, an error entry will be created in a designated log table within Icertis to capture details of the failure for monitoring and troubleshooting.

Icertis Bulk API Invocation Errors
If the invocation of the Icertis Business Bulk API fails, the error will be logged in the same log table to ensure traceability and support issue resolution.

Icertis Bulk API Processing Errors
If errors occur during the processing of supplier records via the Bulk API, Icertis will automatically generate out-of-the-box error logs in its standard log table, ensuring system-level traceability.

Testing

How to Test

Test Conditions and Expected Results

Test Considerations/Dependencies

Not Applicable

Other Information

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