| Status | |
|---|---|
| Owner | ROWLINSON-ext, Kerry |
| Stakeholders | |
| Jira Request ID | |
| Jira Development ID |
| Implementing System | SAP ERP (PF2) & SAP ERP (WP2) |
|---|---|
| Invoked by | ERP-260 |
| Business Process Reference | 03.04.04.01. Manage Outline Agreements (R2) |
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 more 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:
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 interface ERP-260. 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. Based on the information received from Icertis in those calls confidential records are filtered out; fields not required are ignored; and some field values are translated.
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. New contracts which are executed in Icertis and which are relevant for storing in the custom table will have a new entry made. Amendments, renewals and terminations require existing table entries to either be updated or first deleted and then re-created.
The purpose of this functional specification is to provide the details of the ABAP logic in SAP ECC which takes the field values from CPI and enables placement of the entries into the custom table.
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:
The purpose of this specification is to define the logic of the custom ABAP program which will take the data received from Icertis and make the necessary entries in the custom table in SAP ECC.
Both ECC systems have the same custom table and the same entries. For this reason the data cannot be validated against the actual SAP field values as the values are not consistent between the systems.

This system interface is invoked for a number of different events in ICertis, which are listed below. Events raised by ICertis are received by CPI Integration Process ERP-260, and forwarded to the System Interface described in this document.
| Event in ICertis | Resulting action in SAP ECC |
|---|---|
A purchase contract is executed in Icertis:
| New entry in custom table for the Icertis Contract Integration automatically creates the Icertis Contract record in custom table in both SAP ECC systems (WP2 & PF2) with the Tenant ID, Agreement Type, System ID, Icertis Agreement Code and the relevant data fields from the contract header. Purchasing Organization values and the System ID are stored in a separate custom table. |
| An amendment for an existing contract is executed in Icertis. | Change entry in custom table for the parent contract of the amendment. The existing entry in the table for the parent agreement of the amendment is located and all the relevant fields in the table are overwritten with the values provided in the amendment. Purchasing Organization values for the System ID are overwritten in a separate custom table. |
| An existing purchase contract in Icertis is renewed automatically when the renewal date comes due, which in turn updates the validity end date. | Update the existing entry in the table for the purchase contract to reflect the changes to the validity end date. |
| An existing purchase contract in Icertis is terminated which updates the validity end date and the status in Icertis. | Update the existing entry in the table for the purchase contract to reflect the change to the expiry date. |
| Changeable fields (tracking attributes) are updated in an existing purchase contract in Icertis | Update the existing entry in the table for the purchase contract to reflect the changes to the fields. Purchasing Organization values for the System ID are overwritten in a separate custom table. |
There are no specific assumptions identified.
This development will be called by integration development ERP-260.
No confidential agreements (ICMConfidentialContract='true') are to be stored in the custom table. These are filtered out in interface ERP-260 so there is no trace of them in the custom table in ECC.
There are no configuration requirements.
As the interface is one-way from Icertis to SAP ECC there are no special requirements or authentication considerations to take into account.
Other custom tables in SAP ECC do not have any authorization controls apart from transaction code. This custom table does not require a transaction as it is not subject to manual maintenance as part of the processes. However, for the integrity of the interface manual maintenance will be prevented for business users who currently have table maintenance access via SM30.
Support users may need in exception cases to maintain the table entries manually (for example, any issues at go live, or faults with the automated table updates whilst the fault is being remediated). To facilitate this, an authorization group will be assigned to the custom table. Edit access for this authorization group will only be applied to the support users. It will also enable the development team for this enhancement to reuse payloads from Icertis during unit testing by maintaining the table entries.
The CPI interface ERP-260 will take care of complex transformations and rules while the ABAP logic in this development will take care of the following types of manipulation of the data from CPI before updating the custom table:
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.
The following fields will be used in table ZMM_ICMCONTRACT to provide the required data structure of the interface:
| Field | Description | Mandatory (Y/N) | Data Type - SAP ECC lengths |
|---|---|---|---|
| TENANTID | Tenant ID | Y | 20 CHAR (3 CHAR in ECC with view and coded values) |
| EVENTDATETIME | Event Date Time | Y | 30 CHAR |
| CONTRACTTYPENAME | Contract Type Name | Y | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| SYSID | System ID | Y | 36 CHAR in ECC |
| ICMAGREEMENTCODE | Agreement Code | Y | 224 CHAR (25 CHAR in ECC) |
| ICMPURCHASINGORGCODE | Purchasing Org Code | Y | 1000 CHAR (224 CHAR in ECC) Note: In the case of master agreements, no purchasing org will be passed from Icertis. Can be left blank in ECC table. Field in Icertis is multi value and all values will be passed in this field with each 4 CHAR code separated by a comma. To be stored with the System ID and the separated values in a different custom table. |
| ICMCONFIDENTIALCONTRACT | Confidential Contract | N | 5 CHAR (1 CHAR in ECC with value selected or not) |
| NAME | Agreement Name | N | 1000 CHAR (First 255 CHAR in ECC) |
| ASSOCIATINGTYPE | Associating Agreement Type | N | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| ASSOCIATINGCODE | Associating Agreement Code | N | 224 CHAR (25 CHAR in ECC) |
ASSOCIATINGSYSID | Associating System ID | N | 36 CHAR (36 CHAR in ECC) |
| ICMAPPSRCSUPPLIERID | Bidders/Supplier SAP ID | N | 224 CHAR (10 CHAR in ECC) |
| ICMEFFECTIVEDATE | Effective Date | N | DATE |
| ICMEXPIRYDATE | Expiry | N | DATE |
| ICMTOTALCONTRACTVALUE | Total Contract Value | N | INT(15 including 2 decimals) |
| ICMCURRENCY | Supplier Currency | N | 5 CHAR |
| ICMLEGALENTITYCODE | Syensqo Legal Entity Code | N | 1000 CHAR (4 CHAR in ECC) |
| ICMORGTEAM | Org Team | N | 1000 CHAR (25 in ECC) |
| ICMPRIMARYOWNERNAME | Primary Contract Owner | N | 224 CHAR (100 CHAR in ECC) |
| ICMINCOTERMSCODE | Incoterms Code | N | 224 CHAR (3 CHAR in ECC) |
| ICMINCOTERMSLOCATION | Incoterms Location | N | 1000 CHAR (70 CHAR in ECC) |
| ICMPAYMENTTERMS | Payment Terms | N | 224 CHAR (4 CHAR in ECC) |
The table below shows the rule instruction for each field in table ZMM_ICMCONTRACT:
| Field | Rule Type | Rule Instruction |
|---|---|---|
| TENANTID | Coded Values | For the development system: source: "/icertis/syensqo-dev" Create a view for these values and assign a 3 CHAR code of DEV, UAT, PRD to each, with the description holding the full value. |
| EVENTDATETIME | None | 30 CHAR in ECC, direct mapping EventDateTime": "2024-04-12T07:16:17.9661276Z |
| CONTRACTTYPENAME | Coded Values | Possible values are: Create a view for these values and assign a 3 CHAR code of 001, 002 etc. for each; these coded values will be used in the custom table. For reporting, the original values can be displayed. |
| SYSID | None | 36 CHAR in ECC, direct mapping (keep upper/lower case) |
| ICMAGREEMENTCODE | Remove spaces and limit length | 224 CHAR (25 CHAR in ECC) Values will be in this format where nnnnn starts at 1, 2, 3 etc.: Remove spaces from the field value provided from CPI/Icertis |
| ICMPURCHASINGORGCODE | Remove spaces, and limit the length. Separate the individual values. | Icertis provides for purchasing organization to be multi-select. Where there are multiple values, they will be provided separated by commas. Remove any spaces from the beginning and end of the value sent. Split out the individual values (which will be 4 character codes) 1000 CHAR (224 CHAR in ECC) Split the values in the field provided into separate purchasing org codes and store them in a separate table with the SYSID. Whenever a record is received, all entries in this purchasing org/SysId table are overwritten for the SYSID. |
| ICMCONFIDENTIALCONTRACT | Convert to single value on/off | Convert the ICertis values of 'true' and 'false' to a single character selected/deselected. Note: There will never be an entry in the table for a confidential contract as they will be filtered out in CPI. |
| NAME | Remove spaces and limit length | 1000 CHAR (First 255 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered; then take only the first 100 CHAR of the contents |
| ASSOCIATINGTYPE | Coded Values | Possible values are: Create a view for these values and assign a 3 CHAR code of 001, 002 etc. for each; these coded values will be used in the custom table. For reporting, the original values can be displayed. |
| ASSOCIATINGCODE | Coded Values | 224 CHAR (25 CHAR in ECC) Values will be in this format where nnnnn starts at 1, 2, 3 etc.: |
ASSOCIATINGSYSID | None | 36 CHAR (36 CHAR in ECC) - direct mapping |
| ICMAPPSRCSUPPLIERID | Remove spaces and limit length | 224 CHAR (10 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered (there should be no more than 10 CHAR remaining) |
| ICMEFFECTIVEDATE | None | Format in Icertis is YYYY-MM-DDTHH:MM:SS CPI will remove the HH:MM:SS and 'dashes' to provide to SAP as YYYYMMDD |
| ICMEXPIRYDATE | None | Format in Icertis is YYYY-MM-DDTHH:MM:SS CPI will remove the HH:MM:SS and 'dashes' to provide to SAP as YYYYMMDD |
| ICMTOTALCONTRACTVALUE | None | INT(15 including 2 decimals) - direct mapping |
| ICMCURRENCY | None | 5 CHAR - direct mapping |
| ICMLEGALENTITYCODE | Remove spaces and limit the length | 1000 CHAR (4 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered (there should be no more than 4 CHAR remaining) |
| ICMORGTEAM | Remove spaces and limit the length | 1000 CHAR (25 CHAR in ECC) |
| ICMPRIMARYOWNERNAME | Remove spaces and limit the length | 224 CHAR (100 CHAR in ECC) First name and last name in one field Strip any spaces from the beginning and end of the value delivered; then take only the first 100 CHAR of the contents |
| ICMlNCOTERMSCODE | Remove spaces and limit the length | 224 CHAR (3 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered (there should be no more than 3 CHAR remaining) |
| ICMINCOTERMSLOCATION | Remove spaces and limit the length | 1000 CHAR (70 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered; then take only the first 70 CHAR of the contents (70 CHAR aligns with the location field in SAP) |
| ICMPAYMENTTERMS | Remove spaces | 224 CHAR (4 CHAR in ECC) Strip any spaces from the beginning and end of the value delivered (there should be no more than 4 CHAR remaining) |
The ABAP logic 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.
The composite key of the custom table is: TENANTID + CONTRACTTYPENAME + SYSID + ICMAGREEMENTCODE
For a single Icertis contract there will be one entry in the custom table. ICMPurchasingOrgCode is a multi value field in Icertis and the separated values will be stored in an additional custom table where they can be available for reporting.
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.
The following will be monitored:
There are no language requirements for this integration. The contents of fields from Icertis are predominantly text-based formats and are being transferred in the language in which they were entered.
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.
The sequencing of the messages from Icertis to CPI to SAP are important that they are processed in the sequence in which they occurred in Icertis. This is because whilst there will usually be a lengthy time between messages for the same SysId (Icertis Contract Id), 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. Other changes which require an amendment are expected to have a length of time between messages in order to draft, author, approve and execute Amendments. Technically any processing out of sequence could result in overwriting values in the custom table and cause an inconsistency in the data between the two systems.
CPI sends the messages determined from the events in the sequence in which they were provided from Icertis. Each event has an EventDateTime field which will be held in SAP in the custom table for traceability.
CPI must wait until the completion of the call from SAP ECC (both systems WP2 and PF2). Upon receipt of the message from CPI, SAP ECC secures a successful lock on the custom table in order to make the updates, trying multiple times if necessary. Each SAP system sends a successful message back to CPI, or an error message if unsuccessful.
Following a successful message from both SAP systems, CPI may process the next message.
In the event of one or both SAP systems sending an error message to CPI, the next message must not be processed. CPI will attempt to retry the failed message multiple times.
This process handles the scenarios of lock entries on the custom table preventing the update, or if one of both of the SAP ECC production systems are temporarily down. There are no functional table update errors expected as the content of the fields are not being validated against SAP field values but are treated as text.
Approx. 3,000 purchase 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.
Response time is less important as this interface is triggered as a background process, and not visible to users.
Error Handling:
Error Messages Returned by the Event Management API
This is implemented using ABAP proxy and errors encountered on the ABAP side such as incorrect tenant ID, will be sent back as a response to CPI. The plan is to use integration and exception monitoring that is, in theory, manageable via Cloud ALM.
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 update of tracking attributes.
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 are the same for the ERP-260 development and both can be unit tested concurrently.
Sample integration files from Icertis are stored in this folder as they become available for the different agreement types and the different API calls:
Icertis ECC Sample Integration Files - ERP Rebuild Implementation - Google Drive
| ID | Condition | Expected Results |
|---|---|---|
Execution | ||
| 1 | Execute Master Agreement | Execution event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Creation of new entry in custom table with field values as defined. |
| 2 | Execute Sub Agreement (single) for single purchasing organization | Execution event received in CPI Successful call to Icertis for agreement details Successful call to Icertis for association details Successful retrieval of agreement details Successful retrieval of association details Creation of new entry in custom table with field values as defined. Check association of Sub Agreement to the relevant Master Agreement is correct |
| 2a | Execute Sub Agreement (single) for multiple purchasing organizations | Execution event received in CPI Successful call to Icertis for agreement details Successful call to Icertis for association details Successful retrieval of agreement details Successful retrieval of association details Creation of new entry in custom table with field values as defined. Check association of Sub Agreement to the relevant Master Agreement is correct Creation of new entries for each purchasing organization and System ID in the purchasing org custom table. |
| 3 | Execute an agreement for a confidential contract (Sub Agreement) | Execution event received in CPI Successful call to Icertis for agreement details Successful call to Icertis for association details Ensure filtering in CPI removes record for processing. No entry processed in SAP ECC. |
| 4 | Execute Stand Alone Agreement for single purchasing organization | Execution event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details No call for association details Creation of new entry in custom table with field values as defined. Creation of new entry for purchasing organization and System ID in the purchasing org custom table. |
| 4a | Execute Stand Alone Agreement for multiple purchasing organizations | Execution event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details No call for association details Creation of new entry in custom table with field values as defined. Creation of new entries for purchasing organization and System ID in the purchasing org custom table. |
| 5 | Execute Supporting Agreement (NDA) for single purchasing organization | Execution event received in CPI Successful call to Icertis for agreement details Successful call to Icertis for association details Successful retrieval of agreement details Successful retrieval of association details Creation of new entry in custom table with field values as defined. Check association to the relevant Master Agreement is correct Creation of new entry for purchasing organization and System ID in the purchasing org custom table. |
| 5a | Execute Supporting Agreement (NDA) for multiple purchasing organizations | Execution event received in CPI Successful call to Icertis for agreement details Successful call to Icertis for association details Successful retrieval of agreement details Successful retrieval of association details Creation of new entry in custom table with field values as defined. Check associations to the relevant Master Agreement is correct Creation of new entries for purchasing organization and System ID in the purchasing org custom table. |
| 6 | Execute Sub Agreement (multiple for the one Master Agreement) for single purchasing organization | Execution event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Creation of new entries in custom table with field values as defined. Check association of Sub Agreements to the relevant Master Agreement is correct |
| 6a | Execute Sub Agreement (multiple for the one Master Agreement) for multiple purchasing organizations | Execution event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Creation of new entry in custom table with field values as defined. Check association of Sub Agreements to the relevant Master Agreement is correct Creation of new entries for purchasing organization and System ID in the purchasing org custom table. |
| Renewal | ||
| 7 | Agreement for single purchasing organization with auto renewal is renewed when the renewal date is reached | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the renewal date. |
| 7a | Agreement for multiple purchasing organizations with auto renewal is renewed when the renewal date is reached | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the renewal date. |
| Termination | ||
| 8 | Existing active Agreement for single purchasing organization is terminated with notice (method 1) | Termination event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the termination notice date. |
| 8a | Existing active Agreement for multiple purchasing organizations is terminated with notice (method 1) | Termination event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the termination notice date. |
| 9 | Existing active Agreement for single purchasing organization is terminated without notice (method 2) | Termination event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the termination date. |
| 9a | Existing active Agreement for multiple purchasing organizations is terminated without notice (method 2) | Termination event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the termination notice date. |
| Amendment Executed | ||
| 10 | Execute an amendment for a Master Agreement | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 11 | Execute an amendment for a Sub Agreement with Master for single purchasing organization | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 11a | Execute an amendment for a Sub Agreement with Master for multiple purchasing organizations | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 12 | Execute an amendment for a Stand Alone Agreement for single purchasing organization | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 12a | Execute an amendment for a Stand Alone Agreement for multiple purchasing organizations | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 13 | Execute an amendment for a Supporting Agreement (NDA) for single purchasing organization | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 13a | Execute an amendment for a Supporting Agreement (NDA) for multiple purchasing organizations | Amendment event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table for Parent Agreement & Parent SysId entry |
| 13b | Agreement with an amendment already executed with auto renewal is renewed when the renewal date is reached. | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table with expiry updated to the renewal date. |
| Executed Updated | ||
| 14 | Update one or more tracking attribute fields for a Sub Agreement with Master for single purchasing organization | ExecutedUpdated event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table |
| 14a | Update one or more tracking attribute fields for a Sub Agreement with Master for multiple purchasing organizations | ExecutedUpdated event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table |
| 14b | Update one or more tracking attribute fields for a Sub Agreement or Standalone agreement where there has already been an amendment executed. | ExecutedUpdated event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of existing record in custom table |
| Other | ||
| 15 | Custom table can be updated by support user | Support user with the relevant authorization group assigned is able to update the contents of the custom table. User id without the relevant authorization group is not able to update the custom table. |
| 16 | Contract in Icertis is executed in a language other than English | Confirm the update of the relevant table entries are the same regardless of the language. |
Considerations and dependencies for testing:
| Package Name | Parent Package |
|---|---|
Other Development Objects
| Object Type | Object Name | Purpose/High Level Logic | Design Rationale Reference |
|---|---|---|---|
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.
