Assisted Service Module

ASM in composable storefront requires the following SAP Commerce Cloud extensions:

• assistedservicewebservices extension

To enable ASM in composable storefront, you need to grant CMS permissions and configure CORS settings specific to ASM.

The asagentgroup user group needs specific rights to read CMS data from OCC.

If you start from scratch and initialize your SAP Commerce Cloud system with version 1905.5 or newer, the asagentgroup gets the required permissions to use CMS data through composable storefront and OCC. There is no further action to take.

However, if you upgrade SAP Commerce Cloud from a version that is older than 1905.5, you need to grant the asagentgroup permissions by importing the following ImpEx data through the ImpEx console:

# Access rights for asagentgroup
# - These are needed for rendering (cmsoccaddon).

$START_USERRIGHTS;;;;;;;;;
Type;UID;MemberOfGroups;Password;Target;read;change;create;remove;change_perm
UserGroup;asagentgroup;;;;;;;;

# general
;;;;Item;+;;;;;
;;;;Type;+;;;;;

# access rights for Products, Store, Site and Catalogs
;;;;Product;+;;;;;
;;;;Category;+;;;;;
;;;;VariantType;+;;;;;
;;;;BaseSite;+;;;;;
;;;;BaseStore;+;;;;;
;;;;Catalog;+;;;;;
;;;;CatalogVersion;+;;;;;
;;;;ContentCatalog;+;;;;;
;;;;MediaContainer;+;-;-;-;-;
;;;;MediaContext;+;-;-;-;-;
;;;;MediaFormat;+;-;-;-;-;
;;;;MediaFormatMapping;+;-;-;-;-;

# cms2 items
;;;;CMSItem;+;-;-;-;-;

$END_USERRIGHTS;;;;;

The assistedservicewebservices extension requires CORS configuration. The CORS configurations for assistedservicewebservices have default values that are specified in the project.properties file of the assistedservicewebservices. The default values are the following:

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

The various CORS configurations for ASM that are required by the back end can be installed in the following ways:

• using configuration properties to install them during a deployment

• using the SAP Commerce Cloud manifest file to install them during a deployment

• using an ImpEx script to install them at runtime

• using Backoffice to configure them manually at runtime

The following sections describe how to update the CORS configurations for ASM through the local.properties file, the SAP SAP Commerce Cloud manifest file, and through ImpEx.

corsfilter.assistedservicewebservices.allowedOriginPatterns=*
corsfilter.assistedservicewebservices.allowedMethods=GET HEAD OPTIONS PATCH PUT POST DELETE
corsfilter.assistedservicewebservices.allowedHeaders=origin content-type accept authorization cache-control if-none-match x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time
corsfilter.assistedservicewebservices.exposedHeaders=x-anonymous-consents occ-personalization-id occ-personalization-time
corsfilter.assistedservicewebservices.allowCredentials=true

{
	"key": "corsfilter.assistedservicewebservices.allowedOriginPatterns",
	"value": "*"
},
{
	"key": "corsfilter.assistedservicewebservices.allowedMethods",
	"value": "GET HEAD OPTIONS PATCH PUT POST DELETE"
},
{
	"key": "corsfilter.assistedservicewebservices.allowedHeaders",
	"value": "origin content-type accept authorization cache-control if-none-match x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time"
},
{
	"key": "corsfilter.assistedservicewebservices.exposedHeaders",
	"value": "x-anonymous-consents occ-personalization-id occ-personalization-time"
}
{
	"key": "corsfilter.assistedservicewebservices.allowCredentials",
	"value": "true"
}

INSERT_UPDATE CorsConfigurationProperty;key[unique=true];value;context[default=assistedservicewebservices,unique=true]
;allowedOriginPatterns;*
;allowedMethods;GET HEAD OPTIONS PATCH PUT POST DELETE
;allowedHeaders;origin content-type accept authorization cache-control if-none-match x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time
;allowCredentials;true
;exposedHeaders;x-anonymous-consents occ-personalization-id occ-personalization-time

CORS configurations are customized by overriding the default configuration through your local.properties file.

Since configurations are overridden in local.properties, if you want to add a configuration element without losing the default values, you need to add all of the default elements in addition to any new elements. For example, to add my-new-header to the allowedHeaders list, you need to provide all of the default headers as well as any custom headers in the allowedHeaders list.

The following is an example that adds my-new-header to the default allowedHeaders list in the local.properties file:

corsfilter.assistedservicewebservices.allowedHeaders=origin content-type accept authorization my-new-header.

To customize allowedMethods or allowedHeaders, you should include to the default values along with your custom values.

To customize the allowedOrigins property of assistedservicewebservices, you need to override (that is, replace) the default value in your local.properties file with a host name that is relevant to your environment. The following is an example:

corsfilter.assistedservicewebservices.allowedOrigins=https://my-new-host:4200

For development purposes only, you can use allowedOriginPatterns and set the value to a wildcard (*), as shown in the following example:

corsfilter.assistedservicewebservices.allowedOriginPatterns=*

To enable customer emulation, you must add the sap-commerce-cloud-user-id header to the corsfilter.commercewebservices.allowedHeaders list. As described in previous sections, you can update the configuration in the local.properties file, in the SAP Commerce Cloud manifest file, or through ImpEx. The following is an example of the updated corsfilter.commercewebservices.allowedHeaders list in the local.properties file:

corsfilter.commercewebservices.allowedHeaders=origin content-type accept authorization cache-control if-none-match x-anonymous-consents x-profile-tag-debug x-consent-reference occ-personalization-id occ-personalization-time sap-commerce-cloud-user-id

Additionally, in an AsmConfig provider, add a userIdHttpHeader.enable key with the value set to true. The following is an example:

provideConfig(<AsmConfig>{
  asm: {
    userIdHttpHeader: {
      enable: true,
    },
  },
}),

Now when requests are sent, the sap-commerce-cloud-user-id header has its value set to the emulated user's ID. This prevents ambiguity errors when making requests to OCC.

To write ASM-compatible code, you need to use the takeUserId() function from the UserIdService to determine the userId that is used in OCC calls. This is typically done in a service that dispatches an action that contains the userId in the payload.

Prior to official ASM support in composable storefront, in requests sent on behalf of an authenticated user, the OCC userId was the special "current" OCC user, which was represented by the OCC_USER_ID_CURRENT constant. This can be seen in the following example:

/**
 * Retrieves user's addresses
 */
loadAddresses(): void {
  this.store.dispatch(new UserActions.LoadUserAddresses(OCC_USER_ID_CURRENT));
}

With official ASM support in composable storefront, the correct way to determine the OCC userId is to call UserIdService.takeUserId(). Using the previous example as the starting point, composable storefront now determines the OCC userId as follows:

/**
 * Retrieves user's addresses
 */
loadAddresses(): void {
  this.userIdService.takeUserId().subscribe((userId) => {
    this.store.dispatch(new UserActions.LoadUserAddresses(userId));
  });
}

To support ASM in composable storefront, and potentially other features in the future, the facade services cannot simply use the "current" special userId when calling various actions. There needs to be some logic that is applied to determine the correct OCC userId to pass down to actions that trigger back end calls. As a result, the logic to determine the correct OCC userId is centralized in the takeUserId() function of the UserIdService.

When a customer support agent signs in, a Session Timeout timer appears in the ASM UI. The default value is 600 seconds (10 minutes), but you can change the session timeout duration.

The following is an example:

provideConfig({
  asm: {
    agentSessionTimer: {
      startingDelayInSeconds: 720,
    },
  },
});

In this example, the duration of the session timer has been set to 720 seconds (12 minutes).

The number of results in the ASM customer search can be customized.

The following is an example:

provideConfig({
  asm: {
    customerSearch: {
      maxResults: 20,
    },
  },
});

You can customize the columns of the customer list to display the customer information of your choosing.

The customer list is an extensible list that allows customer support agents to display a list of customers that are assigned to them. You can configure the columns of the customer list depending on the type of information you want to display in the list.

The following is an example:

    customerList: {
      pageSize: 5,
      showAvatar: true,
      columns: [
        {
          headerLocalizationKey: 'asm.customerList.tableHeader.customer',
          renderer: (customer) => {
            return customer.name ?? '';
          },
          actionType: CustomerListColumnActionType.START_SESSION,
        },
        {
          headerLocalizationKey: 'asm.customerList.tableHeader.email',
          renderer: (customer) => {
            return customer.uid ?? '';
          },
        },
        {
          headerLocalizationKey: 'asm.customerList.tableHeader.phone',
          renderer: (customer) => {
            return customer?.defaultAddress?.phone ?? '';
          },
        },
        {
          headerLocalizationKey: 'asm.customerList.tableHeader.order',
          icon: {
            symbol: ICON_TYPE.ORDER,
            captionLocalizationKey: 'asm.customerList.tableHeader.order',
          },
          actionType: CustomerListColumnActionType.ORDER_HISTORY,
        },

In this example, the columns displayed in the customer list are Customer, Email, Phone, and Order. Selecting the value in the Customer column opens a new session on the storefront with ASM mode enabled and the customer and cart ID pre-filled. Selecting the value in the Order column navigates to the customer's order history.

To invoke the ASM UI in the composable storefront, add the ?asm=true suffix to the URL.

For example, with the electronics sample store, you can invoke the ASM UI on the home page with the following URL:

https://{hostname}/electronics-spa/en/USD/?asm=true

No special extensibility is available for this feature.

ASM customer emulation does not work with CMS content rules and restrictions in composable storefront.

If there are content rules or restrictions that are normally applied based on a customer’s ID, or the customer’s group ID, these rules and restrictions are not applied during an ASM customer emulation. The CMS endpoints instead provide content based on what the customer support agent is permitted to see.

To display CMS content, composable storefront relies on the CMS endpoints from OCC. When requests are sent, the CMS endpoints do not accept a userId parameter that could define the emulated user (that is, the customer). The CMS endpoints only recognize the authenticated user as the sender of requests, and in ASM customer emulation sessions, the authenticated user is the customer support agent.

The following OCC CMS endpoints work only for the authenticated user:

• /{baseSiteId}/cms/components

• /{baseSiteId}/cms/components/{componentId}

• /{baseSiteId}/cms/pages

• /{baseSiteId}/cms/pages/{pageId}

• /{baseSiteId}/cms/sitepages

OCC CMS endpoints do not accept a userId parameter, so it is not possible for an emulated customer to trigger CMS rules and restrictions during an ASM emulation session.