Installing SAP Commerce Cloud for use with Spartacus

The following instructions describe how to install and configure SAP Commerce Cloud release 1905 for use with a Spartacus storefront. In these instructions, SAP Commerce Cloud is installed to your local computer, so localhost is used in the browser URLs.

The installation procedure includes steps for creating and using a b2c_for_spartacus recipe that makes use of the Spartacus Sample Data Addon, but you can use you own sample data or recipe as long as it includes the cmsoccaddon and ycommercewebservices extensions.

The Spartacus Sample Data Addon makes a copy of the Electronics storefront with changes to content that work with the default Spartacus storefront. If you are trying out Spartacus for the first time using the default sample data, installing the Spartacus Sample Data Addon is required.

However, installing the Spartacus Sample Data Addon is not required in all cases. The Spartacus layout is CMS driven as much as possible, but there are a few areas where the CMS structure does not provide enough information. To address this, Spartacus includes a layout configuration that provides additional information for the layout rendering of the CMS content (specifically, the order of the page slots). This configuration is provided in the B2cStorefrontModule. It is important to understand that this specific configuration is tightly coupled to the Spartacus sample data, and that whenever you change the sample data (something that happens in all projects), you should introduce your own layout configuration. When you are ready to introduce your own layout configuration, do not import the B2cStorefrontModule, but instead, use the StorefrontModule that does not provide any layout configuration. The StorefrontModule is not dependent on the Spartacus sample data, and is most likely a good starting point for your project.

For more information about the changes that are implemented with the Spartacus Sample Data AddOn, see Spartacus Sample Data Addon.

Installing and configuring SAP Commerce Cloud for use with Spartacus involves the following procedures:

Setting up SAP Commerce Cloud
Configuring OCC credentials
Configuring CORS

Setting Up SAP Commerce Cloud with the Spartacus Sample Data Addon

Some of the steps in this procedure are derived from the documentation for installing SAP Commerce Cloud using recipes. For more information, see Installing SAP Commerce Using Installer Recipes in the SAP Help Portal.

Unzip the SAP Commerce Cloud zip archive.

Note: The name of the zip archive for release 1905 starts with CXCOMM1905#.... This folder will be referred to as CXCOMM* for the rest of these instructions.
Download the Spartacus Sample Data AddOn.

The Spartacus Sample Data AddOn is versioned and released with the Spartacus storefront library. You can download the latest version by clicking on spartacussampledataaddon.zip in the Assets section of the most recent release of the storefront library.

For example, to download the Spartacus Sample Data AddOn for the 1.4.0-next.1 release, you access the Assets section of the @spartacus/storefront@1.4.0-next.1 library here.
Unzip the spartacussampledataaddon.zip archive.
Move the spartacussampledataaddon folder to hybris/bin/modules/b2c-accelerator.

The spartacussampledataaddon folder can be stored anywhere in the modules folder. The b2c-accelerator folder is chosen as it contains other B2C sample data.
In the installer/recipes folder, duplicate the b2c_acc_plus folder.
Rename the copy of the b2c_acc_plus folder to b2c_for_spartacus.
In b2c_for_spartacus, open build.gradle with a text editor.
In the list of extensions, add the following:
```
extName 'spartacussampledataaddon'
```
You can put the new entry anywhere in the list of extensions, but it’s usually added near electronicsstore. The following is an example:
```
extName 'electronicsstore'
extName 'apparelstore'
extName 'spartacussampledataaddon'
```
Note: The Spartacus Sample Data AddOn copies data from the Electronics store, so the electronicsstore extension is required. Additionally, the time to initialize is longer because SAP Commerce Cloud builds the Electronics and Apparel stores, as well as the Electronics for Spartacus store. If you do not need to install the Apparel store, you can speed up initialization by removing extName 'apparelstore' from the build.gradle file.
In the addons { forStoreFronts('yacceleratorstorefront') section of the build.gradle file, add 'spartacussampledataaddon' to the names list. The following is an example:
```
 addons {
     forStoreFronts('yacceleratorstorefront') {
         names('spartacussampledataaddon', 'captchaaddon', ...
```
Save the file.
Open a terminal or command prompt window inside the CXCOMM*\installer folder.
Set up the recipe using the following command:
```
./install.sh -r b2c_for_spartacus -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd
```
If you are using Windows, change ./install.sh to install.bat.

Note: Starting with release 1905, SAP Commerce Cloud releases do not ship with a default admin password. You must specify a password when running recipe commands (as shown above), or you can specify a password in a file named custom.properties stored in CXCOMM*\installer\customconfig. See the Alternate Method for Setting the SAP Commerce Cloud Admin Password procedure below for information on setting a password in the custom.properties file.
Initialize the system using the following command:
```
./install.sh -r b2c_for_spartacus -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd initialize
```
Initialization of the b2c_for_spartacus recipe can take about 30 minutes. Sample data for this recipe includes Electronics, Apparel, and Electronics for Spartacus sample stores.

Start SAP Commerce Cloud with the following command:

./install.sh -r b2c_for_spartacus -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd start

Verify that the system is working.
- Display the Admin Console: https://localhost:9002
- Display Backoffice: https://localhost:9002/backoffice
- Display the Accelerator Electronics storefront: https://localhost:9002/yacceleratorstorefront/?site=electronics

Note: When setting up your Spartacus storefront, set the base site in app.module.ts to electronics-spa. The following is an example:

context: {
  baseSite: ['electronics-spa']
},

Configuring OCC Credentials

By default, SAP Commerce Cloud replies to OCC REST API calls that do not require authentication. For example, you can do the following:

Display Open API documentation: https://localhost:9002/rest/v2/swagger-ui.html
Display information about the Electronics base store: https://localhost:9002/rest/v2/electronics/basestores/electronics

To be able to register users and check out, SAP Commerce Cloud must be configured with a client ID and password. When required, your Spartacus storefront sends this client ID and password when communicating with the back end. For more information about OCC configuration, see Defining OAuth Clients in an Impex File in the SAP Help Portal.

The following procedure describes how to configure SAP Commerce Cloud to accept OCC REST API calls.

Open the Hybris Administration Console in a web browser at the following address: https://localhost:9002.
Hover your mouse over the Console tab, then click Impex Import.

Copy-paste the following code into the Import content field.

INSERT_UPDATE OAuthClientDetails;clientId[unique=true]    ;resourceIds       ;scope        ;authorizedGrantTypes                                            ;authorities             ;clientSecret    ;registeredRedirectUri
                                ;client-side              ;hybris            ;basic        ;implicit,client_credentials                                     ;ROLE_CLIENT             ;secret          ;http://localhost:9001/authorizationserver/oauth2_implicit_callback;
                                ;mobile_android           ;hybris            ;basic        ;authorization_code,refresh_token,password,client_credentials    ;ROLE_CLIENT             ;secret          ;http://localhost:9001/authorizationserver/oauth2_callback;

When you import this sample (which is the same as the sample that is provided in the SAP Commerce Cloud documentation), you add the following client ID and password:

client ID: mobile_android
password (or secret): secret

Note: The values for client ID and password are just samples. You would use different values for your production environments.

Click the Import content button.

You have now added a client ID and password to your Spartacus storefront configuration.
You can verify that the OAuth client has been successfully defined by entering the following curl command in a terminal or command prompt window:
```
curl -k -d "client_id=mobile_android&client_secret=secret&grant_type=client_credentials" -X POST https://localhost:9002/authorizationserver/oauth/token
```
The curl command sends a POST request for an access token, using the client ID and password that you added to the back end. The command should return something similar to the following:
```
{
  "access_token" : "550d9a25-87c8-4e76-af21-6174a1e56d5c",
  "token_type" : "bearer",
  "expires_in" : 41809,
  "scope" : "basic openid"
}
```

You can now start Spartacus! After you have configured SAP Commerce Cloud to accept OCC REST API calls, you can set up and start your storefront. See Building the Spartacus Storefront from Libraries for more information.

Configuring CORS

CORS (Cross-Origin Resource Sharing) defines a way for a browser and a server to decide which cross-origin requests for restricted resources can or cannot be allowed. Certain Spartacus functionality, such as checkout and consent management, may not work properly if the CORS OCC REST API settings are not configured properly in SAP Commerce Cloud.

You can add these settings using the Hybris Administration Console. Hover your mouse over the Platform tab, click Configuration, then update the CORS settings.

To configure CORS settings for OCC REST APIs, add the following to your SAP Commerce Cloud configuration:

corsfilter.ycommercewebservices.allowedOrigins=http://localhost:4200 https://localhost:4200
corsfilter.ycommercewebservices.allowedMethods=GET HEAD OPTIONS PATCH PUT POST DELETE
corsfilter.ycommercewebservices.allowedHeaders=origin content-type accept authorization cache-control if-none-match

Note: If you are using version 1.3 or newer of the Spartacus libraries, you must also add the CORS settings for anonymous consent, or disable the anonymous consent feature. Otherwise the Spartacus storefront will not display properly (for example, you might see a blank page when loading the Home page). Add the x-anonymous-consents custom header to corsfilter.ycommercewebservices.allowedHeaders, as follows:

corsfilter.ycommercewebservices.allowedHeaders=origin content-type accept authorization cache-control if-none-match x-anonymous-consents

For more information, see Anonymous Consent.

There are a number of other Spartacus features that also require additional CORS settings. For more information, see the following:

For more information about CORS, see ycommercewebservices Extension in the SAP Help Portal.

Alternate Method for Setting the SAP Commerce Cloud Admin Password

Instead of including the admin password in every install command as required for release 1905, you can create a configuration file that is used each time.

Create a file named custom.properties inside the installer/customconfig folder of your SAP Commerce Cloud folder.
Add the following line: initialpassword.admin=Y0urFav0r!tePassw0rd

Change Y0urFav0r!tePassw0rd to the password you’d like to use.
Save the file.

The next time you run the recipe install command, the settings inside custom.properties are used to build the local.properties file, and there’s no need to include -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd.

Supporting Regions in the Billing Address

A specific configuration can be entered if the payment provider requires the regions field as part of the billing address data.

Spartacus automatically picks up on the configuration and displays the regions field in the form.

If you do not have a custom.properties file, create a file named custom.properties inside the installer/customconfig folder of your SAP Commerce Cloud folder.
Add the following line to your custom.properties file:
```
 mockup.payment.label.billTo.region=billTo_state
```
Save the file.

The next time you run the recipe install command, the settings inside custom.properties are used to build the local.properties.

Note: If you wish this configuration to be present without reinstalling, you can add the property to your local.properties file.

Possible Issues

Failure at the Payment Step in Checkout

You may encounter the following error message:

POST http://localhost:4200/acceleratorservices/sop-mock/process 404 (Not Found)

This issue is caused by an incorrect configuration of the sop.post.url property.

Make sure this property is set to sop.post.url=https://localhost:9002/acceleratorservices/sop-mock/process.