High- Level Specification

Functional Overview

This enhancement introduces a custom event job in Icertis to send default event payloads (matching the stream event payload) to SAP CPI for specific agreement lifecycle events: Amendment Executed, Renewal, Legacy Load and Termination. The enhancement addresses current gaps in Icertis’ out-of-the-box event streaming, enabling real-time integration with SAP for these critical contract milestones. The solution will include robust error handling (logging and retry mechanism) to ensure reliability and traceability.

Scope and Objectives

Scope:

• Configure a custom event job in Icertis to trigger on the following agreement events:
  • Amendment Executed (when an amendment agreement is executed)
  • Renewal (when an agreement is expired and renewed)
  • Termination (when an agreement is terminated)
  • Update of Tracking Attributes after agreement is Executed.
  • Published event during Legacy load of agreements
  • Amendment Published event during legacy load of amendments
  • Association Peer Linkage event for linking legacy sub-agreement with respective master agreement.
• Send the default event payload to SAP CPI via a webhook or REST API.
• Implement error handling: log errors and provide a retry mechanism for failed transmissions.

Objectives:

• Enable real-time, automated communication of key contract lifecycle events from Icertis to SAP.
• Ensure SAP systems are always up-to-date with the latest contract status (amendment, renewal, termination, Published event for Agreement Legacy Load, Published event for Amendment legacy load, Association Peer Linkage).
• Provide robust error handling and traceability for integration failures.
• Close the gap in Icertis’ standard event streaming, which does not natively support these event types for external integration.

Gap Addressed:

• Icertis’ standard event streaming does not cover Amendment Executed, Renewal, Published event for Agreement Legacy Load, Published event for Amendment legacy load, Association Peer Linkage and Termination events for external integration.
• This enhancement ensures these events are captured and communicated to SAP CPI, enabling downstream SAP processes to react in real time.

Assumptions

• Icertis event streaming and webhook configuration is available and can be extended for custom events.
• Retry mechanism will be limited to a configurable for 3 number of attempts.
• Error logs will be accessible for support teams.

Dependencies

• Scheduling of the event job should not conflict with other critical jobs.
• Any changes to event types or payload schema in Icertis must be communicated to SAP CPI integration team in advance.

Security, Integrity and Controls

• Audit Logging: All API calls, event payloads, and data changes must be logged
• Error Handling: All errors must be logged with sufficient detail for troubleshooting

Configuration Requirements

• Configurate the Event streams for following events
  • Amendment Executed, 
  • Auto-Renewal
  • Termination
  • Update of Tracking Attributes after agreement is Executed.
  • Legacy Load of Agreements
  • Legacy Load of Amendments
  • Peer Linkage of Associations
• SAP CPI endpoint URL and authentication details.
• Retry parameters (number of attempts, interval).
• Error log table/configuration.

Language Requirements

• All labels, logs, and error messages will be in English.

Special Requirements

• If any changes are made to the agreement tracking attributes while the agreement status is Executed, and the user clicks the Update event, a message should be sent to SAP CPI.
• However, the Update event in Icertis can also occur during the Draft stage or when an executed agreement is edited. The custom task must ensure that messages are sent only when the Update event occurs for agreements with status Executed, and not during the Draft stage.

Design Rationale

Functional Requirements

• Capture specific contract lifecycle events in Icertis.
• Send event payload to SAP CPI in real time.
• Log all events, successes, and failures.
• Retry failed transmissions as per configuration.

CR0397 Requirements

During legacy load testing, it was observed that agreements loaded into Icertis as part of the legacy data load were not being replicated to the ECC Z-table. Further analysis confirmed that event configurations for legacy-loaded agreements were not enabled, which resulted in the missing data synchronization.

CR0397 addresses this gap by enabling data synchronization between Icertis and the ECC Z-table through customization of event streams for the Published event applicable to legacy agreements.

Scope

• Legacy agreements uploaded into Icertis should be synchronized to the ECC Z-table, similar to other lifecycle events such as Executed, Amendment Executed, and Terminated.
• Follow‑up amendments created for legacy agreements as part of BAU should also be synchronized with the ECC Z-table, in line with the Amendment Executed event.
• Sub‑agreements created for legacy master agreements should be correctly linked, consistent with the current behavior for sub‑agreements created under Executed events.
• Auto‑renewal of legacy agreements should trigger synchronization events similar to auto‑renewals of agreements created directly in Icertis.
• Termination of legacy agreements should also be synchronized with the ECC Z-table.
• Updates to tracking attributes on legacy agreements should be synchronized with the ECC Z-table.
• Confidential legacy agreements should be excluded from synchronization with the ECC Z-table.

Configuration Requirements

Configure event streams for following events:

1. Published event during Legacy load of agreements
2. Amendment Published event during legacy load of amendments
3. Association Peer Linkage event for linking legacy sub-agreement with respective master agreement.

Special Requirements

1. Event streams on Agreement Draft "Publish" should not be triggered and sent to ECC.

Sample Payload:

{
    "id": "c827d613-a5a5-4c2d-9d7d-8898abd92715",
    "source": "/icertis/mycompany",
    "type": "com.icertis.mycompany",
    "data": {
        "EventHash": "6R0AQ/viamcLKQ73E4/lXNrgPaIS8xStSHP7MPDpNW8=",
        "EventMessage": {
            "EventStreamId": "f64fc1fb-0ee6-41a2-8dd3-6727363a28a5",
            "EventStreamName": "AutomationBasicAgreement-CreatedAndUpdate",
            "EventId": "65638f47-42dc-4aee-85c5-aed814705121",
            "ResourceType": "Agreement",
            "ContractTypeName": "ICMAutomationBasicAgreement",
            "ActionName": "Created",
            "FromState": null,
            "ToState": null,
            "EventBy": "d82605cb-cf47-4427-bed4-525fe568fdd3",
            "EventDateTime": "2024-04-12T07:16:17.9661276Z",
            "ExternalId": "",
            "SysId": "35913105-9ae6-454e-aa59-ce13da70ee54",
            "CorrelationId": "6f470533-f498-4f23-acb0-764da4cc2d31"
        }
    }
}

Proposed Technology to Use

• Icertis custom event job (webhook or REST API call).
• SAP CPI as the integration middleware.
• SAP BADI/User Exit for downstream SAP processing (if required).

Data Source Considerations

Data Validation Considerations

Processing Logic

• Listen for configured event types in Icertis (Amendment Executed, Renewal, Termination, Legacy Load - Published).
• On event, prepare default payload.
• Send payload to SAP CPI endpoint via HTTP POST.
• If success, log event as success.
• If failure, log error and retry as per configuration.

Volumetrics

• Initial load: N/A (event-driven, not batch).
• Expected frequency: Low to moderate (depends on contract activity).
• Growth: Linear with contract volume.

For example, if Syensqo manages 1,000 contracts and, on average, 5–10% of contracts undergo amendments, renewals, or terminations per month, then the expected event volume would be 50–100 events monthly. The volume grows linearly because each new contract added to the system has the potential to generate Amendment, Termination, Renewal events over its lifecycle.

For legacy agreements, Icertis will send the legacy agreement details to CPI when Published event is triggered. If 1000 agreements are loaded in a single batch, Icertis will send 1000 unique events to CPI. When Legacy load activity takes place, the published event for those agreements are sent to CPI, the agreements are identified where its flag is set as isLegacy = true

Performance Considerations

• Performance: Must process events in near real-time; retry logic should not block other events.

Error Handling

• All errors logged in Icertis standard log table. Support team will have access to monitor the success/failed logs
• Retry mechanism as per configuration.
• Notification to support team if repeated failures occur.

Testing

How to Test

• Trigger each event type in Icertis (Amendment, Renewal, Termination).
• Validate payload received in SAP CPI.
• Simulate endpoint failure to test retry and error logging.
• Check logs for all events.

Test Conditions and Expected Results

Test Considerations/Dependencies

Not Applicable

Other Information

Development Details

Package

Enhancement Implementation

Other Development Objects

See also

Change log