Installing SAP Commerce Cloud for use with TUA Spartacus 2.x

Note: Spartacus 4.x is no longer maintained. Please upgrade to the latest version.

Note: Spartacus 4.x was tested with SAP Commerce Cloud versions 1905 to 2205. Spartacus 4.x has not been verified to work with (and is not guaranteed to work with) SAP Commerce Cloud 2211 or later releases.

The following instructions describe how to install and configure SAP Commerce Cloud (release 2005) with Telco & Utilities Accelerator (supports both release 2007 and release 2011, latest patch) for use with a TUA Spartacus storefront. In these instructions, SAP Commerce and Telco & Utilities Accelerator are installed on your local computer, so localhost is used in the browser URLs.

The installation procedure includes steps for creating and using a b2c_telco_spa recipe that makes use of the TUA Spartacus Sample Data (b2ctelcospastore), but you can use your own sample data or recipe as long as it includes the cmsocc, commercewebservices, acceleratorocc extensions and TUA module.

Note: If you are trying out TUA Spartacus for the first time and intend to use the default sample data, you must use the TUA Spartacus Sample Data store extension (should be part of your list of extensions). The TUA Spartacus Sample Data is a set of data (product offerings and content) for the telco industry.

However, installing the TUA Spartacus Sample Data is not required in all cases. The TUA 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, TUA 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 TmaB2cStorefrontModule. It is important to understand that this specific configuration is tightly coupled to the TUA 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 TmaB2cStorefrontModule, but instead, use the StorefrontModule that does not provide any layout configuration. The StorefrontModule is not dependent on the TUA Spartacus sample data, and is most likely a good starting point for your custom project.

To install and configure SAP Commerce Cloud for use with TUA Spartacus, you must complete the following procedures:

Setting Up SAP Commerce Cloud with TUA using the TUA Spartacus Sample Data Store Extension
Configuring OCC credentials
Updating System and User Credentials
Configuring CORS

Table of Contents

Setting Up SAP Commerce Cloud with TUA using the TUA Spartacus Sample Data Store Extension
Configuring OCC Credentials
Updating System and User Credentials
Configuring CORS
Alternate Method for Setting the SAP Commerce Admin Password
Supporting Regions in the Billing Address
Possible Issues
- Failure at the Payment Step in Checkout

Setting Up SAP Commerce Cloud with TUA using the TUA Spartacus Sample Data Store Extension

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

Unzip the SAP Commerce and Telco & Utilities Accelerator zip archives.

Note: Use the latest patches for SAP Commerce Cloud version 2005 and Telco & Utilities Accelerator version 2007 or Telco & Utilities Accelerator version 2011.
Download the TUA Spartacus Sample Data Store Extension.

The TUA Spartacus Sample Data is provided in the following zip files:
- For TUA 2007:
  - b2ctelcospastore_2007.zip.
  - utilitiesspastore_2007.zip.
- For TUA 2011:
  - b2ctelcospastore_2011.zip.
  - utilitiesspastore_2011.zip.
Unzip the sample data for 2007 or 2011 depending on the TUA backend version you want to use.

Note: You can either use both the store extensions, or only one of them, depending on your needs (specific to Telco or to Utilities).
- Sample data for Telco is stored in the following archive files:
  - b2ctelcospastore_2007.zip.
  - b2ctelcospastore_2011.zip.
- Sample data for Utilities is stored in the following archive files:
  - utilitiesspastore_2007.zip.
  - utilitiesspastore_2011.zip.
Move:
- the b2ctelcospastore folder from extracted b2ctelcospastore_2007 folder or b2ctelcospastore_2011 folder to <sap-commerce-folder>/hybris/bin/modules/b2c-telco-accelerator.
- the utilitiesspastore folder from extracted utilitiesspastore_2007 or utilitiesspastore_2011 folder to <sap-commerce-folder>/hybris/bin/modules/b2c-telco-accelerator.
Note: The b2ctelcospastore folder can be stored anywhere in the modules folder. The b2c-telco-accelerator folder is chosen as it contains other TUA sample data.
Unzip TUA cms extension for utilities:
- If you want to use utilities sample data then also unzip the b2ctelcocms.zip.
- Move the b2ctelcocms folder in the same location with utilitiesspastore folder.
In the sap-commerce-folder>/installer/recipes folder, create a copy of the b2c_telco folder.
Rename the copy of the b2c_telco folder to b2c_telco_spa.

In b2c_telco_spa, the build.gradle file should have the following content:

If you want to use the two sample data extensions, for Telco and Utilities, the build.gradle file must have the following structure:

 apply plugin: 'installer-platform-plugin'
 apply plugin: 'installer-addon2-plugin'

 def pl = platform {
 localProperties {
     property 'kernel.events.cluster.jgroups.channel', 'disable'
     property 'datahub.publication.saveImpex', ''
     property 'commerceservices.default.desktop.ui.experience', 'responsive'
     property 'kernel.autoInitMode', 'update'
     property 'installed.tenants', 'junit'
 }
 afterSetup {
     ensureAdminPasswordSet()
 }

 extensions {
     extName 'acceleratorcms'
     extName 'adaptivesearchbackoffice'
     extName 'adaptivesearchsolr'
     extName 'addonsupport'
     extName 'b2ctelcobackoffice'
     extName 'b2ctelcofulfillmentprocess'
     extName 'b2ctelcospastore'
     extName 'utilitiesspastore'
     extName 'b2ctelcocms'
     extName 'b2ctelcotmfwebservices'
     extName 'b2ctelcowebservices'

     extName 'b2ctelcocommercewebservicescommons'
     extName 'b2ctelcoocc'
     extName 'commerceservicesbackoffice'
     extName 'solrfacetsearchbackoffice'
     extName 'solrserver'
     extName 'subscriptionbackoffice'
     extName 'yacceleratorcore'
     extName 'commercewebservices'

     extName 'cmsbackoffice'
     extName 'cmswebservices'
     extName 'previewwebservices'
     extName 'smarteditwebservices'
     extName 'cmssmarteditwebservices'
     extName 'permissionswebservices'
     extName 'cmssmartedit'
     extName 'cmsocc'
     extName 'acceleratorocc'
     extName 'customersupportbackoffice'

     extName 'personalizationwebservices'
     extName 'previewpersonalizationweb'
     extName 'personalizationcmsweb'
     extName 'personalizationsmartedit'
     extName 'personalizationservicesbackoffice'
     extName 'personalizationcmsbackoffice'
     extName 'personalizationservices'
     extName 'personalizationfacades'

     extName 'acceleratorservices'
     extName 'assistedservicefacades'

     extName 'rulebuilderbackoffice'
     extName 'couponbackoffice'
     extName 'droolsruleengineservices'
     extName 'couponfacades'
     extName 'couponservices'
 }
 }

 task setup () {
 doLast {

     pl.setup()

     copy {
     from "${installerHome}/recipes/b2c_telco_spa/logback.xml"
     into "${suiteHome}/hybris/bin/platform/tomcat/lib"
     }
     copy {
     from "${installerHome}/recipes/b2c_telco_spa/sbg_properties"
     into "${suiteHome}/hybris/bin/platform/tomcat/lib"
     exclude "**/*.txt"
     }
 }
 }

 task buildSystem(dependsOn: setup) {
 doLast {
     pl.build()
 }
 }

 task initialize (dependsOn: buildSystem) {
 doLast {
     pl.initialize()
 }
 }

 task start () {
 doLast {
     pl.start()
 }
 }

 task startInBackground () {
 doLast {
     pl.startInBackground()
 }
 }

 task stopInBackground {
 doLast {
     pl.stopInBackground()
 }
 }

If you want to use only Telco sample data then remove the following lines from the build.gradle file:

 extName 'utilitiesspastore'
 extName 'b2ctelcocms'

Open a terminal or command prompt window inside the sap-commerce-folder>/installer folder.
Set up the recipe using the following commands:

For Windows:
```
 install.bat -r b2c_telco_spa -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd
```
For Unix:
```
 ./install.sh -r b2c_telco_spa -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd
```
Note: Starting with release 2005, SAP Cloud releases do not ship with a default admin password. You must specify a password when running the preceding recipe commands, or you can specify a password in the custom.properties file that is stored in sap-commerce-folder>\installer\customconfig. See the following Alternate Method for Setting the SAP Commerce Admin Password procedure for information on setting a password in the custom.properties file.
Initialize the system using the following command. From the sap-commerce-folder>/installer folder run the following commands:

For Windows:
```
install.bat -r b2c_telco_spa -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd initialize
```
For Unix:
```
./install.sh -r b2c_telco_spa -A local_property:initialpassword.admin=Y0urFav0r!tePassw0rd initialize
```
Initialization of the b2c_telco_spa recipe can take about 20 minutes. Sample data for this recipe includes telco-specific data and content.
Start SAP Commerce Cloud with the following command. From the sap-commerce-folder>/installer folder, run the following commands

For Windows:
```
install.bat -r b2c_telco_spa start
```
For Unix:
```
./install.sh -r b2c_telco_spa start
```
Verify that the system is working.
- Access Admin Console: https://localhost:9002
- Access Backoffice: https://localhost:9002/backoffice
Note: When setting up your Spartacus storefront, set the base site in app.module.ts to telcospa and/or utilitiesspa depending on which sample data you want to use. Following are the samples:

Telco:
```
 context: {
 baseSite: ['telcospa']
 },
```
Utilities:
```
 context: {
 baseSite: ['utilitiesspa']
 },
```
Both:
```
 context: {
 baseSite: ['telcospa', ‘utilitiesspa’]
 },
```

Configuring OCC Credentials

By default, SAP 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 telcospa base store: https://localhost:9002/occ/v2/telcospa/basestores/telcospa
Display information about the utilitiesspa base store: https://localhost:9002/rest/v2/utilitiesspa/basestores/utilitiesspa

To register users and check out, SAP Commerce Cloud must be configured with a client ID and password. When required, your TUA Spartacus storefront sends this client ID and password when communicating with the backend. 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 TUA 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 backend. 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 TUA 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 TUA Spartacus Storefront from Libraries for more information.

Updating System and User Credentials

Note: Updating system and user credentials (2005 only) is optional.

If you are using SAP Commerce Cloud 2005, you may need to enable users and passwords for certain functionality to work. For more information, see Setting Passwords for Default Users.

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. Building the TUA 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 TUA 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 (local.properties file of your config folder):

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 x-anonymous-consents

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

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

Note: The x-anonymous-consents custom header is included in the above example, but it can be removed if you plan to disable the anonymous consent feature. However, do not remove this header if you do not plan to disable the anonymous consent feature. For more information, see Anonymous Consent.

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

Alternate Method for Setting the SAP Commerce Admin Password

Instead of including the admin password in every install command as required for release 2005, 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 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.

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

Note: Please make sure that you have the website properties properly set for your telcospa base site to point to your environment. For your localhost environment, they should have the following values:

website.telcospa.http=http://localhost:9001
website.telcospa.https= https://localhost:9002
website.utilitiesspa.http=http://localhost:9001
website.utilitiesspa.https=https://localhost:9002