High-Level Specification

Functional Overview

Icertis Contract Intelligence is the contract management and authoring application for Syensqo's purchase contracts. Purchase orders are created in S/4 HANA with reference to purchase contracts (outline agreements). The key information from the legal contract which is relevant for procurement forms the basis of the purchase contract or outline agreement in S/4 HANA.  For release 4, the integration between Icertis and S/4 HANA will be more complete and automated. However, for release 2 the option for a 'light' integration was decided due to the limitations of the two SAP ECC systems and in particular the substantial existing custom logic which needed to remain unaffected by any changes.

The 'light' integration consists of three main parts:

1. Maintaining the relationship between the Icertis Contract ID and the SAP outline agreement number.
2. The ability to report where there are inconsistencies in the data between the two systems.
3. The ability for users to update the Icertis Contract ID on the SAP outline agreement.

When an agreement in Icertis is executed, an event in Icertis is initiated and the stream event payload is received to CPI (Cloud Platform Integration) via API Management  (as CPI and APIM are components of Integration Suite and data flows via APIM to CPI) . CPI then uses key fields from that payload to make a call to Icertis to retrieve the complete contract record payload from Icertis. An additional call is made for some agreement types to find associations to a master agreement. A subset of the total fields provided are then mapped to fields in a custom table in both SAP ECC systems (PF2 and WP2) where the data is stored.

Events for AmendmentExecuted, AutoRenewed, Terminated and Updated require development within Icertis in order to be initiated and for a custom event job to send the default payload to CPI via API Management.

Scope and Objectives

The objective of the interface for release 2 is to provide a functional relationship between the Icertis Contract and the SAP outline agreement to enable consistency of the data to be reported and therefore maintained. The business users will manually create and change the outline agreements as a result of contract executions, amendments, renewals and contract terminations.

The entry and update of the contract data in the custom table enables:

1. Validation that the correct Icertis Contract ID is entered on the outline agreement.
2. Reporting any key header data from the outline agreement which is not aligned with the corresponding data in Icertis.
3. Enables identification of orphan outline agreements which do not have an Icertis Contract ID assigned.
4. Enables a complete reporting view of all the Icertis types of purchase contracts, their hierarchical structure along with their association to the SAP outline agreement (if relevant for assignment).

Without this integration there is no place where the hierarchical structure of Icertis Master Agreements & associated Sub Agreements and Standalone Agreements can be viewed with their association to the outline agreements in SAP ECC. It provides a mechanism to ensure the purchase contract content common to both systems remains aligned despite the reliance on manual entry by business users in SAP.

The linking of the documents in this way acts as a starting point for  data enrichment for release 4, allowing the identification of outline agreements which do not have a legal purchase contract.  The data will be the foundation for the conversion of open outline agreements in release 4.

Sequence Diagram

The sequence diagram below shows the data flow between Icertis Contract Management and SAP ECC:

The process is that events in Icertis transmit a record to CPI via API Management with ContractTypeName, SysId and ActionName.

With that information CPI makes two calls to Icertis to retrieve the agreement data and any associating instances (which exist between Sub Agreements, Supporting Agreements and their Master Agreements).  There are no other associations which are relevant to be represented in the reporting structure in SAP apart from Master Agreements.

The ActionName field in the initial event received to CPI is the key controlling information which CPI needs to complete the mapping and transformation of some fields ready for SAP.  The values in this field are:

• "Terminated" (update existing entry)
• "AutoRenewed" (update existing entry)
• "AmendmentExecuted" (update existing entry, but for the ICMParentContractId  and ICMParentEntityInstanceId)
• "Executed" (create a new entry)
• "Updated" (update existing entry)

CPI does not need to provide the ActionName to ECC. The ABAP logic in ERP-261 will determine whether to make a new entry or to change an existing entry based on whether the Agreement Code and System ID already exist in the custom table.

Call 1: To retrieve agreement details for the contract code sent in the event

GET /v{version}/agreements/{contractTypeName}/{agreementId}

If the agreement type received in the event is 'ICMSupportingAgreement' or 'ICMSubAgreement' then we must search for any Master Agreement which is an associated entity.

If ICMConfidentialContract = true, terminate processing. Contracts marked as Confidential must not be replicated to SAP ECC. 

Call 2: To retrieve the associating entity details for ICMMasterAgreement

GET /v{version}/agreements/{contractTypeName}/{agreementId}/associatinginstances/{associatingEntityName}

In the call, associatingEntityName will always be ICMMasterAgreement.

Returned will be the full details for the associated Master Agreement. 

In the case of amendments (ContractTypeName): 
ICMMasterAgreementAmendment
ICMSupportingAgreementAmendment
ICMSubAgreementAmendment
ICMStandaloneAgreementAmendment

it is not necessary to make the second call for associations as there will never be an association to a master agreement for an amendment. When an amendment is created in Icertis, any associations are not copied from the parent contract to the amendment. The master agreement remains associated to the original contract. The associations defined in the custom table for the parent contract when it was first integrated to ECC will remain unchanged when the field values from the amendment contract are updated against the parent in ECC.

Call 2 for the associating entity details is not required for ActionName "Terminated" or "AutoRenewed" as both of these update only the expiry date.

A table detailing the scenarios and the calls made from CPI for the possible combinations of ContractTypeName and ActionName is provided: 

CPI makes the necessary filters and translations required to prepare data in the format needed for the downstream interface ERP-261. 

The availability of the key Icertis purchase contract information within the SAP ECC systems then makes it possible to report outline agreements associated to Icertis contracts and to compare key data objects.

</Start CR0397>

Events for Legacy Contract Loads in Icertis

Icertis Contract Management to SAP ECC integration relies on event creation from ICertis, processing in CPI and storage in a custom table in SAP ECC. ERP-260, ERP-261, ERP-508 enable this process for new contracts created and for lifecycle events on migrated contract but not for the initial bulk loading in Icertis of legacy contract data.

A solution in Icertis to automatically create new events for each of the relevant steps in the load of legacy contracts requires changes in CPI to handle the processing of these new events.

Theoretically, the loading of legacy contract data only occurs once at the time of cutover to the new Icertis Contract Management system, and therefore these events would be used a single time. However, a possible scenario is the acquisition of a new business whose legacy contracts will be loaded into the existing Icertis system. These events would be generated from Icertis to CPI.

The table below shows the new event names which are produced in Icertis during the legacy contract loading, the action taken by CPI and the changes required in CPI.

Once the legacy contracts are loaded in Icertis, any subsequent lifecycle changes such as updates, renewals, terminations and amendments generate events in the same way as non-legacy loaded contracts.

</End CR0397>

Assumptions

It is assumed that all messages are processed in the sequence in which the events occurred in Icertis. This is to ensure that field values in the custom table remain aligned to the most recent updates in the Icertis agreement and we do not overwrite fields with previous values. Further details are provided in the Sequencing section of this document.

Dependencies

The following enhancement requests in Icertis are required to fully support the integration of the purchase contracts to the custom table in SAP ECC.

ERP-203: Icertis: Total Contract Value Calculation with Multiple Amendments 

In order to correctly fill the target value ERP-203 enhancement is being made in Icertis to consolidate the total value of the amendments. In addition to ensure the currency of the contract is passed to SAP, the logic is being adjusted so that it uses the local agreed currency instead of defaulting to EURO.

This is required in order for the target value field for the contract in the custom table to be tested in all scenarios.

ERP-508: Enhancement for Icertis Event Streams

 Configure a custom event job to send the default payload (equal to the stream event payload) to SAP CPI from Icertis. This enhancement will support the following event types:

• AmendmentExecuted

• AutoRenewed

• Terminated

• Updated*

This development in Icertis is required in order for integration to be tested for event types other than Agreement Execution.  

*Icertis Contract Management has some fields for the purchase contracts which are defined as tracking attributes. Tracking attributes are fields which can be updated directly in Icertis without creating an amendment. These are typically internal fields. Examples of these type of fields are agreement name, purchasing organization and contract owner and are held in the custom table in SAP ECC. The logic will trigger on the "update" event, only when the agreement status is "Executed", and if any of the mentioned fields have changed. In such cases, Icertis sends the default payload with the action name "Updated".

Security, Integrity and Controls

Confidential contracts are to be filtered out in CPI and must not be visible in the custom table.

There are no other specific security, integrity or controls required for the processing of the interface.

Configuration Requirements

Icertis Configuration

Configuration in Icertis for the event stream definition and activation, the Webhook URL for the API endpoint is required in order for the event notifications to be available in CPI.

Special Requirements

Confidential Contracts

Icertis contracts which are identified as confidential (ICMConfidentialContract = true) are filtered out in CPI and must not have entries made in the custom table in SAP ECC. This check and filter needs to happen in the middleware to ensure there is no trace of the confidential contract details maintained outside Icertis. ICMConfidentialContract field in Icertis is changeable, for example via an amendment.  The recommendation to contract specialists is if they need to adjust the confidential contract field they will create a new Sub Agreement instead of an amendment. The reason is that the contract contents may already have been passed to SAP (if not confidential); or may not have had an entry in the SAP table that can be changed with an amendment (if was originally confidential).

Design Rationale

CPI will take care of complex transformations and rules for the data from Icertis while the ABAP logic in the development ERP-261 System Interface - Icertis Contract Data Replication to SAP ECC will take care of minor manipulation of the data from CPI before updating the custom table.

Below is an example of the out-of-the-box payload sent from Icertis to CPI on the events:

{
	"id": "c827d613-a5a5-4c2d-9d7d-8898abd92715",
	"source": "/icertis/mycompany",
	"type": "com.icertis.mycompany",
	"data": {
		"EventHash": "6R0AQ/viamcLKQ73E4/lXNrgPaIS8xStSHP7MPDpNW8=",
		"EventMessage": {
			"EventStreamId": "f64fc1fb-0ee6-41a2-8dd3-6727363a28a5",
			"EventStreamName": "AutomationBasicAgreement-CreatedAndUpdate",
			"EventId": "65638f47-42dc-4aee-85c5-aed814705121",
			"ResourceType": "Agreement",
			"ContractTypeName": "ICMMasterAgreement",
			"ActionName": "Executed",
			"FromState": null,
			"ToState": null,
			"EventBy": "d82605cb-cf47-4427-bed4-525fe568fdd3",
			"EventDateTime": "2024-04-12T07:16:17.9661276Z",
			"ExternalId": "",
			"SysId": "35913105-9ae6-454e-aa59-ce13da70ee54",
			"CorrelationId": "6f470533-f498-4f23-acb0-764da4cc2d31"
		}
	},
	"time": "2024-04-12T07:16:23.5831003+00:00",
	"specversion": "1.0",
	"subject": "AutomationBasicAgreement-Executed"
}

Below is an example of the type of file received for the call to Icertis to retrieve the agreement information using the Contract Type Name and the System ID. The returned fields shown are just an example and are dependent on the configuration of the metadata in Icertis for Syensqo.

{
    "Messages": null,
    "Data": {
        "ICMSupplierContactName2": "",
        "ICMIsAssignment": false,
        "ICMContractTerm": 6,
        "ICMCountry": [
            {
                "UniqueValues": [
                    "E53DF3A1-CFFA-44DA-8483-7CF4F1F1A03C"
                ],
                "DisplayValue": "CN-CHINA",
                "ExternalId": null
            }
        ],
        "ICMPreferredCurrencyUniqueName": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMAribaLastSyncMessage": "Agreement sync with Ariba failed. \nICI Agreement Id: PMA78\nAriba Contract Workspace Id: \nCreate Contract Workspace Failed. Error(s): Create contract workspace api returned failure. Status Code: BadRequest Reason: [ {\n  \"errorCode\" : \"400004\",\n  \"message\" : \"[No template exists with the given template ID: CW2502]\"\n} ]\n",
        "ICMRenewalPeriod": null,
        "ICMAribaContractWorkspaceId": "",
        "ICMParentContractType": "",
        "ICMLegalEntityCountry": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "CN-China",
            "ExternalId": null
        },
        "ICMTriggerNotifications": 1,
        "ICMPartyName": "",
        "ICMAribaComplianceContractRequestId": "",
        "ICMBuyoutOptionDate": null,
        "ICMIsTermination": false,
        "ICMIsSignatureInAriba": false,
        "ICMTerminationDate": null,
        "ICMMultiParty": false,
        "ICMAribaMainAgreementDocumentId": "",
        "ICMEvergreen": false,
        "ICMAssignedParentId": "",
        "ICMExchangeRateInEuros": 50.0,
        "ICMDocuSignSignatureConsole": true,
        "ICMAribaLastSyncStatus": false,
        "ICMContractLanguage": "English",
        "ICMAmendmentAmount": {
            "Value": null,
            "Currency": ""
        },
        "ICMBusinessOwnerDepartment": "Legal",
        "ICMRenewalNoticePeriod": "",
        "ICMAribaCWIsActive": "",
        "ICMContractValue": {
            "Value": 800000.0,
            "Currency": "USD"
        },
        "ICMAribaIntegrationType": "",
        "ICMAppSrcSupplierCountry": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMLoanSyensqoequipment": false,
        "ICMTakeorPay": false,
        "ICMEffectiveDate": "2025-11-04T00:00:00",
        "ICMEarlyTerminationOption": false,
        "ICMReviewerHelpMessage": "Sample agreement",
        "ICMProjectLocation": "",
        "ICMPartyAddress": "",
        "ICMExternalSignatory2": "",
        "ICMBonusRebates": false,
        "ICMMaxRenewals": null,
        "ICMIsLegacy": false,
        "ICMAppSrcSupplierName": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "Test Supplier 11",
            "ExternalId": null
        },
        "ICMAribaCWLink": "",
        "FilePath": {
            "Content": null,
            "Name": "ICMMasterAgreement_f8a2c845-5660-93fd-3cfb-e177c59365dc_1",
            "Extension": "DOCX",
            "Path": "default:\\agreements\\ICMMasterAgreement_f8a2c845-5660-93fd-3cfb-e177c59365dc_1.Docx"
        },
        "ICMEarlyTerminationNoticeDeadline": null,
        "ICMSupplierContractEmail2": "",
        "ICMAppSrcSupplierContactName": "ABC",
        "ICMIsAmendmentRequest": false,
        "ICMNumberofExternalSignatories": "1",
        "ICMSupplierAddress3": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "Lyon",
            "ExternalId": null
        },
        "ICMNumberofInternalSignatories": "1",
        "ICMGoLiveDate": null,
        "ICMUseAmendmentTemplate": false,
        "PreviousAgreementId": "",
        "ICMIncoterms": {
            "UniqueValues": [
                "cca80b1f-d423-43ac-afc0-c683065edd99"
            ],
            "DisplayValue": "CIP - Carriage/insurance paid",
            "ExternalId": null
        },
        "ICMAribaExecutedDocumentId": "",
        "ICMBusinessOwner": "muskan.arora@accenture.com",
        "ICMLegalEntityCity": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "CHANGSHU",
            "ExternalId": null
        },
        "ICMAribaCLIDContentType": "",
        "ICMContractSubType": {
            "UniqueValues": [
                "9a853be8-201f-489f-b218-efd0aa272a45"
            ],
            "DisplayValue": "Supply of Packaging",
            "ExternalId": null
        },
        "ICMLegalEntityStreetAddress": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "18 HAI KANG ROAD HI-TECH INDUSTRIAL PARK,HAI YU TOWN",
            "ExternalId": null
        },
        "ICMLicenseTerm": "",
        "ICMCommodityL1Description": {
            "UniqueValues": [
                "af71549b-6a36-4f3a-9075-5e5598153ff7"
            ],
            "DisplayValue": "LOGISTICS",
            "ExternalId": null
        },
        "ICMAppSrcSupplierContactEmailID": "abc@gmail.com",
        "ICMLegalEntityCode": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "5991",
            "ExternalId": null
        },
        "ICMIsAssigned": false,
        "ICMTypeofLeaseTermination": "",
        "ICMTotalContractValue": {
            "Value": 0.0,
            "Currency": "EUR"
        },
        "ICMContractDescription": "Sample information",
        "ICMLegalEntityName": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "Solvay Specialty Polymers (Changshu)",
            "ExternalId": null
        },
        "ICMAribaIsBaselineContract": false,
        "ICMPricingType": "Fixed",
        "ICMPackagingSegment": "Sample",
        "ICMAribaAmendmentReason": "",
        "ICMSupplierRiskOfBankruptcy": false,
        "ICMBuyoutOptionNoticeNotificationDate": null,
        "ICMIncludesITEquipment": false,
        "ICMAribaCLIDStatus": "",
        "ICMEarlyTerminationDate": null,
        "ICMRegions": {
            "UniqueValues": [
                "5567a577-dbb3-4ffd-8f9f-8544e5f5c56e"
            ],
            "DisplayValue": "EMEA",
            "ExternalId": null
        },
        "ICMDomain": {
            "UniqueValues": [
                "cbbd6184-4096-4067-9ecd-6e6cd7c6888d"
            ],
            "DisplayValue": "Packaging",
            "ExternalId": null
        },
        "ICMAribaLastSyncTime": "2025-11-05T18:01:33",
        "ICMCommodityL2Description": {
            "UniqueValues": [
                "1a604add-20e4-4df9-bcf6-b98514692707"
            ],
            "DisplayValue": "LO-COLD STORAGE (RE)PACKING SERVICES",
            "ExternalId": null
        },
        "ICMAmendmentEffectiveDate": null,
        "ICMPrimaryOwnerEmail": "clmadmin@waadicm.onmicrosoft.com",
        "ICMSupplieraccessSYENSQOSystems": false,
        "ICMEarlyTerminationNoticeNotificationDate": null,
        "ICMIsthisaIFR16Contract": false,
        "ICMAppSrcSupplierStreetZip": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMAribaBaselineContractId": "",
        "ICMAribaCWLastModifiedDate": null,
        "ICMTaxExempt": false,
        "ICMAribaCWAutoPublishJobId": "",
        "ICMCostbenefitfruition": "As credit note",
        "ICMArbitrationChamber": {
            "UniqueValues": [
                "e4d200bb-27bd-4b0c-996c-4c1e6d522b38"
            ],
            "DisplayValue": "Shanghai International Arbitration Center",
            "ExternalId": null
        },
        "ICMAribaTemplateId": "CW2502",
        "ICMTemplate": {
            "Name": "Frame Agreement for the Supply of Packaging_Master Agreement",
            "Version": "1",
            "Extensions": null
        },
        "ICMBusinessRegion": "APAC",
        "ICMIsTestProject": false,
        "ICMIsAmendment": false,
        "ICMTerminatedParentId": "",
        "ICMAribaCLIDDocumentId": "",
        "ICMExternalSignatory3": "",
        "ICMContractOwner": "clmadmin@waadicm.onmicrosoft.com",
        "ICMIsthisComplexContract": false,
        "ICMPrimaryOwnerName": "CLM Admin",
        "ICMORGAxis": [
            "Composite Materials"
        ],
        "ICMAribaInboundLastSyncTime": "2025-11-04T11:30:56",
        "ICMAppSrcSupplierState": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMServicesDescription": "Sample information",
        "ICMAribaIsExecutedPaper": false,
        "ICMSupplierAccessExportControlData": false,
        "ICMPaymentTermsDescription": {
            "UniqueValues": [
                "2e468649-93da-4afb-97d2-5fd54d4f8d85"
            ],
            "DisplayValue": "120 D end of month from invoice date",
            "ExternalId": null
        },
        "ICMAribaInternalId": "",
        "ICMAribaInboundLastSyncMessage": "Agreement successfully initialized with Ariba details. \nICI Agreement Id: PMA78\nICMAribaSourcingEventId: \nCLID Sync Status : Not Applicable \nContract Team Sync Status : Not Applicable",
        "ICMNumberofRenewals": null,
        "ICMAribaHierarchicalType": "StandAlone",
        "ICMExpiryDate": "2026-05-30T00:00:00",
        "ICMTerminationNoticeDate": null,
        "ICMIsExecutedWithoutSignedCopy": false,
        "ICMInternalSignatory": {
            "UniqueValues": [
                "7e2a69b7-a1c1-44c7-bbb8-6078ecd2f33f"
            ],
            "DisplayValue": "amit.baviskar-ext@syensqo.com",
            "ExternalId": null
        },
        "ICMGoverningLaw": {
            "UniqueValues": [
                "ba6a64b2-6a65-47a3-b63d-7b3a263b1993"
            ],
            "DisplayValue": "Laws of PRC",
            "ExternalId": null
        },
        "ICMAribaAmendmentType": "",
        "ICMSupportServicesApply": "",
        "ICMExternalSignatory": "poojapisal072@gmail.com",
        "ICMAppSrcSupplierAddress": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "Lyon",
            "ExternalId": null
        },
        "IsLocked": false,
        "ICMAribaInboundLastSyncStatus": true,
        "ICMBuyoutOptionNoticeDeadline": null,
        "ICMProcessPersonaldata": false,
        "ICMICMReferenceKey": "",
        "LockedByUser": "",
        "ICMInternalSignature3": {
            "UniqueValues": [],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMSupplierAddress2": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "Lyon",
            "ExternalId": null
        },
        "ICMParentContractId": "",
        "ICMRenewal": false,
        "ICMInternalSignature2": {
            "UniqueValues": [],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMAribaExpirationTermType": "Fixed",
        "ICMSignatureType": "Electronic Signature",
        "ICMApproverHelpMessage": "Sample agreement",
        "ICMInstallEquipment": false,
        "ICMPreliminaryIntegrationServiceApply": "",
        "ICMIncotermsCode": {
            "UniqueValues": [
                "cca80b1f-d423-43ac-afc0-c683065edd99"
            ],
            "DisplayValue": "CIP",
            "ExternalId": null
        },
        "ICMAribaIsPreAwardContract": false,
        "ICMConfidentialContract": true,
        "ICMSignatureSequence": "External First",
        "LockedByUserId": "",
        "ICMAribaCWVersion": "",
        "ICMNumberofThirdParties": null,
        "ICMLegalEntityState": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "Jiangsu",
            "ExternalId": null
        },
        "ICMAppSrcSupplierID": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "SID1234",
            "ExternalId": null
        },
        "ICMNumberofSuppliers": "1",
        "ICMBuyoutAmount": {
            "Value": null,
            "Currency": ""
        },
        "ICMSAPAribaDefaultCurrency": "",
        "ICMContractValueinEuros": {
            "Value": 40000000.0,
            "Currency": "EUR"
        },
        "ICMOrgTeam": "Composite Material",
        "ICMBuyoutOption": false,
        "ICMVenue": {
            "UniqueValues": [
                "f941c9de-d713-4e27-9550-773fb944adb5"
            ],
            "DisplayValue": "Shanghai (PRC)",
            "ExternalId": null
        },
        "ICMAribaCWStatus": "",
        "ICMOrgAxisGBU": {
            "UniqueValues": [
                "b96ac447-b959-467f-8cd2-0f63e3176316"
            ],
            "DisplayValue": "COMPOSITE MATERIALS",
            "ExternalId": null
        },
        "ICMTakeorPayAmount": null,
        "ICMLegalEntityZIPCode": {
            "UniqueValues": [
                "3d037081-709b-438c-9acc-970fbcf49b37"
            ],
            "DisplayValue": "215522",
            "ExternalId": null
        },
        "ICMIFR16Comments": "",
        "ICMAgreementCode": "PMA78",
        "ICMAribaAsyncAction": "",
        "ICMDataOutsideEEA": "No",
        "ICMProjectID": "Sample Agreement",
        "ICMSite": [
            {
                "UniqueValues": [
                    "35C92D5B-DF46-4998-96A5-F80864D005F2"
                ],
                "DisplayValue": "CN026-CHANGSHU",
                "ExternalId": null
            }
        ],
        "ICMIndexType": "",
        "ICMBidwaiverformrequired": false,
        "ICMExternalId": "",
        "ICMOtherBusinessOwner": "pooja.piscal-ext@syensqo.com",
        "ICMIncotermslocation": "India",
        "Name": "MA_04-11",
        "ICMAppSrcSupplierCity": {
            "UniqueValues": [
                "543d6dd7-c04b-4276-b8d3-8b583e2c9acc"
            ],
            "DisplayValue": "",
            "ExternalId": null
        },
        "ICMCLIDLineItems": null,
        "ICMSubAgreement": null,
        "ICMCertificates": null,
        "ICMMASupportingDocuments": null,
        "ICMCLIDFile": null,
        "ICMSupplierContracts": null,
        "ICMSupportingAgreement": null,
        "ICMBidWaiverForm": null,
        "ICMTerminationAgreement": null,
        "ICMMasterAgreementAmendmentCollection": null,
        "BusinessStatus": "Draft",
        "TypeOfPaper": "Own",
        "IsPublished": true,
        "IsDeviated": false,
        "Status": "Draft",
        "CreatedBy": "clmadmin@waadicm.onmicrosoft.com",
        "CreatedDate": "2025-11-04T11:30:40",
        "ModifiedBy": "clmadmin@waadicm.onmicrosoft.com",
        "ModifiedDate": "2025-11-05T08:17:00",
        "ParentContractTypeName": null,
        "ExtendedStatus": null,
        "SysId": "f8a2c845-5660-93fd-3cfb-e177c59365dc",
        "TypeOfContract": "Agreement",
        "ContractTypeName": "ICMMasterAgreement",
        "OrgPath": "/syesnqo/procurement/procurement contracts"
    },
    "HasMoreData": false,
    "PagingData": null
}

Data Structure

Source Structure

The following fields from Icertis are required for the content of the custom table in SAP, or to support the interface process. The exact sequence of the fields in the returned JSON files for each contract type is unknown at the time of writing and there will be many more fields in the file than those specified below.

"2024-04-12T07:16:17.9661276Z"

Target Structure

The fields defined in the target structure below will be the structure of the custom table in SAP ECC, named ZMM_ICMCONTRACT.

Validation

Although some of the Icertis fields correspond directly to fields in SAP, it is not possible to use these fields for validation due to the two separate SAP ECC systems. The intention is to have the same content filled in the custom table in both systems, regardless of whether the company code, purchasing organization, supplier etc. are defined in that system. All fields therefore have to be text-based fields unless otherwise specified.

Field Definitions

Field labels and field names are to correspond with the Icertis field labels and field names. It is understood there is a limit of 30 CHAR in SAP for a table name and all named fields are below the limit.

Parent Entity Instance ID and Parent Contract are not relevant to store in the custom table. The situation where these fields are filled from Icertis is when the Agreement Type is an amendment. These will only be used in the middleware to determine which entry in the custom table requires updating.

Note: For clarity, the field System ID is not a 'system identifier', it is a unique 36 char code which is held in Icertis as a unique code for an agreement code. This is not the agreement code which the users see, but it is the code that represents the agreement in the database and it will need to be stored in SAP ECC.

Table Entries in Target SAP ECC

Icertis Amendments will not be stored directly in the custom table. Amendment events received will make the call to Icertis to obtain the amendment contract data, but the update of the table entries with the values retrieved will be made for the Parent Contract and Parent Entity Instance ID.

The key of the table will be Tenant ID, Contract Type Name, System ID and Agreement Code  which will form a unique record.  The two fields used for the calls to Icertis, are Agreement Type and System ID which form a unique record in Icertis. The key fields will be available for all events and will be considered mandatory in the table, whereas all other fields are optional entry. Agreement Code will be a unique record in its own right, but cannot be used alone as the database uses Agreement Type and System ID.
It is important to note that for Master Agreements, purchasing organization is not available for entry in Icertis and a 'blank' value will be passed for this field to SAP ECC. 

One Icertis Agreement to One ZMM_ICMCONTRACT Entry

An Icertis contract can be defined for use by multiple purchasing organizations. The field in Icertis is defined for multiple selection and represents the organizations for which an operational outline agreement will be created in SAP. In SAP, an outline agreement is defined for a single purchasing organization. This means that for one Icertis Agreement Code there will be one outline agreement for each purchasing organization. 

The field ICMPurchasingOrgCode is provided to CPI with all the values in a single field separated by commas. This will be held in the custom table in SAP in a single field in the same format (values separated by commas).  

For the 'Execution' event, one new entry is created in the table. For the other events AmendmentExecuted, AutoRenewed, Terminated & Updated the existing table entry for TenantID, ContractTypeName, SysId, ICMAgreementCode, is updated.

• AmendmentExecuted

• AutoRenewed

• Terminated

• ExecuteUpdated

It was considered whether the individual values for purchasing organization could be stored separately resulting in a row in the custom table for each purchasing organization. This would have required purchasing organization to be part of the key of the table to keep unique entries. Due to the way purchasing organization can be changed in Icertis, there are technical limitations for the accurate updating of the multiple rows. Instead, the individual values will be stored with the System ID in an additional table to be available for reporting. The original value in the purchasing organization field from Icertis will be all the values separated by commas. This will be stored in the custom table for reference but not reported.

"2024-04-12T07:16:17.9661276Z"

Mapping and Calculation

Note:  Icertis has many text-based fields ranging from 224 to 1000 chars which are able to be input by users. We cannot control that the contents will fit into a fixed length field on the target system.

Field lengths for the custom fields in SAP ECC will correspond to the length of the fields in Icertis unless specified otherwise. In those cases where the ECC field is smaller than the Icertis field, it is known that the field values will fit in the defined length.

Important:  The ActionName field in the initial event received to CPI is to be passed in the target structure to SAP ECC so the value of the most recent message for the agreement is stored. This will assist in traceability of the changes to field values in the table. The ABAP logic determines whether to update an entry or create a new one based on the existing entries rather than the ActionName itself.

The possible values for ActionName are:

"Terminated" (update existing entry)
"AutoRenewed" (update existing entry)
"AmendmentExecuted" (update existing entry, but for the ICMParentContractId  and ICMParentEntityInstanceId)
"Executed" (create a new entry)
"Updated" (update existing entry)

The payload of the agreement data from Icertis is expected to have many more fields than what are relevant to store in the custom table in SAP ECC. CPI will filter out the fields which are not required to be stored in SAP or used in the determination of field values.

Icertis field contents are not case-sensitive.  

Processing Logic

Processing within Source

There is no processing requirement to be carried out in the Source System Icertis.

Processing within Middleware

All processing within CPI is defined in the mapping sheet.

Processing within Target

ERP-261 is the target interface being called by this integration process. 

Interface Dependency

There are no dependent interfaces identified which require processing prior to this interface.

Interface Constraints

There are no constraints identified.

Delivery Requirements

The delivery requirements are expected to be as close to real time as possible, allowing just for processing time.

The triggering events from Icertis are received to CPI via API and is a push of the event information. There is then a pull of the contract information from Icertis by CPI based on the event data provided in the initial payload.

Sequencing

The sequencing of the messages for the same contract from Icertis to CPI and to SAP is important in some scenarios. In most cases there will usually be a lengthy time between messages for the same SysId (Icertis Contract Id) because it takes time to execute a contract or to execute an amendment. It is possible for some fields on the original Icertis contract to be updated directly (without an amendment) and technically, multiple messages for the same contract could come through in rapid succession.  Processing these types of messages out of sequence could result in overwriting values in the custom table and cause an inconsistency in the data between the two systems. This is, however, likely to only be possible in the event of an outage of the CPI system.

Icertis processes the event messages in the sequence in which they occurred and likewise, CPI will process the messages it receives from ICertis in the order they were received. In CPI, each event message is processed and completed, with calls to Icertis successfully completed before processing the next event. 

In the event of a system outage of CPI, there is the potential for multiple event messages to be queued up on the Icertis side and in various schedules for retries. There is the possibility for these to be processed out of sequence. Currently there is no mechanism in Azure Event Grid to prevent this and to guarantee strict delivery order. It is unlikely that there will be multiple messages for the same contract unless multiple tracking attribute updates were made in quick succession during a system outage of CPI. Tracking attribute fields are always internal fields and present a low impact if they are updated out of sequence. In summary the risk of this happening is very low, and the impact is also low.

Delta or Full Load Requirements

This flow is triggered for each relevant event in ICertis, for the contract that generated the event. 

Interface Alert & Monitoring

The following will be monitored:

• API endpoints are available to view all event details, including events that were successfully processed, those that failed, and those currently in the queue.
• Failures on inbound processing and outbound side need to be handled. Please refer to the Error Handling section for error management in both Icertis and CPI.
• Messages are processed in reasonable time to ensure that the custom table record in SAP ECC is available for the business user when they go to create the outline agreement.  This is expected to be immediately after the execution of a new contract or the triggering of the relevant event, and will appear to happen in real time.

Interface Reporting

There are no specific reporting requirements identified to support this interface.

Language Requirements

There are no specific language requirements. The contract content from Icertis is predominantly text based and will therefore be shown in the language it which it was entered in Icertis.

User Interface Requirements

There are no requirements for any user interface associated with this interface. The only interaction with users will be via the consolidation report being delivered via Business Warehouse.

Volumetrics

Approx. 3,000 contracts will exist at the point of go-live. 

It is estimated that fewer than 100 new contracts are created or changed each day. This System Interface would be called for each relevant change. 

Performance Consideration

Response time is less important as this interface is triggered as a background process, and not visible to users. However, the interface should operate in near-real-time to avoid delays. 

Error Handling

Icertis Messages to CPI

Icertis event messages on execution of a contract or contract changes are handled by Azure Service Bus which is the message broker that facilitates communication between Icertis and CPI. Azure Service Bus queues store the messages until the receiving application is ready to receive and process them. Azure Event Grid has the webhook details and includes pre-defined rules for retrying of message. In the case of CPI being temporarily down, Event Grid will retry for up to 24 hours (up to 30 times), usually at exponentially increasing waiting times across the duration to resend the event messages. These rules for error handling and retrying are defined within Azure Event Grid and are not customizable for Syensqo. Events remain available until the 24-hour time period expires.

In the event of errors, alert messages are provided by Azure and include the ability to see the error details and the contents of the failed message.

If a message is still failed following all the retries, Azure Event Grid sends the message to the Dead Letter Queue and issues alerts. There is no reprocessing of the message from here, but the full contents are available. The message is marked with a failed status. The recovery process from an Icertis event message in the Dead Letter Queue would be to look up the Icertis Contract details and request for the table entries in ECC to be manually created or updated.

CPI Calls to Icertis

If CPI receives an error response from Icertis when calling for the Agreement details or Associations, it will retry the messages in sequence. There is a defined schedule for retries and the waiting period between attempts increases exponentially until the end of the defined time period. Any message still in error at the end of the allocated time will be sent to the Dead Letter Queue. Alerts are provided for any error messages and the full payload contents are available. There is no reprocessing of the message from the Dead Letter Queue and the recovery for these would be a request for the table entries in ECC to be manually created or updated.

Errors in the calls to Icertis are only expected in the event of a technical communication issue or a system outage for Icertis. It is generally expected that these errors would be resolved based on the alerts received, before the message was placed in the Dead Letter Queue.

Testing

How to Test

In order to unit test the interface, the events will have to be initiated in Icertis for the execution of new contracts, execution of amendments, renewals, terminations and tracking attribute field updates.

This is dependent on the metadata having been configured in Icertis, and on developments in Icertis mentioned previously.

Z-table entries can be reset manually in order to reuse payloads from Icertis.

Test Conditions and Expected Results

</Start CR0397>

Testing Scenarios

Testing of the changes need to be carried out in conjunction with the ERP-261 changes in order to see the correct results received into SAP ECC.

</End CR0397>

Test Considerations/Dependencies

Considerations and dependencies for testing:

ERP-203 Icertis: Total Contract Value calculation with multiple amendments to enable ECC Integration needs to be completed in order for the target value to reflect the total of all amendments and the original contract target value.

ERP-508 Enhancement for Icertis event streams need to be completed in order for the events for renewals, terminations, amendments to be generated from Icertis and send the initial payload to CPI.

Configuration of metadata is required to be completed in Icertis.

Other Information

There is no other information identified.

Development Details

Package

Other Development Objects

 Support Components/Dependencies.

Security Material

Appendix

See also

Change log