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 SAP ECC 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 SAP ECC.  The integration between Icertis and SAP ECC for release 2 is a custom table in SAP ECC to hold key header field content from Icertis (ERP-260 Integration Process - Icertis to SAP ECC Contract Data Replication & ERP-261 System Interface - Icertis Contract Data Replication to SAP ECC). This custom table supports the main objectives:

1. To enable a relationship between the Icertis Agreement Code and the SAP outline agreement number.
2. To report where there are inconsistencies in the data between the two systems.

Under this spec the following components will need to be delivered:

1. A new field in Outline Agreement Header, available to be updated via ME31K & ME32K and displayed when using ME33K. The new field will be called "OA Verification Status". This field will be able to be updated (the same as the ICM Agreement Code EKKO-ZZICMAGREEMENTCODE) via the Contract Mass Maintenance transaction MEMASSCONTRACT.
2. A new program / transaction code for users to edit in bulk two fields:
   1. The new field created under this spec: "OA Verification Status".
   2. The existing field ICM Agreement Code (EKKO-ZZICMAGREEMENTCODE) (this was created under spec ERP-259 Enhancement for Storage of Icertis ID on OA Header).

The new field & the new TCODE to update both fields will need to be available both in WP2 and PF2 environments.

Scope and Objectives

For one purchase contract in Icertis, there can be multiple outline agreements created in SAP ECC (one per relevant purchasing organization). The Icertis Agreement Code is entered on the header of each outline agreement. This can be done during the creation of each one, or via ME32K Change Outline Agreement after creation and one outline agreement at a time. This enhancement allows contract specialists and also GBS members to update in bulk the ICM Agreement code and also the OA Verification status via a new transaction code.

The intended business process is for all new outline agreements created in SAP ECC after the introduction of Icertis Contract Management to be assigned to the respective Icertis legal contract via the entry of the ICM Agreement Code on the header when the outline agreement is created. Currently active outline agreements exist in SAP ECC which may not have a signed legal contract, and many outline agreements have an open-ended validity period which makes it difficult to determine which outline agreements are relevant to be migrated to S/4 HANA.

To assist with the process of identifying outline agreements which have been verified for migration, this enhancement will provide an additional field on the header to allow the classification of the outline agreement for migration without a legal contract, or not for migration. The population of this field will assist Syensqo to categorize outline agreements:

• which have been verified as not having a current legal contract but require migration to S/4 HANA
• which have been verified to not be migrated
• which still require verification for migration or not, or association to an Icertis agreement

The BW Consolidation Report (ERP-503 Consolidation Report Icertis SAP ECC Outline Agreements - Story) includes both fields and will provide the users with a working list to identify outline agreements which require one (usually not both) of these fields to be set.

The categorization of outline agreements in this way will assist in the management of activities relating to the migration of outline agreements to S/4 HANA. Agreements which have already been categorized as 'not for migration' or 'migrate without a legal contract' can be identified on the report of outline agreements without an ICM contract (ERP-503 Consolidation Report Icertis SAP ECC Outline Agreements - Story) to avoid repeat analysis of them. From a business process point of view, it is recommended that users enter a more detailed reason in an internal text for the omission of a legal contract.

Both the ICM Agreement Code and the OA Verification fields are available to update via the standard mass maintenance transaction for outline agreements (MEMASSCONTRACT). However, mass maintenance is more complex, makes available the mass update of all header and line-item fields, and is mostly used only by GBS for specific outline agreement changes. This custom developed transaction will make updates to these two fields only in a user-friendly, low-risk format.

For the correction of other key data in SAP ECC which is not aligned with Icertis, the existing upload programs for change outline agreement can be used, or the contract can be changed directly in transaction ME32K.

Process Flow Diagram

Assumptions

N/A

Dependencies

In order to assign an ICM Agreement code to the Outline agreement, the ICM Agreement code must exist in the ZMM_ICM* Tables. This logic is covered in ERP-259 Enhancement for Storage of Icertis ID on OA Header.

The selection of the relevant outline agreements and the field update values is required prior to the loads into SAP. The reporting of outline agreements relevant for the update of these fields is via the BW Contract Consolidation Report ERP-503 Consolidation Report Icertis SAP ECC Outline Agreements - Story

The preparation of a load file based on the template for the program is required prior to loading.

Security, Integrity and Controls

The new program will be assigned to a transaction code so that contract specialists and GBS employees can run this new application. 

It is not required to create any new authorization objects given that when trying to change the Outline Agreement, SAP will check that the user has access to modify the document (including Org checks).

The new transaction will be added to an existing role in WP2 and PF2.

It is suggested to use a BAPI to change the outline agreements, which can also help us to run the program in test run mode and leverage the error log coming from table RETURN. 

Configuration Requirements

The new field "OA Verification Status" will be included in the contract header screen on ME31K / ME32K and ME33K and will have the following behavior:

1. Field is optional.
2. Only allowed values are:
   1. 01 - Verified without ICM Contract
   2. 02 - Do Not Migrate

Language Requirements

N/A

Special Requirements

N/A

Design Rationale

Functional Requirements

This custom program is to take field values from a spreadsheet and make new entries into the fields for the specified outline agreement.

The columns in the spreadsheet will have column headings which are the field names in the tables.

The initial selection screen will have fields to hold the location of the relevant upload file.  Checks and validations will be carried out prior to the updates. The user running the program must clear the errors before proceeding to load. Table records as per the spreadsheet content are updated directly.

Template spreadsheets can be downloaded within the program for ICM Code update and OA Verification update.

Test mode will complete the checks and validations and list any error messages based on the updates for each outline agreement. Test mode will also show the current value of the field being changed alongside the new value from the spreadsheet file.

A blank value in the file for an outline agreement will clear the current content of the field being updated. A warning message will be provided during test mode where a blank value is being uploaded to a field which already has an existing entry which is not blank.

The following table explains functionally the combinations that can happen on outline agreement. It is not required to validate all combinations. This is a logical/functional explanation on what it would mean for an OA Agreement with different combinations on both fields. The combination of a valid ICM Code and 01 Verified Without ICM Contract is the only combination which is not permitted.

Proposed Technology to Use

It is suggested to:

• Create a new custom field in EKKO table for "OA Verification status" under the same append structure used for field ZZICMAGREEMENTCODE (append structure ZSMM_ICMAGREEMENT_EKKODB).
• Replicate similar behavior for screen interaction used with ZZICMAGREEMENTCODE (User Exits ZXM06U36, ZXM06U37 and ZXM06U43).
• Enable the OA Verification Status field to be updated via mass maintenance transaction MEMASSCONTRACT.
• Create a new ABAP program which will be responsible to modify the Outline Agreement fields based on spreadsheets with the required values in each field. This program calls BAPI_CONTRACT_CHANGE which will allow to run program in test mode to validate entries before changing the contract and also to provide an error log on the screen for users to verify if updates are going to be successful.
• Create a new Transaction code which invokes this new program.
• Include the new transaction code in existing roles so that relevant users have access to the new developed program.

Data Source Considerations

All data required for the table entries will be provided in the spreadsheet. The formats of the spreadsheets (one for the ICM Agreement Code and one for the OA Verification Status) are shown below and a sample file provided for unit testing.

The column labels in the spreadsheet are the same as the field name in the tables.

A sample file for loading ICM Agreement Code or OA Verification Code is available here:  Agreement Code and Verification Field Update Template.xlsx - Google Sheets

Data Validation Considerations

The standard BAPI to change contract should validate the fields according to the logic already defined in user exits which validate format of ZZICMAGREEMENTCODE and the new field introduced under this spec (OA Verification Status).

An outline agreement with an ICMAGREEMENTCODE entered, and the OA Verification Status set to 01 Verified without ICM Contract is not permitted. Error message: 'Outline Agreement xxx has ICM Code, 01 status not permitted'

The following data validations are carried out in both test and update modes:

Custom Tables

N/A

Master Data

N/A

Configuration Table

The new field "OA Verification Status", which will be included in table EKKO, will need to have 2 allowed values (+ blank):

Selection Screen Enhancement

The selection screen of the new program will allow the user to between two radio buttons to update one field at a time:

• Update ICM Agreement Code
• Update OA Verification Status

A checkbox parameter field called "Test Run" will allow users to verify if all records can be updated before doing the actual update. 

Options to download a template spreadsheet for ICM Agreement Code and OA Verification Status Update is available from the initial screen.

Following picture shows a tentative layout for the screen. 

Processing Logic

On the New TCODE:

Once the user has completed the Outline agreements + the field to be updated (either ICM Agreement Code or OA Verification Status), the program should prepare records to call BAPI_CONTRACT_CHANGE. 

The two custom fields are typically populated by table EXTENSIONIN.

The field Test Run will need to be populated from the parameter in the selection screen. This will determine if update will be saved on DB or just a test run is required. This will allow users to validate all records before processing.

We suggest to read the output of table Return and provide a log in an ALV fashion so that users know for each OA Processed if there are any errors or if update is successful. 

In ME31K →

On ME31K user should be able to populate the new created field "OA Verification Status" and then it should be saved in EKKO. The allowed values are the ones defined by the data element (01, 02 or Blank).

In ME32K → 

On ME32K, if a value is already saved on EKKO for field "OA Verification Status", the content of the field will need to be retrieved by the DB Table EKKO and presented on screen.

If a user decides to change the value in ME32K, the value will need to be validated according to the data element and saved in table EKKO.

In ME33K →

On ME33K, if a value is saved on EKKO for field "OA Verification Status", the field will need to be retrieved from the DB and presented on Screen. 

In MASS -->

• Enable the update of the OA Verification field on the outline agreement header via the standard mass update transaction MEMASSCONTRACT (the same as has been done for ICMAGREEMENTCODE field in ERP-259 Enhancement for Storage of Icertis ID on OA Header.

Volumetrics

There are approximately 3000 purchase contracts being loaded in Icertis Contract Management. A portion of these will be relevant for outline agreements (only Sub Agreement and Standalone Agreement types). No ICM Agreement Codes will be entered on existing outline agreements as part of the introduction of Icertis and the load of legacy contracts. Progressively Syensqo will use the BW Report (ERP-503 Consolidation Report Icertis SAP ECC Outline Agreements - Story) to identify outline agreements which need a corresponding Icertis code assigned and update the records. Similarly, they will progressively do the work to identify orphan outline agreements and determine if they are relevant for migration and if they require a legal contract.  Updates will therefore be inconsistent based on the analysis carried out by Syensqo.

Performance Considerations

There are no specific performance considerations to take into account.

Error Handling

The new program will need to display the output of RETURN table from BAPI_CONTRACT_CHANGE in screen in an ALV so that users can see the status of their operation performed (either successful or with details errors to understand the issues).
Lock entries on the relevant outline agreement number which prevent the update occurring will be shown in the log in both test and update mode.

Testing

How to Test

Test Conditions and Expected Results

Test Considerations/Dependencies

N/A

Other Information

Development Details

Package

Enhancement Implementation

Other Development Objects

Appendix

Custom Authorization Group Naming Convention

This table is based on the Syensqo development standards document. It provides the naming conventions for authorization groups to associated with custom reports and tables to comply with security requirements.

See also

Change log