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). 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:

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, Standalone Agreements, and Non-Disclosure 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 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 should 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.

Security, Integrity and Controls

There are no 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.

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 and their Master Agreements).  

CPI makes the necessary 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 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 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.

Target Structure

The following fields will be used to provide the required information for this interface.

Note: 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 labels are to correspond with the Icertis field labels.

Apart from the fields Icertis Agreement Type and System ID which are defined to be the key for the table and will therefore be (i) available for all events  (ii) considered mandatory, all other fields are optional entry in the custom table.

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.

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 will the values retrieved will be made for the Parent Contract and Parent System ID.

The key of the table will be Tenant ID, Icertis Agreement Type and 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.

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 a contract id. This is not the contract id which the users see, but it is the code that represents the contract and it will need to be stored in SAP 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.

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

Provide volumetrics details: Initial load volumes, Number of Records, Expected Frequency, Expected Long term Growth)

BAU - up to 10,000 contracts

Performance Consideration

Specify if there are any specific performance factors that need to be taken into consideration during development i.e. interface must be able to handle 100 posting per-hour, etc.

<100 new/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

Please provide some guidance and/or test data to help the developer unit test the interface. Please include both positive and negative testing (to validate error situations handling)

Dhiraj & Kapila - these will have to be initiated in Icertis?

Dependency on the metadata having been configured in Icertis?

The developer will need to test repeatedly, so where appropriate provide instructions to reverse the actions performed so the test may be run again, or explain how to create new input data to the test. In particular, the developer will need logons for test users representing the various roles within the approval process.

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

Test Conditions and 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.

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.

Other Information

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