Overview

Developing SAP Commerce Cloud Locally

SAP Commerce Cloud provides a standardized, automated end-to-end build and deployment solution for Commerce projects to release code from the repository to the cloud.

Many aspects of SAP Commerce Cloud overlap with the capabilities of continuous integration (CI) and continuous delivery (CD) solutions such as Jenkins. However, SAP Commerce Cloud is not a wholesale replacement for Jenkins, which supports many other capabilities and use cases beyond the scope of SAP Commerce Cloud.

This article outlines the best practices of using SAP Commerce Cloud as part of your project, as well as being covered in this video.

Table of Contents

General Development Best Practices

Before starting this article, you should read through the general best practices and guidelines for working with SAP Commerce Cloud that are covered in the product documentation. These practices can be found here. The following article will cover the development practices for implementing SAP Commerce Cloud solutions.

Release Cadence

As outlined in "Getting Started with SAP Commerce Cloud", your SAP Commerce Cloud solution may consist of a few different code bases that are are all merged as part of the build and deploy process:

Automatically Upgraded:

• SAP Commerce Cloud automation (release notes) - feature releases typically occur every 1-2 months, patches ongoing.
• SAP Commerce Cloud Extension Packs - available only for Commerce Cloud on Public Cloud customers using SAP Commerce Core 1905. Replaced starting with Commerce 2005 by the Integration Extension pack (see below)

Requires the use of a compatible version:

• SAP Commerce (release notes) -  See the release notes for the most up to date version. Previously, there were new releases every quarter, but this will be reduced going forward to as little as one release per year.
• Spartacus Javascript storefront (documentation) - ongoing. Pull code for the latest.
• Industry accelerators (documentation) - dependent on the industry accelerator. See the compatibility matrix in the documentation to determine which combination of industry version and SAP Commerce are compatible.
• Integration Extension Pack (documentation) - with the release of SAP Commerce Core 2005 the integration extensions have been split into their own separate artifact, which allows for a separate cycle for improving integrations. New versions may be released on demand, as often as quarterly.
• Data Hub (documentation) - dependent on the SAP Commerce release.

In some cases, there is a dependency on the correct code version to ensure compatibility with your SAP Commerce Cloud solution. You should check the compatibility page to ensure you are using the right version for each code base. You have the ability to determine when to upgrade certain portions of your solution.

Connect your Code Repository

SAP Commerce Cloud takes into account your code customizations which are stored in a Git-based code repository. Once you have access to the SAP Commerce Cloud portal, it is essential that you connect your code repository as shown in the following video:

https://microlearning.opensap.com/media/1_k7dw7g1m.

We strongly recommend that you do not store any private properties (for example, passwords) in your source code repository. Instead, to define these sensitive properties, you should leverage the Service Configuration option in the SAP Commerce Cloud portal for each endpoint.

Third-Party Java Libraries

To keep the source repository footprint small and to make library updates simple and reliable, each Commerce Platform extension is able to use Maven to manage them.

Ant Customize

Sometimes, it may appear necessary to customize the platform code delivered as part of Commerce. This may be because you are unable to extend or override the code, or you need a different jar file, or you are required to patch certain files in your existing SAP Commerce suite. This would normally be done using the "ant customize" target.  Please be aware SAP Commerce Cloud does not currently support running the "customize" target.

Configuration Reuse

When moving from local development to cloud environments, it is important to consider how you can reuse your configurations. As outlined in this page of the product documentation, the following local configurations can be linked in your manifest.json file:

• Solr
• Properties
• Extensions
• Languages

Solr

As outlined in Getting Started with SAP Commerce Cloud, SAP Commerce Cloud typically uses a cloud setup of Apache Solr which includes three Zookeeper nodes and two Solr nodes. You can configure your code repository to customize how Solr is configured (for example, solrconfig.xml) to ensure it works the way you need it to. Keep in mind, that any changes you make to your Solr configuration could break your search functionality. If you need to customize Solr for your SAP Commerce Cloud solution, please see this section in the product documentation. It covers the compatibility requirements, repository setup and manifest.json configuration. If you're looking for more information on improving your search functionality, please see Search and Navigation in SAP Commerce Cloud - An In-depth Series.

Language Packs

You should try to include only the languages you will support, as unnecessary languages can slow down the build and deploy cycle. If you the use of language packs, you can have them deployed using the following:

1. In the root of your code repository, create a folder for storing language packs, such as "_LANGUAGES_”.
2. Add your language pack zip files to this folder.

3. Add the following property to your manifest.json with only the languages you have.

   
   

       "useConfig":
   {
   		...
           "languages" : {
               "location": "_LANGUAGES_"
           }
   }

   Copy this code!

Extensions

In order to keep your configurations in sync between your local and the SAP Commerce Cloud environments, you should configure your manifest.json file to point to your localextensions.xml file as covered in this page of the product documentation. If you have some extensions you use locally, you should make use of the "exclude" option to ensure they are not deployed in your SAP Commerce Cloud environments.

HTTP Session Failover

Sessions, used by clients that are bound to an individual cluster node, stick with the cluster node. Consequently, an SAP Commerce Cloud cluster uses sticky sessions. In addition,  SAP Commerce Cloud  offers a session failover mechanism. For more details, see HTTP Session Failover.

Complete Manifest.json

This page of the product documentation covers the many different components of a manifest.json file. There are also many different example manifest files for a variety of common scenarios.  For a complete manifest.json file that reflects different properties files per environment and aspect, languages packs, multiple add-ons, the definition of the aspects, and the ability to run various types of tests please see the open source code sample. You can find the detailed steps for setting up your environment in Build and Deploy Your First SAP Commerce Cloud Project.

Monitoring and Troubleshooting

Application Performance Monitoring (APM)

Each node in each environment includes Dynatrace agents that are used to monitor the health of the environment as well as to help troubleshoot issues. You can access the full stack monitoring capabilities of Dynatrace through the SAP Commerce Cloud Portal. See this page in the documentation for more. If you need assistance with the performance of your site, please contact your Customer Engagement Executive, or contact SAP CX Services to find the nearest available SAP Customer Experience representative.

To learn how to access your Dynatrace instance please see Using Dynatrace to Manage and Optimize the Performance of your SAP Commerce Cloud Solution.

Centralized Logging

Each environment of SAP Commerce Cloud comes with its own centralized logging endpoint which launches Kibana. This provides a single point to review logs for the aspects defined in your manifest.json file. The following covers the centralized logging with instructions:

If you are unfamiliar with Kibana or are looking for a quick start, we have attached the  Commerce Cloud Kibana Example.json to this page. This contains some helpful dashboards, searches and visualizations. To use it:

1. Follow steps #1 and 2 from the product documentation to launch Kibana.
2. Download Commerce Cloud Kibana Example.json.
3. Select Management → Saved Objects → Import.
   
   
   
   
   
   
4. Upload the JSON file you downloaded in the step above.
5. Click on the "Dashboard" option in the left panel to select one of three dashboards:

Dashboard - Cloud: Overview of what is occurring across all servers:

Dashboard - Console Logs: Overview of what is occurring in the console logs:

Dashboard - Access Log: Overview of access logs for your storefront and backoffice servers:

Kibana Alerting

The alerting feature notifies you when data from one or more Elasticsearch indices meets certain conditions. For example you might want to:

• be notified via a Slack channel if your application logs more than five HTTP 503 errors in one hour
• you might want to page a developer if no new documents have been indexed in the past 20 minutes
• be notified when log pattern matching found in log file

Use Case

In the following example we want to receive an alert on Slack from Kibana, when SAP Commerce Cloud Log contains a message or matches a string "No populator configured for option [VARIANT_FIRST_VARIANT]" with log level as WARN on accstorefront aspects. 

Key Terms

Create Destinations

1. Choose Alerting, Destinations, Add destination.
2. Specify a name for the destination so that you can identify it later.
3. For Type, choose Slack, Amazon Chime, or custom webhook.
4. Specify the webhook URL. These requests use the HTTP POST method.

For more information about webhooks, see the documentation for Slack and Chime.

Slack web-hook and Kibana Destination Configurations

Create Monitors

1. Choose Alerting, Monitors, Create monitor.
2. Specify a name and schedule for the monitor.
3. Choose one or more indices. You can also use (flb*) as a wildcard to specify an index pattern.

4. Define the monitor, select Define using extraction query.

   • Query definition gives you flexibility in terms of what you query for using the Elasticsearch query DSL( DSL ) and how you evaluate the results of that query
5. Add your query (DSL) at Define Extraction Query text box, and test it using the Run button.

   • sample query for our use case. The query look for match "No populator configured for option [VARIANT_FIRST_VARIANT]" message on log file with WARN log level of  hybris pods in accstorefront aspect. The query also looks for match with the time range within 5m from the the time of query execution

   • VARIANT_FIRST_VARIANT Expand source

     {
       "query": {
         "bool": {
           "must": [
             {
               "match": {
                 "kubernetes.labels.app_kubernetes_io/name": "hybris"
               }
             },
             {
               "match": {
                 "kubernetes.labels.ccv2_cx_sap_com/platform-aspect": "accstorefront"
               }
             },
              {
               "match": {
                 "logs.level": "WARN"
               }
             },
             {
               "match": {
                 "logs.message": "No populator configured for option [VARIANT_FIRST_VARIANT]"
               }
             },
              {
               "range": {
                 "@fb_timestamp": {
                   "gte": "now-5m"
                 }
               }
             }
           ]
         }
       },
       "sort": [
         {
           "@fb_timestamp": {
             "order": "desc"
           }
         }
       ]
     }

     Copy this code!
6.  The monitor makes this query to Elasticsearch as often as the schedule dictates; check the Query Performance section and make sure you’re comfortable with the performance implications.
7. Choose Create.

     Monitor Configurations 

Create Triggers

The next step in creating a monitor is to create a trigger. 

1. Choose Alerting, Monitors.
2. Select the Monitor created at previous step.
3. Click on Create button at Triggers section.
4. At Create Triggers page, Give a name to Trigger (e.g WARN-VARIANT-TRIGGER ).
5. Test your script using the Run button.

For Trigger condition, specify a Painless script that returns true or false. Painless is the default Elasticsearch scripting language and has a syntax similar to Groovy.

Trigger condition scripts revolve around the ctx.results[0] variable, which corresponds to the extraction query response. For example, your script might reference ctx.results[0].hits.total.value or ctx.results[0].hits.hits[i]._source.error_code.

A return value of true means the trigger condition has been met, and the trigger should execute its actions.

// Evaluates to true if the query returned any documents
ctx.results[0].hits.total.value > 0

Available Variables 

Trigger Configurations 

Add Actions

The final step in creating a monitor is to add one or more actions. Actions send notifications when trigger conditions are met and support Slack, Amazon Chime, and webhooks.

1. On Create Trigger page from Create Triggers section.
2. Specify a name for the action.
3. Choose a destination, like the previously created Slack destination.
4. Add a subject and body for the message.
   
   • You can add variables to your messages using Mustache templates. You have access to ctx.action.name, the name of the current action, as well as all trigger variables (Available Variables from triggers)
5. Click on Send Test Message link below message area text box to check the test message.

6. Choose Create.

   If you fail to receive test message on slack, there is a possibility netpol rule which will allow to access internet by Kibana/ES doesn’t exists. Raise a ticket to support/operation team to enable netpol.

   Sample Message

   Monitor {{ctx.monitor.name}} just entered an alert state. Please investigate the issue.
   - Trigger: {{ctx.trigger.name}}
   - Severity: {{ctx.trigger.severity}}
   - Period start: {{ctx.periodStart}}
   - Period end: {{ctx.periodEnd}}

   Copy this code!

Sample Action Configuration

Kibana Alert

Work with Alerts

Alerts persist until you resolve the root cause and have the following states:

Overview of Alert Dashboard

Conclusion

If you are familiar with developing SAP Commerce solutions, then the move to SAP Commerce Cloud will mostly require an adjustment to how your code is structured in your repository. Additionally, it will require an adjustment as to how best to configure your manifest.json file and how to use logging to your advantage. By understanding what you can and cannot do with SAP Commerce Cloud, you will be better positioned to deliver a successful SAP Commerce Cloud solution.