SAP Cloud Integration - Upgrade Readiness Design Guidelines/Best Practices for Future Readiness

[kamlesh_zanje]

Introduction

Have you ever wondered where to start to understand the benefits of upgrade readiness design guidelines for your cloud integration system and how to achieve them? Then this blog post is for you! It brings you in-depth insights into the upgrade readiness concept and its implementation, with resources to help make your integration artifacts, prominently Groovy scripts, future-proof.

Whether you're developing integration scenarios in SAP Integration Suite or refining existing ones, this is your guide to ensuring long-term stability, maintainability, and resilience - even in the face of major runtime upgrades.

In this blog post, you will understand the detailed aspects of upgrade readiness, its objectives, principles and how to leverage in the integration flow tooling. With the 7.45 version in NEO and 6.72/8.36 in Cloud foundry release,  SAP Cloud Integration provides a upgrade readiness feature.

Why is Upgrade Readiness Essential?

One of the most powerful features of SAP Cloud Integration is the Groovy flow step, which allows developers to write custom Groovy scripts to solve complex problems efficiently. However, these scripts can create risks for future upgrades, especially when they rely on:

• Unsupported system classes.
• Internal Apache Camel framework classes.
• Undocumented Java libraries.

Using these internal or unsupported classes may not only result in incompatibility during major runtime upgrades but can make the system fragile and prone to failures, something many of you may have experienced during previous major version upgrades.

What is Upgrade Readiness?

Upgrade readiness is a set of best practices, guidelines, rules, or tools designed to ensure scripts are clean, consistent, and ready for future upgrades. It promotes a development approach that helps maintain the stability and reliability of integration artifacts and minimizes the risk of breakdown during major runtime version upgrades in SAP Integration Suite.

Here’s how upgrade readiness can help:

1. Restrict Usage of Internal APIs: Avoid APIs that are unsupported or pose risks during upgrades.
2. Identify Violations in Groovy Scripts: Detect and fix problematic script patterns, such as unused imports or usage of internal APIs.
3. Encourage Using Recommended Libraries and Standards: Build scripts that align with SAP's recommended practices and approved APIs.

Upgrade Readiness Guidelines

Adhering to these guidelines promotes a robust, scalable architecture that withstands future system upgrades. Let’s explore key considerations.

Remove Unused Imports

Unused imports create unnecessary complications during software or runtime upgrades:

• Avoid compilation/runtime errors: Unused imports might reference deprecated libraries or classes, potentially breaking the script.
• Eliminate visual clutter: It helps streamline script functionality while avoiding confusion about dependencies.

Best Practice: Scan all Groovy scripts for unused imports and remove them to ensure clean and efficient code.

Use Recommended Libraries and Classes

A crucial step in creating upgrade-ready artifacts is using only recommended or SAP-approved libraries and APIs:

• Avoid Internal Classes: Replace direct usage of internal classes (e.g., Apache Camel) with SAP-provided APIs and extensions.
• Leverage supported libraries: Always rely on SAP APIs for safe system interactions, reducing risks from dependency issues during updates.
• Bundle custom libraries carefully: If a critical library isn’t provided by SAP, include it as part of your integration flow. However, be aware that this may impact flow size and startup performance.
• Restrict OS/Network access: Avoid direct file/system operations; use alternatives provided by SAP.

Examples of unsupported classes to avoid:

• System.exit() or TimeZone.setDefault()
• Direct access to environment variables using System.getenv() or System.getProperty()
• Console outputs like System.out.println()

Instead, use alternatives like SAP API com.sap.it.script.system.Properties for environment-safe interactions.

Refer KBA to know the list of incompatible internal classes.

Plan Proactive Cleanup of Existing Scripts

As part of preparing your system for future upgrades, ensure current scripts are compliant with upgrade readiness guidelines.

• Start cleanup processes for existing artifacts adhering to the new framework.
• Focus on creating awareness among development teams about unsupported script patterns.
• Get familiar with the upgrade readiness toolset in SAP Integration Suite.

Upgrade Readiness Objectives and Strategy

Upgrade readiness is more than just avoiding future system breakdowns; it’s about establishing a future-proof integration development model.

Objectives:

1. Enable future proofing: Build robust integration artifacts that are immune to frequent version upgrades.
2. Ensure maintainability: Maintain clean, stable, and compatible integration scripts.
3. Reduce upgrade risks: Proactively address dependencies on unsupported libraries and APIs.

Strategy:

• Introduce upgrade compliance guidelines for current SAP Cloud Integration stacks (NEO, CF) to foster awareness.
• Collaborate with teams to initiate self-service cleanup of existing artifacts.
• Provide training and resources to ensure developers are well-versed in upgraded best practices.

Upgrade Readiness Principles

1. Code Cleanliness

   • Remove unused imports.
   • Write concise, maintainable scripts.

2. Avoid Unsupported APIs and Classes

   • Avoid internal, deprecated, or system-level APIs.
   • Refrain from direct OS manipulations.

3. Use Recommended Libraries and APIs

   • Use SAP-provided or approved APIs.
   • Replace unsupported libraries with standard alternatives.

4. Plan for Future Compatibility

   • Design artifacts resilient to runtime upgrades.
   • Ensure compatibility with future software updates.

5. Reduce Code and Visual Clutter

   • Eliminate unnecessary logs and code blocks.
   • Keep scripts streamlined and easy to understand.

6. Enable Proactive Cleanup

   • Regularly review and update integration artifacts.
   • Clean up older stacks like NEO and CF deployments.

7. Avoid Operating System Manipulations

   • Avoid direct OS interactions.
   • Use platform-provided APIs for secure operations.

8. Train Teams on Best Practices

   • Educate developers on best practices.
   • Promote awareness of upgrade readiness tools.

9. Utilize Upgrade Readiness Tools

   • Use tools to monitor for violations.
   • Proactively identify and resolve issues.

Implementing these principles ensures stable, future-proof integration artifacts.

Steps to Apply Upgrade Readiness

Applying upgrade readiness and future-proofing your integration artifacts involves following a set of best practices and utilizing the tools provided within the integration platform. Below, we outline the steps to achieve this:

Access Integration Settings Page

• Navigate to the Integration Settings page.
• Here, you will find the newly introduced upgrade readiness design guidelines, which are activated by default

Open Integration Flow Editor

• Access the integration flow editor where you design and manage your integration artifacts.
• You will notice the same set of upgrade readiness design guidelines applicable here.

Execute Guidelines and Check Compliance Status

• Execute the guidelines to see the compliance status of your integration artifacts.
• Specifically check for non-compliant Groovy flow steps. Analysis feature will show the list of affected groovy scripts. Check the version of the groovy script as well.

Open the Script Editor

• Open the script editor to examine the issues highlighted in the problems view.
• Note that upgrading to Groovy step 2.x can fix crucial violations related to internal Camel and stack class usage.

Apply Fixes and Recommendations

• Follow the suggested fixes and recommendations to make your Groovy scripts future-ready.
• Save the Groovy script by clicking Apply and then close the editor to return to the integration flow editor.

Save the Integration Flow

• Save your integration flow to ensure that all changes are persisted.
• Verify the version of the Groovy flow step is updated to 2.x.

Re-evaluate Compliance

• After applying the upgrades, execute the guidelines again to ensure that the previously violated Groovy steps are now compliant.

Important Note

• You can leverage the public OData Remote APIs to read, execute and download the guidelines at the integration flow artifact level. This will promote the automation.
• Refer to the documentation for details: Integration Flow Design Guidelines.

Why Groovy Script 2.x?

Upgrading to Groovy script 2.x provides several benefits:

• Future-Ready Scripts: Automatic fixes for incompatible libraries and classes prepare your scripts for future major version runtime and software upgrades.
• Advanced Groovy Features: Utilizes Groovy runtime 4.0.29, providing access to modern language elements such as switch expressions and other capabilities. You can refer the groovy 4.0.29 for more details.

Handling Non-Compatibility

If the updated version of the Groovy step does not yield the expected result then take the below measures.

1. Downgrade Groovy Script: You can downgrade the Groovy script step and revert to the older version.
2. Create a ServiceNow ticket : Document the issue and create a ticket using the component LOD-HCI-PI-WT-IFL for further assistance. Issue will be fixed as per the SLA.
3. Adapt Processes: Adapt your business processes to accommodate the upgraded script to stay prepared for future upgrades. You should strive to be on the major version of the script step.

By following these steps, you can ensure that your integration artifacts are compliant with the latest guidelines and ready for future upgrades.

What’s coming next

• Upgrade Readiness Guidelines for JavaScript.
• Execute Design Guidelines Automatically on Artifact Save.
• Block Artifact Deployment if Guidelines Are Violated, Governed by Tenant Administrator.
• Central Dashboard Displaying All Incompatible Scripts at Tenant Level.

Share your feedback in the comment section on these upcoming innovations and provide your remarks on the prioritization.

Other source of material

• Upgrade groovy script
• new design guideline: recommended classes 
• KBA Article

I hope you find the enhancements in this blog post beneficial. If you have any questions or feedback, please leave a comment.