High- Level Specification

Functional Overview

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

The 'light' integration consists of three main parts:

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

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

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

Scope and Objectives

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

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

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

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

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

Process Flow Diagram

Assumptions

There are no specific assumptions identified.

Dependencies

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

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

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

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

ERP-508: Enhancement for Icertis Event Streams

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

• AmendmentExecuted

• Renewed

• Terminated

• ExecutedUpdated (see Enhancement ERP-766)

This development in Icertis is required in order for integration to be tested for event types other than Agreement Execution.  The Renewed event is for contracts defined with automatic renewal in place. Any other contract renewals are handled as amendments.

There is an additional dependency on the completion of the configuration of all the metadata in ICertis which defines the fields.

ERP-766: Icertis Enhancement to Trigger Event to CPI for Nominated Tracking Attribute Changes

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

Security, Integrity and Controls

Purchase Contracts in Icertis which are marked as confidential contract ('true') are to be filtered out in CPI 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 and no visibility of them except by the contract owner and only within Icertis. 

It is noted, that although it is technically possible for the confidentiality setting on the contract to be changed in ICertis, the recommendation to the business users is for them to create a new Sub Agreement if this is required. This is because the integration cannot adequately support all the scenarios of changing the setting when a contract has been transmitted to the custom table, or when it is missing from the table but has been changed.

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

Configuration Requirements

Icertis Configuration

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

The Icertis configuration is required to be completed as per the configuration workbook.

Special 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.

Confidential Contracts

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

Design Rationale

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 via API Management with ContractTypeName, SysId and ActionName.  With that information CPI makes two calls to Icertis to retrieve the agreement data and any associating instances (which exist between Sub Agreements, Supporting Agreements and their Master Agreements).  There are no other associations which are relevant to be represented in the reporting structure in SAP apart from Master Agreements.

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

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

CPI does not need to provide the ActionName to SAP. 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.

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

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

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

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

A table detailing the scenarios and the calls made from CPI is provided here: CPI Calls based on Contract Type and Action Name - Google Sheets

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 fields 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.

Target Structure

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

Validation

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

Field Definitions

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

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

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

Table Entries in Target SAP ECC

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

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

One Icertis Agreement to One ZMM_ICMCONTRACT Entry

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

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

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

• AmendmentExecuted

• Renewed

• Terminated

• ExecuteUpdated

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

Mapping and Calculation

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

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

Important:  The ActionName field in the initial event received to CPI is 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 ICMParentContractId  and ICMParentEntityInstanceId)
"Executed" (create a new entry)
"ExecutedUpdated" (update existing entry)

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

Icertis field contents are not case-sensitive.  

Processing Logic

Processing within Source

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

Processing within Middleware

All processing within CPI is defined in the mapping sheet.

Processing within Target

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 time.

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

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.

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, terminations and tracking attribute field updates.

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

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

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

Test Conditions and Expected Results

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.

ERP-766: Icertis Enhancement to Trigger Event to CPI for Nominated Tracking Attribute Changes is required to be completed in Icertis.

Other Information

There is no other information identified.

Development Details

Package

Other Development Objects

Appendix

See also

Insert links and references to other documents which are relevant when trying to understand this decision and its implications. Other decisions are often impacted, so it's good to list them here with links. Attachments are also possible but dangerous as they are static documents and not updated by their authors.

Change log