CX Works

CX Works brings the most relevant leading practices to you.
It is a single portal of curated, field-tested and SAP-verified expertise for SAP Customer Experience solutions

Developing SAP Commerce Cloud Locally

19 min read

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 (release notes, documentation) - available only for Commerce Cloud on Public Cloud customers using SAP Commerce Core 1905. Releases occur each month.

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


If you think you can only solve your issue through running ant customize, please engage SAP CX Services before doing so.

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_"
            }
    }

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.


Not all extensions are supported by SAP Commerce Cloud. Before including an extension in your localextensions.xml, please consult the Compatibility Matrix page to determine if it is supported.

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.


Enable the following property in your local development environment for logging when a non-serializable object is added to an HTTP session: session.serialization.check=true

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:


You can click on the word "cloud" or "pie chart" to filter down to a particular aspect and/or log level.



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


You can click on the word "cloud" or "pie chart" to filter down to a particular aspect and/or HTTP Status.


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

Term

Definition

Monitor A job that runs on a defined schedule and queries Elasticsearch. The results of these queries are then used as input for triggers.
Trigger Conditions, if met, generate alerts and can perform some action.
Alert A notification that a monitor’s trigger condition has been met.
Action The information that you want the monitor to send out after being triggered. Actions have a destination, message subject and message body.
Destination A reusable location for an action, such as Amazon Chime, Slack, or a webhook URL.

Create Destinations

  1. Choose AlertingDestinationsAdd 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 AlertingMonitorsCreate 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
      {
        "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"
            }
          }
        ]
      }
  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 AlertingMonitors.
  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 

Variable

Description

ctx.results An array with one element (i.e. ctx.results[0]). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See ctx.error.
ctx.monitor Includes ctx.monitor.namectx.monitor.typectx.monitor.enabledctx.monitor.enabled_timectx.monitor.schedulectx.monitor.inputstriggers and ctx.monitor.last_update_time.
ctx.trigger Includes ctx.trigger.namectx.trigger.severityctx.trigger.condition, and ctx.trigger.actions.
ctx.periodStart Unix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every ten minutes, a period might begin at 10:40 and end at 10:50.
ctx.periodEnd The end of the period during which the alert triggered.
ctx.error The error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise.
ctx.alert The current, active alert (if it exists). Includes ctx.alert.idctx.alert.version, and ctx.alert.isAcknowledged. Null if no alert is active.

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.

If you don’t want to receive notifications for alerts, you don’t have to add actions to your triggers. Instead, you can periodically check Kibana.

  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}}

Sample Action Configuration

Kibana Alert

Work with Alerts

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

State Description
Active The alert is ongoing and unacknowledged. Alerts remain in this state until you acknowledge them, delete the trigger associated with the alert, or delete the monitor entirely.
Acknowledged Someone has acknowledged the alert, but not fixed the root cause.
Completed The alert is no longer ongoing. Alerts enter this state after the corresponding trigger evaluates to false.
Error An error occurred while executing the trigger—usually the result of a a bad trigger or destination.
Deleted Someone deleted the monitor or trigger associated with this alert while the alert was ongoing.

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.

Overlay