Installing SAP Commerce for use with TUA Spartacus 1.3

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

The following instructions describe how to install and configure SAP Commerce (release 1905) with Telco & Utilities Accelerator (release 2003, 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 cmsoccaddon, ycommercewebservices, acceleratorwebservicesaddon 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 for use with TUA Spartacus, you must complete the following procedures:

Setting up SAP Commerce with Telco & Utilities Accelerator
Configuring OCC credentials
Configuring CORS

Setting Up SAP Commerce with Telco & Utilities Accelerator

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 lastest patches for SAP Commerce version 1905 and Telco & Utilities Accelerator version 2003.
Download the TUA Spartacus Sample Data Store Extension.

The TUA Spartacus Sample Data Store Extension is the extension provided in the following zip file: b2ctelcospastore.zip.
Unzip the sample data.

Note: You can use both the store extensions, or only one of them, depending on your needs (specific to Telco or Utilities).
- The sample data for Telco is stored in the b2ctelcospastore.zip archive.
- The sample data for Utilities is stored in the utilitiesspastore.zip archive.
Move the b2ctelcospastore folder and utilitiesspastore folder to sap-commerce-folder>/hybris/bin/modules/b2c-telco-accelerator.

The b2ctelcospastore and utilitiesspastore folders can be stored anywhere in the modules folder. The b2c-telco-accelerator folder is chosen as it contains other TUA sample data.
Unzip the cms addon for Utilities:
- If you want to use utilities sample data, unzip the b2ctelcocmsaddon.zip.
- Move the b2ctelcocmsaddon folder in the same location with the utilitiesspastore folder.
In the sap-commerce-folder>/installer/recipes folder, duplicate 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:

Note: If you want to use both sample data extensions for Telco and Utilities, the build.gradle file should 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, api, foo'

   }
   afterSetup {
      ensureAdminPasswordSet()
   }   
      
      extensions {
         extName 'acceleratorcms'
         extName 'adaptivesearchbackoffice'
                  extName 'adaptivesearchsolr'
         extName 'addonsupport'
         extName 'b2ctelcobackoffice'
         extName 'b2ctelcofulfillmentprocess'
         extName 'b2ctelcospastore'
         extName 'utilitiesspastore'
         extName 'b2ctelcocmsaddon'

         extName 'b2ctelcoaddon'
         extName 'b2ctelcotmfwebservices'
         extName 'b2ctelcowebservices'
         
         extName 'b2ctelcooccaddon'
         extName 'commerceservicesbackoffice'
         extName 'solrfacetsearchbackoffice'
         extName 'solrserver'
         extName 'subscriptionbackoffice'
         extName 'yacceleratorstorefront'
         extName 'yacceleratorcore'
         extName 'ycommercewebservices'
                  extName 'pcmbackofficesamplesaddon'

         extName 'cmsbackoffice'
         extName 'cmswebservices'
         extName 'previewwebservices'
         extName 'smarteditwebservices'
         extName 'cmssmarteditwebservices'
         extName 'permissionswebservices'
         extName 'smarteditaddon'
         extName 'cmssmartedit'
         extName 'cmsoccaddon'
         extName 'customerticketingaddon'
         extName 'customersupportbackoffice'
            
         extName 'personalizationwebservices'
         extName 'previewpersonalizationweb'
         extName 'personalizationcmsweb'
         extName 'personalizationsmartedit'
         extName 'personalizationservicesbackoffice'
         extName 'personalizationcmsbackoffice'
         extName 'personalizationservices'
         extName 'personalizationfacades'
            
         extName 'acceleratorservices'
         extName 'assistedservicefacades'
         extName 'assistedservicestorefront'
         extName 'assistedservicecustomerinterestsaddon'

         extName 'rulebuilderbackoffice'
         extName 'couponbackoffice'
         extName 'droolsruleengineservices'
         extName 'couponfacades'
         extName 'couponservices' 
         extName 'promotionenginesamplesaddon'
         extName 'acceleratorwebservicesaddon'

   }
addons {
      forStoreFronts('yacceleratorstorefront') { 
         names('b2ctelcoaddon', 'smarteditaddon', 'customerticketingaddon', 'assistedservicestorefront', 'assistedservicecustomerinterestsaddon', 'pcmbackofficesamplesaddon', 'promotionenginesamplesaddon')
         template 'yacceleratorstorefront'
      }

      forStoreFronts('ycommercewebservices') {
         names('b2ctelcooccaddon','cmsoccaddon','acceleratorwebservicesaddon',b2ctelcocmsaddon')
         template 'ycommercewebservices'
            
      }
         
   }
}

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

Notes:

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

extName 'utilitiesspastore'
extName 'b2ctelcocmsaddon'

Additionally, ensure that you also remove the b2ctelcocmsaddon from the build.gradle file:

names('b2ctelcooccaddon','cmsoccaddon','acceleratorwebservicesaddon','b2ctelcocmsaddon')

If you want to use only Utilities sample data, then remove the following line from the build.gradle file:

extName 'telcospastore'

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 1905, SAP Commerce 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 the custom.properties file that is stored in sap-commerce-folder>\installer\customconfig. For information about setting a password in the custom.properties file, see Alternate Method for Setting the SAP Commerce Admin Password procedure.
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 with 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 start

For Unix:

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

Verify that the system is working.
- To access the Admin Console, use: https://localhost:9002
- To access the Backoffice, use: https://localhost:9002/backoffice
Note: When setting up your TUA Spartacus storefront, set the base site in app.module.ts to telcospa and/or utilitiesspa (depending on the sample data that you chose to use). The following is an example:

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

Configuring OCC Credentials

By default, SAP Commerce 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/rest/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 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.

To configure SAP Commerce to accept OCC REST API calls, follow the steps:

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 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 can 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 at the 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 to accept OCC REST API calls, you can set up and start your storefront. See Building the TUA Spartacus Storefront Using 1.3 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.

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 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 ycommercewebservices 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 1905, you can create a configuration file to use 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 want 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 is 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 custom.properties file 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.

Tip: If you want to use this configuration 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 due to an incorrect configuration of the sop.post.url property.

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

Note: Ensure that you have the website properties properly set for your telcospa base site and/or the utilitiesspa base site(s) 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