| Status | |
|---|---|
| Owner | ROWLINSON-ext, Kerry |
| Stakeholders | |
| Jira Request ID | |
| Jira Development ID |
High- Level Specification
| Parameter | Value |
|---|---|
| Application System (Source) | Icertis Contract Intelligence |
| Application System ( Target) | SAP ERP (PF2) & SAP ERP (WP2) |
| Business Process Reference | 03.04.04.01. Manage Outline Agreements (R2) |
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 completer 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:
- Maintaining the relationship between the Icertis Contract ID and the SAP outline agreement number.
- The ability to report where there are inconsistencies in the data between the two systems.
- 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). 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.
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:
- Validation that the correct Icertis Contract ID is entered on the outline agreement.
- Reporting any key header data from the outline agreement which is not aligned with the corresponding data in Icertis.
- Enables identification of orphan outline agreements which do not have an Icertis Contract ID assigned.
- 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).
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.
Process Flow Diagram
The process steps:
Step | Description | Comment | |
|---|---|---|---|
1 | A purchase contract is executed in Icertis | Icertis | A legal purchase contract is executed in Icertis: |
2 | New entry/entries in custom table for the Icertis Contract | SAP ECC | 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, Purchasing Organization and the relevant data fields from the contract header. |
3 | An amendment to a contract in Icertis is executed | Icertis | An amendment for an existing contract is executed in Icertis. |
4 | Change entry/entries in custom table for the parent contract of the amendment | SAP ECC | The existing entry/entries in the table for the parent agreement of the amendment are located and all the relevant fields in the table are overwritten with the values provided in the amendment. |
5 | A renewal of an existing contract in Icertis is made. | Icertis | An existing purchase contract in Icertis is renewed which updates the overall value and the validity end date. |
6 | The entry/entries in the custom table for the contract are updated. | SAP ECC | The existing entry/entries in the table for the purchase contract are updated to reflect the changes to the overall value and the validity end date. |
7 | An existing purchase contract in Icertis subject to automatic renewal is renewed. | Icertis | An existing purchase contract in Icertis is renewed automatically when the renewal date comes due which updates the validity end date. |
8 | The entry/entries in the custom table for the contract are updated. | SAP ECC | The existing entry/entries in the table for the purchase contract are updated to reflect the changes to the validity end date. |
9 | An existing purchase contract in Icertis is terminated. | Icertis | An existing purchase contract in Icertis is terminated which updates the validity end date and the status in Icertis. |
10 | The entry/entries in the custom table for the contract are updated. | SAP ECC | The existing entry/entries in the table for the purchase contract are updated to reflect the changes to the expiry date. |
Assumptions
There are no specific assumptions identified.
Dependencies
This specification is dependent on the integration development ERP-260 Custom Integration to Call/Dump Icertis Records into Z-Table.
Security, Integrity and Controls
No confidential agreements (ICMConfidentialContract=YES) are to be stored in the custom table.
Configuration Requirements
There are no configuration requirements.
Special Requirements
As the interface is one-way from Icertis to SAP ECC there are no special requirements, security 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.
Design Rationale
The 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 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.
CPI makes the necessary filters and translations and ABAP logic then takes the field information from CPI to populate into the same custom table in each of the SAP ECC systems.
CPI will take care of complex transformations and rules while the ABAP logic will take care of the following types of manipulation of the data from CPI before updating the custom table:
- Removal of any spaces from the beginning and end of field values
- Splitting of any field value
- Stripping out parts of the field values (eg. stripping the time from the date fields)
- Reformatting of field values (eg. reformatting the date fields)
- Defining and managing coded values for fields to reduce field sizes (eg. Contract type names to have coded values)
API Use
The API is consumed in the process.
Data Structure
The following fields will be used to provide the required data structure of the interface:
| Parent - ECC Custom Table | Field | Description | Mandatory (Y/N) | Data Type - SAP ECC lengths |
|---|---|---|---|---|
| ZWPUT_ICMCONTRCT | TENANTID | Tenant ID | Y | 20 CHAR (3 CHAR in ECC with view and coded values) |
| ZWPUT_ICMCONTRCT | CONTRACTTYPENAME | Contract Type Name | Y | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| ZWPUT_ICMCONTRCT | SYSID | System ID | Y | 36 CHAR in ECC |
| ZWPUT_ICMCONTRCT | ICMAGREEMENTCODE | Agreement Code | Y | 224 CHAR (25 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMCONFIDENTIALCONTRACT | Purchasing Org Code | Y | 1000 CHAR (4 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | NAME | Confidential Contract | N | 3 CHAR (1 CHAR in ECC with value selected or not) |
| ZWPUT_ICMCONTRCT | ASSOCIATINGTYPE | Agreement Name | N | 1000 CHAR (First 100 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ASSOCIATINGCODE | Associating Agreement Type | N | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| ZWPUT_ICMCONTRCT | ASSOCIATINGSYSID | Associating Agreement Code | N | 224 CHAR (25 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMAPPSRCSUPPLIERID | Associating System ID | N | 36 CHAR (36 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMEFFECTIVEDATE | Bidders/Supplier SAP ID | N | 224 CHAR (10 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMEXPIRYDATE | Effective Date | N | DATE |
| ZWPUT_ICMCONTRCT | ICMTOTALCONTRACTVALUE | Expiry | N | DATE |
| ZWPUT_ICMCONTRCT | ICMCURRENCY | Total Contract Value | N | INT(15 including 2 decimals) |
| ZWPUT_ICMCONTRCT | ICMLEGALENTITYCODE | Supplier Currency | N | 5 CHAR |
| ZWPUT_ICMCONTRCT | ICMPURCHASINGORGCODE | Syensqo Legal Entity Code | N | 1000 CHAR (4 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMREGION | Region | N | 4 CHAR |
| ZWPUT_ICMCONTRCT | ICMPRIMARYOWNERNAME | Primary Contract Owner | N | 224 CHAR (100 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMlNCOTERMSCODE | Incoterms Code | N | 224 CHAR (3 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMINCOTERMSLOCATION | Incoterms Location | N | 1000 CHAR (70 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | ICMPAYMENTTERMS | Payment Terms | N | 224 CHAR (4 CHAR in ECC) |
Calculation and Validation
The table below shows the rule instruction for each field:
| Parent | Field | Rule Type | Rule Instruction |
|---|---|---|---|
| ZWPUT_ICMCONTRCT | 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. |
| ZWPUT_ICMCONTRCT | 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. |
| ZWPUT_ICMCONTRCT | SYSID | None | 36 CHAR in ECC, direct mapping |
| ZWPUT_ICMCONTRCT | ICMAGREEMENTCODE | Remove spaces | 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 |
| ZWPUT_ICMCONTRCT | ICMCONFIDENTIALCONTRACT | None | 1000 CHAR (4 CHAR in ECC) |
| ZWPUT_ICMCONTRCT | NAME | Coded Values | Convert the ICertis values of 'YES' and 'NO' 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. |
| ZWPUT_ICMCONTRCT | ASSOCIATINGTYPE | Remove spaces and limit the length | 1000 CHAR (First 100 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 |
| ZWPUT_ICMCONTRCT | ASSOCIATINGCODE | 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. |
| ZWPUT_ICMCONTRCT | ASSOCIATINGSYSID | Remove spaces | 224 CHAR (25 CHAR in ECC) Values will be in this format where nnnnn starts at 1, 2, 3 etc.: |
| ZWPUT_ICMCONTRCT | ICMAPPSRCSUPPLIERID | None | 36 CHAR (36 CHAR in ECC) - direct mapping |
| ZWPUT_ICMCONTRCT | ICMEFFECTIVEDATE | Remove spaces | 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) |
| ZWPUT_ICMCONTRCT | ICMEXPIRYDATE | Strip and format | Format received is YYYY-MM-DDTHH:MM:SS Remove the HH:MM:SS and 'dashes' to store in the Z table as YYYYMMDD |
| ZWPUT_ICMCONTRCT | ICMTOTALCONTRACTVALUE | Strip and format | Format received is YYYY-MM-DDTHH:MM:SS Remove the HH:MM:SS and 'dashes' to store in the Z table as YYYYMMDD |
| ZWPUT_ICMCONTRCT | ICMCURRENCY | None | INT(15 including 2 decimals) - direct mapping |
| ZWPUT_ICMCONTRCT | ICMLEGALENTITYCODE | None | 5 CHAR - direct mapping |
| ZWPUT_ICMCONTRCT | ICMPURCHASINGORGCODE | Remove spaces | 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) |
| ZWPUT_ICMCONTRCT | ICMREGION | None | 4 CHAR - direct mapping |
| ZWPUT_ICMCONTRCT | ICMPRIMARYOWNERNAME | Remove spaces and limit the length | 224 CHAR (100 CHAR in ECC) First name, last name and email id 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 |
| ZWPUT_ICMCONTRCT | ICMlNCOTERMSCODE | Remove spaces | 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) |
| ZWPUT_ICMCONTRCT | 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) |
| ZWPUT_ICMCONTRCT | 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) |
Processing Logic
Describe the processing requirement in the System
The ActionName field in the initial event received to CPI is the key controlling information which determines whether new line item(s) in the custom table are required, or existing line(s) are to be updated. The values in this field are:
"Terminated" (update existing entry)
"Renewed" (update existing entry)
"AmendmentExecuted" (update existing entry, but for the Parent Contract and Parent System ID)
"Executed" (create a new entry)
It is expected that CPI will have to provide the ActionName or an indicator for the ABAP logic to know whether to make new entries or to change/replace existing entries.
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.
Delta or Full Load Requirements
CPI will filter out any additional fields provided in the payloads from Icertis and keep only those required to be stored in SAP or used by the ABAP logic.
Interface Alert & Monitoring
The following will be monitored:
- API endpoints are available.
- Failures on inbound processing and outbound side need to be handled . Please check the Error Handling section.
- 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 within the hour immediately after the execution of a new contract.
Language Requirements
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.
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
BAU - up to 10,000 contracts
Performance Consideration
Estimated <100 new contracts/contract changes per day
Error Handling
Error Handling:
- SAP Cloud ALM (CALM) will be used to capture integration execution errors.
- To correct the error, the Administrator must ensure that the data inconsistency is resolved in the concerned system.
- Refer to the link below to troubleshoot Error Messages Returned by the Event Management API.
Error Messages Returned by the Event Management API
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 and terminations.
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
| ID | Condition | Expected Results |
|---|---|---|
Test Considerations/Dependencies
List any considerations essential for application test planning (e.g., test this before ABC along with DEF separate from GHI). If the development encompasses a user interface, explain how to test it. List any insights as to how this component could be tested the most efficiently.
Other Information
Development Details
Package
| Package Name | Parent Package |
|---|---|
Other Development Objects
| Object Type | Object Name | Purpose/High Level Logic | Design Rationale Reference |
|---|---|---|---|
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.
