| Status | Approved |
|---|---|
| Owner | ROWLINSON-ext, Kerry |
| Stakeholders | |
| Jira Request ID | ERP-228 - Getting issue details... STATUS |
| Jira Development ID | ERP-260 - Getting issue details... STATUS |
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 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:
- 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. 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 Amendment Execution, Renewal and Termination require development within Icertis in order to be initiated and for a custom event job to send the default payload to CPI.
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).
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.
Process Flow Diagram
Step | Description | System | 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 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 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 validity end date. |
11 |
Assumptions
There are no specific assumptions identified.
Dependencies
The following two 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:
Amendment Executed
Renewal
Termination
This development in Icertis is required in order for integration to be tested for event types other than Agreement Execution.
There is an additional dependency on the completion of the configuration of all the metadata in ICertis which defines the fields.
Security, Integrity and Controls
Purchase Contracts in Icertis which are marked as confidential contract ('Yes') are to be filtered out in the middleware with no confidential contracts having entries in the custom table in SAP. These are under strict control and visibility is only by the owner of the contract. There is no representation of them in SAP at all.
There are no other specific security, integrity or controls required for the processing of the interface.
Configuration Requirements
There are no specific configuration requirements for this interface.
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.
Confidential Contracts
Icertis contracts which are identified as confidential (ICMConfidentialContract = YES) are filtered out in CPI and must not have entries made in the custom table in SAP ECC.
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.
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 search for any Master Agreement which is an associated entity.
Call 2: To retrieve the associating entity details for ICMMasterAgreement
GET /v{version}/agreements/{contractTypeName}/{agreementId}/associatinginstances/{associatingEntityName}
Further details about the calls and the returned information is in this document:
Calls to Icertis & Associations - Google Sheets
Note: the call for the associating Master Agreement is NOT made for amendments (Action Name = "AmendmentExecuted") because the associations were entered when the original document was executed.
(update this depending on the technical approach for changing entries in the table - esp. if the whole record is deleted and recreated we would need to call the associations for the Parent )
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.
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.
Below is an example of the out-of-the-box payload sent from Icertis to CPI on the events:
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.
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 sequence of the field in the returned JSON file is unknown at the time of writing and there will be many more fields in the file than those specified below.
| Field | Field Label | Description | Length/Format |
|---|---|---|---|
| n/a | 'Source' | For identifying the tenant, we can use the 'source' information provided in the initial event package from Icertis. For the development system: source: "/icertis/syensqo-dev" | 20 CHAR |
| ActionName | n/a | The ActionName is provided in the payload from the events which are sent to CPI. The content denotes whether the event is a creation, a renewal, a termination or an amendment. Termination of a contract "Terminated" Renewal of a contract "Renewed" Amendment executing "AmendmentExecuted" Agreement creation "Executed" | n/a |
| ContractTypeName | Contract Type Name | Possible values are: (supporting agreement is the NDA; no amendments possible for Baseline Agreements) Termination Agreements - we will receive notification to CPI of 'Terminated' for the original contract (Master/Sub etc.); call for the original contract will have termination date for the original contract. ContractTypeName is not a field seen by the users, but is more a title/heading | 224 CHAR |
| SysId | System ID | Along with ContractTypeName, SysId is the key with which CPI makes the call to Icertis to retrieve the complete header contract field details. This is important to have from Icertis in addition to the agreement code because it is used in backend table mapping in Icertis and is important to keep the relationship to the agreement code. Note: in the calls to Icertis, the field is labelled {agreementId} | 36 CHAR |
| ICMAgreementCode | Agreement Code | The naming convention for Icertis Agreements is defined; characters describe the type and the fact it is amendment is in the structure of the code. The standard field ICMAgreementCode has been assigned a custom number range. It is understood then that the value of the ICMParentContractId field (used in amendments) will be the ICMAgreementCode for the parent contract. Calls to ICertis for associated entities (Master Agreements) will return theICMAgreementCode. | 224 CHAR |
| ICMConfidentialContract | Confidential Contract | YES if the contract is confidential, NO if not (will not be blank) | 3 CHAR |
| Name | Agreement Name | Name field is going to be fully user-defined with no default but it is expected to be descriptive and therefore a useful addition to the report to help users identify what the contract is for (eg. where there are multiple for a supplier and our report will have no line items for context). | 1000 CHAR |
| ICMParentSystemID | Parent System ID | An amendment in Icertis is assigned a new ICMAgreementCode and a new SYSID. But the original agreement code that the amendment is for is in the ICMParentContractId field, and the original contract system id is in the ICMParentSystemID field. This is not a field in Icertis, but more of a defined relationship between the parent contract and the amendment. | 36 CHAR |
| ICMParentContractId | Parent Contract | An amendment in Icertis is assigned a new ICMAgreementCode and a new SYSID. But the original agreement code that the amendment is for is in the ICMParentContractId field, and the original system id is in the ICMParentSystemID field. So the format of the ICMParentContractId field will be the format of the original agreement code field: This is not a field in Icertis, but more of a defined relationship between the parent contract and the amendment. Note: This is not the TYPE of the parent agreement, but the NUMBER of the parent agreement. | 224 CHAR |
| ICMAppSrcSupplierID | Bidders/Supplier SAP ID | The supplier numbers will be the same as the ECC supplier numbers. NDA's may not necessarily have a supplier id as it is possible to define an NDA for a bidder supplier only. | 224 CHAR |
| ICMEffectiveDate | Effective Date | Start date of the agreement "YYYY-MM-DDTHH:MM:SS" If we receive an amendment agreement, we will use the ICMEffectiveDate and not the Amendment Effective Date (ICMAmendmentEffectiveDate) as the valid from date. The validity start date of an outline agreement should not be altered as there could be open documents. | DATE |
| ICMExpiryDate | Expiry | End date of the agreement "YYYY-MM-DDTHH:MM:SS" | DATE |
| ICMTotalContractValue | Total Contract Value | Is the total value of the contract (in ECC it is target value at header level) | INT(15 including 2 decimals) |
| ICMCurrency | Supplier Currency | The currency codes in Icertis are aligned to SAP currency codes | 5 CHAR |
| ICMLegalEntityCode | Syensqo Legal Entity Code | Organizational data - company code and purchasing org are being aligned in Icertis to ECC - it is the 4 char code for company code which matches SAP | 1000 CHAR |
| ICMPurchasingOrgCode | Purchasing Org Code | Organizational data - company code, and purchasing org are being aligned in Icertis to ECC- it is the 4 char code for purchasing organization which matches SAP ECC. Multiple values able to be selected by the user. Values will be provided in a single field with values separated by commas. | 1000 CHAR |
| ICMRegion | Region | Icertis has values for each region which will be useful for the consolidation report to enable filtering of the Icertis Z table records by region. Possible values are: | 4 CHAR |
| ICMPrimaryOwnerName | Primary Owner Name | Use for filtering in the report on Z table so owners can find their own to work on. First name, last name and email id in one field. | 224 CHAR |
| ICMIncotermsCode | Incoterms Code | Incoterms are being aligned to correspond between Icertis and ECC. | 224 CHAR |
| ICMIncotermsLocation | Incoterms Location | Free text for entry by the user. Is the place where Syensqo takes ownership of purchased goods according to the terms agreed with the supplier. Note: For release 4, this will need to be a valid value configured within Transportation Management and is populated into the location ID field which then defaults the description into the location field. For release 2, the location field will be free text. | 1000 CHAR |
| ICMPaymentTerms | Payment Terms | Payment terms are being aligned to correspond between Icertis and ECC. This is the 4 char code that matches to SAP's payment term codes in ECC. | 224 CHAR |
| ICMTerminationNoticeDate | Termination Notice Date | When a termination message is received, the expiry date field remains same in ICertis but the termination date will have to become the expiry date This is the field that will hold the new expiry date every time a 'termination' activity is received. | DATE |
Target Structure
The fields defined in the target structure below will be the structure of the custom table in SAP ECC, named ZWPUT_ICMCONTRCT.
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.
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 System 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 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 System ID.
The key of the table will be Tenant ID, Contract Type Name, System ID, Agreement Code and Purchasing Organization 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.
One Icertis Agreement to One/Many ZWPUT_ICMCONTRCT Entries
Purchasing organization needs to be part of the key in the table in order to ensure a unique record for each entry in the table. An Icertis contract can be defined for use by multiple purchasing organizations. 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. This will be represented by one row for each purchasing org in the table - same Tenant ID, Contract Type Name, System ID and Agreement Code. Values for all other fields will be the same for each purchasing organization entry.
For the Agreement Execution event, one or more new entries are created in the table depending on the number of purchasing organizations sent in the field ICMPurchasingOrgCode. All values are provided in a single field separated by commas.
For the other events Amendment Executed, Renewal, Termination existing table entries for TenantID, ContractTypeName, SysId, ICMAgreementCode, and each ICMPurchasingOrgCode are updated.
Amendment Executed
Renewal
Termination
| Field | Field Label | Description | Length/Format |
|---|---|---|---|
| TENANTID | Tenant ID | For identifying the tenant, we can use the 'source' information provided in the initial event package from Icertis. For the development system: source: "/icertis/syensqo-dev" | 20 CHAR |
| CONTRACTTYPENAME | Contract Type Name | Possible values are: Termination Agreements - we will receive notification to CPI of 'Terminated' for the original contract (Master/Sub etc.); call for the original contract will have termination date for the original contract. ContractTypeName is not a field seen by the users, but is more a title/heading | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| SYSID | System ID | Along withContractTypeName, SysId is the key with which CPI makes the call to Icertis to retrieve the complete contract field details. Example: 1343f2e0-9386-4fa7-aa5b-22abba04d35a (36 chars) | 36 CHAR |
| ICMAGREEMENTCODE | Agreement Code | The agreement code is the contract number in Icertis and is preceded by the agreement type. Example: Master Agreement: Master Agreement: PMAnnnnnnn This value from Icertis will be stored on the header of the outline agreement in SAP ECC. | 224 CHAR (25 CHAR in ECC) |
| ICMCONFIDENTIALCONTRACT | Confidential Contract | YES if the contract is confidential, NO if not (will not be blank) | 3 CHAR (1 CHAR in ECC with value selected or not) |
| NAME | Agreement Name | Description given to the contract (useful for reporting) | 1000 CHAR (First 100 CHAR in ECC) |
| ASSOCIATINGTYPE | Associating Agreement Type | This is the Icertis Agreement Type of the associated agreement (for example ICMMasterAgreement if the record is a ICMSubAgreement or SupportingAgreement. The call for associated entity 'ICMMasterAgreement' will return all the fields for the associated master agreement. The Agreement Type, the Agreement Code and System ID will be stored in the custom table to enable reporting of the hierarchical structure of contracts to their Master Agreements. The associating entity fields are not fields that exist in Icertis, but are defined in SAP in order to hold the information. In Icertis, the associations are held as types of relationships. | 224 CHAR (3 CHAR in ECC, with view and coded values) |
| ASSOCIATINGCODE | Associating Agreement Code | This is the Icertis Agreement Code of the associated agreement (for example ICMMasterAgreement if the record is a ICMSubAgreement or SupportingAgreement. The call for associated entity 'ICMMasterAgreement' will return all the fields for the associated master agreement. The Agreement Type, the Agreement Code and System ID will be stored in the custom table to enable reporting of the hierarchical structure of contracts to their Master Agreements. The associating entity fields are not fields that exist in Icertis, but are defined in SAP in order to hold the information. In Icertis, the associations are held as types of relationships. | 224 CHAR (25 CHAR in ECC) |
ASSOCIATINGSYSID | Associating System ID | This is the Icertis System ID of the associated agreement (for example ICMMasterAgreement if the record is a ICMSubAgreement or SupportingAgreement. The call for associated entity 'ICMMasterAgreement' will return all the fields for the associated master agreement. The Agreement Type, the Agreement Code and System ID will be stored in the custom table to enable reporting of the hierarchical structure of contracts to their Master Agreements. The associating entity fields are not fields that exist in Icertis, but are defined in SAP in order to hold the information. In Icertis, the associations are held as types of relationships. | 36 CHAR (36 CHAR in ECC) |
| ICMAPPSRCSUPPLIERID | Bidders/Supplier SAP ID | The supplier numbers will be the same as the ECC supplier numbers. NDA's may not necessarily have a supplier id as it is possible to define an NDA for a bidder supplier only. Cannot be validated as the supplier records do not exist in both SAP systems. | 224 CHAR (10 CHAR in ECC) |
| ICMEFFECTIVEDATE | Effective Date | YYYYMMDD | DATE |
| ICMEXPIRYDATE | Expiry | YYYYMMDD | DATE |
| ICMTOTALCONTRACTVALUE | Total Contract Value | Is the total value of the contract (in ECC it is target value at header level) In the case of amendments, it is the updated overall total Renewals may also update the overall value. ERP-203 Icertis: Total Contract Value calculation with multiple amendments to enable ECC Integration | INT(15 including 2 decimals) |
| ICMCURRENCY | Supplier Currency | Confirmed the currency codes in Icertis are aligned to SAP codes | 5 CHAR |
| ICMLEGALENTITYCODE | Syensqo Legal Entity Code | Organizational data - company code, purchasing group, purchasing org are being aligned in Icertis to ECC - it is the 4 char code for company code which matches SAP | 1000 CHAR (4 CHAR in ECC) |
| ICMPURCHASINGORGCODE | Purchasing Org Code | Organizational data - company code, purchasing group, purchasing org are being aligned in Icertis to ECC- it is the 4 char code for purchasing organization which matches SAP. Multiple values able to be selected by the user. Values will be provided from ICertis in a single field with values separated by commas. | 1000 CHAR (4 CHAR in ECC) |
| ICMREGION | Region | Icertis has values for each region which will be useful for the consolidation report to enable filtering of the Icertis Z table records by region. Possible values are: WW, EMEA, APAC, AMS (world-wide, Europe, Asia Pacific, Americas) | 4 CHAR |
| ICMPRIMARYOWNERNAME | Primary Contract Owner | Use for filtering in the report on Z table so owners can find their own to work on First name, last name and email id in one field | 224 CHAR (224 CHAR in ECC) |
| ICMlNCOTERMSCODE | Incoterms Code | Incoterms are being aligned to correspond between Icertis and ECC | 224 CHAR (3 CHAR in ECC) |
| ICMINCOTERMSLOCATION | Incoterms Location | Free text for entry by the user. For release 4, this will need to be a valid value configured within Transportation Management and is populated into the location ID field which then defaults the description into the location field. | 1000 CHAR (70 CHAR in ECC) |
| ICMPAYMENTTERMS | Payment Terms | Payment terms are being aligned to correspond between Icertis and ECC This is the 4 char code that matches to SAP's codes in ECC | 224 CHAR (4 CHAR in ECC) |
Mapping and Calculation
Note: For all field values from Icertis, remove any blank spaces from the beginning and end of the value and the remaining content is to go into the target field. 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 have to correspond to the length of the fields in Icertis.
Important: The ActionName field in the initial event received to CPI is the key controlling information which determines whether a new line item in the custom table is required, or an existing line is 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)
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. Given that any differences between the data in the custom table and field values in outline agreements in SAP are to be reported, any lower case values are to be converted to upper case in CPI before being loaded into the table.
| Source Table | API or Portlet Name | Source Field | Required (Y/N) | Description | Target | API or Portlet Name | Target Field | Required (Y/N) | Description (Label in SAP) | Rule Type | Rule Instruction |
|---|---|---|---|---|---|---|---|---|---|---|---|
| N/A | 'Source' | Y | Development system: source: "/icertis/syensqo-dev" Test system: source: "/icertis/syensqo-uat" | ZWPUT_ICMCONTRCT | TENANTID | Y | Tenant ID | Use what is received from Icertis in the Source field: Development system: source: "/icertis/syensqo-dev" Test system: source: "/icertis/syensqo-uat" | |||
N/A | ContractTypeName | Y | Contract Type Name | ZWPUT_ICMCONTRCT | CONTRACTTYPENAME | Y | Contract Type Name | If ActionName is 'Executed', then a new entry is made in the Z table for CONTRACTYPENAME and SYSID If ActionName is 'Renewed' or 'Terminated', then one or more existing entries are updated for the CONTRACTTYPENAME and SYSID If the ActionName is 'AmendmentExecuted' then the existing entry for ICMAGREEMENTCODE = ICMParentContractId and SYSID = ICMParentSystemID is updated. | |||
| N/A | SysId | Y | System ID | ZWPUT_ICMCONTRCT | SYSID | Y | System ID | If ActionName is 'Executed', then a new entry is made in the Z table for CONTRACTYPENAME and SYSID If ActionName is 'Renewed' or 'Terminated', then the existing entry is updated for the CONTRACTYPENAME and SYSID If the ActionName is 'AmendmentExecuted' then the existing entry for for ICMAGREEMENTCODE = ICMParentContractId and SYSID = ICMParentSystemID is updated. | |||
| N/A | ICMAgreementCode | Y | ICM Agreement Code | ZWPUT_ICMCONTRCT | ICMAGREEMENTCODE | Y | ICM Agreement Code | Direct Mapping | |||
| N/A | ICMConfidentialContract | Y | Confidential Contract | ZWPUT_ICMCONTRCT | ICMCONFIDENTIALCONTRACT | Y | Confidential Contract | If the agreement has the value 'YES' for confidential contract, then the file must not be processed; no entry is to be made or changed in SAP. | |||
| N/A | Name | Y | Agreement Name | ZWPUT_ICMCONTRCT | NAME | N | Agreement Name | Direct Mapping | |||
| N/A | N/A | N | N/A | ZWPUT_ICMCONTRCT | ASSOCIATINGTYPE | N | Associating Agreement Type | If the Agreement Type is ICMSupportingAgreement OR ICMSubAgreement we call Icertis for the associating entity ICMMasterAgreement If one is found, store the ContractTypeName for the associated master agreement in ASSOCIATINGTYPE | |||
| N/A | N/A | N | N/A | ZWPUT_ICMCONTRCT | ASSOCIATINGCODE | N | Associating Agreement Code | If the Agreement Type is ICMSupportingAgreement OR ICMSubAgreement we call Icertis for the associating entity ICMMasterAgreement If one is found, store the ICMAgreementCode for the associated master agreement in ASSOCIATINGCODE | |||
| N/A | N/A | N | N/A | ZWPUT_ICMCONTRCT | ASSOCIATINGSYSID | N | Associating System ID | If the Agreement Type is ICMSupportingAgreement OR ICMSubAgreement we call Icertis for the associating entity ICMMasterAgreement If one is found, store the SysId for the associated master agreement in ASSOCIATINGSYSID | |||
| N/A | ICMAppSrcSupplierID | N | Bidders/Supplier SAP ID | ZWPUT_ICMCONTRCT | ICMAPPSRCSUPPLIERID | N | Bidders/Supplier SAP ID | Direct Mapping | |||
| N/A | ICMEffectiveDate | N | Effective Date | ZWPUT_ICMCONTRCT | ICMEFFECTIVEDATE | N | Effective Date | Format received is YYYY-MM-DDTHH:MM:SS Remove the HH:MM:SS and 'dashes' to store in the Z table as YYYYMMDD | |||
| N/A | ICMExpiryDate | N | Expiry | ZWPUT_ICMCONTRCT | ICMEXPIRYDATE | N | Expiry | Format received is YYYY-MM-DDTHH:MM:SS If ActionName is 'Executed', 'Renewed' or 'Amendment Executed', direct mapping. If ActionName 'Terminated', fill with the value from ICMTerminationNoticeDate The format of the contents also need to be updated to remove the time and dashes to store in the Z table as YYYYMMDD | |||
| N/A | ICMTotaIContractVaIue | N | Target Value | ZWPUT_ICMCONTRCT | ICMTOTALCONTRACTVALUE | N | Target Value | Direct Mapping | |||
| N/A | ICMCurrency | N | Supplier Currency | ZWPUT_ICMCONTRCT | ICMCURRENCY | N | Supplier Currency | Direct Mapping | |||
| N/A | ICMLegaIEntityCode | N | Syensqo Legal Entity Code | ZWPUT_ICMCONTRCT | ICMLEGALENTITYCODE | N | Syensqo Legal Entity Code | Direct Mapping | |||
| N/A | ICMPurchasingOrgCode | N | Purchasing Org Code | ZWPUT_ICMCONTRCT | ICMPURCHASINGORGCODE | N | Purchasing Org Code | Direct Mapping | |||
| N/A | ICMRegion | N | Region | ZWPUT_ICMCONTRCT | ICMREGION | N | Region | Direct Mapping | |||
| N/A | ICMPrimaryOwnerName | N | Primary Owner Name | ZWPUT_ICMCONTRCT | ICMPRIMARYOWNERNAME | N | Primary Owner Name | Direct Mapping | |||
| N/A | ICMlncotermsCode | N | Incoterms Code | ZWPUT_ICMCONTRCT | ICMlNCOTERMSCODE | N | Incoterms Code | Direct Mapping | |||
| N/A | ICMIncotermsLocation | Incoterms Location | ZWPUT_ICMCONTRCT | ICMINCOTERMSLOCATION | N | Incoterms Location | Direct Mapping | ||||
| N/A | ICMPaymentTerms | N | Payment Terms | ZWPUT_ICMCONTRCT | ICMPAYMENTTERMS | N | Payment Terms | Direct Mapping | |||
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
There is no processing to be carried out within the target system.
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.
The triggering events from Icertis are received to CPI 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.
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.
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
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.
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.
Update with test scenarios for multiple purchasing orgs when fields are finalised
Test Conditions and Expected Results
| ID | Condition | Expected Results |
|---|---|---|
| Execution | ||
| 1 | Execute 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 entry in custom table with field values as defined. |
| 1a | Execute 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 multiple new entries (one per purchasing organization) 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 multiple new entries (one per purchasing organization) in custom table with field values as defined. Check association of Sub Agreement to the relevant Master Agreement is correct |
| 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 |
| 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. |
| 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 multiple new entries (one per purchasing organization) in custom table with field values as defined. |
| 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 |
| 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 multiple new entries (one per purchasing organization) in custom table with field values as defined. Check associations to the relevant Master Agreement is correct |
| 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 multiple new entries (one per purchasing organization) in custom table with field values as defined. Check association of Sub Agreements to the relevant Master Agreement is correct |
| 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 multiple existing entries (one per purchasing organization) in custom table with expiry updated to the renewal date. |
| 8 | Agreement for single purchasing organization without auto renewal is renewed | 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. |
| 8a | Agreement for multiple purchasing organizations without auto renewal is renewed | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of multiple existing records (one per purchasing organization) in custom table with expiry updated to the renewal date. |
| Termination | ||
| 9 | Existing active Agreement for single purchasing organization is terminated with notice (method 1) | 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 termination notice date. |
| 9a | Existing active Agreement for multiple purchasing organizations is terminated with notice (method 1) | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of multiple existing records (one per purchasing organization) in custom table with expiry updated to the termination notice date. |
| 10 | Existing active Agreement for single purchasing organization is terminated without notice (method 2) | 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 termination date. |
| 10a | Existing active Agreement for multiple purchasing organizations is terminated without notice (method 2) | Renewal event received in CPI Successful call to Icertis for agreement details Successful retrieval of agreement details Update of multiple existing records (one per purchasing organization) in custom table with expiry updated to the termination notice date. |
| Amendment Executed | ||
| 11 | Execute an amendment for a Master 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 |
| 11a | ||
| 12 | 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 |
| 12a | ||
| 13 | 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 |
| 13a | ||
| 14 | 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 |
| 14a |
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
| Package Name | Parent Package |
|---|---|
Other Development Objects
| Object Type | Object Name | Purpose/High Level Logic | Design Rationale Reference |
|---|---|---|---|