Assisted Service Module

If Assisted Service Module is enabled on your SAP Commerce Cloud instance, you can configure the Alokai SAPCC integration to make use of it.

This feature is currently not available in the Unified Data Layer.

SAP pre-requisites

Extensions

Please ensure that your SAP instance has Assisted Service Module enabled - this entails enabling the correct extensions. Especially, make sure the assistedservicewebservices extension is enabled as our ASM API is based on it. The "CX" template from the SAP Commerce Cloud Sample Repository contains sample configuration that includes Assisted Service Module, among other things.

Additionally, you'll need a valid support agent employee account to use log in and use ASM features with. Otherwise, you'll be met with 403 Unauthorized errors when calling the methods.

Employees, customers

To make sure that your instance configuration and customer support agent employee account is valid, see if:

1. you have a customer list configured - you can find ImpEx scripts that create a sample list here
2. the customer support agent employee is a member of:
   1. customermanagergroup - to allow searching customers to emulate
   2. asagentgroup - for emulation and viewing customer lists. If this group doesn't exist for you, you can create it yourself with exactly asagentgroup as the name.
   3. A store group (e.g. nakanostoreemployees) - this allows for creating a customer list which will show customers assigned to the same location as the customer support agent employee. Assigning to physical stores is also described in the SAP documentation linked in point 1.

Feature flags

Some ASM features are disabled by default depending on your SAP Commerce Cloud version. If you need the features described below and your SAP CC version is lower than 2211.16, please make sure to explicitly enable their associated feature flags as described below. This can be done by adding a new key in the core-customize/manifest.json file's properties property in your SAP Cloud Portal configuration Git repository.

Please see:

• Enable returning more data in Customer 360 and customer lists
• Enable createCustomer and getPointOfServices endpoints that are disabled by default (assistedwebservices.api.restrictions.disabled)
• Feature Rollout Phases

// core-customize/manifest.json
 {
   ...,
   "properties": [
+    {
+      "key": "toggle.customer360.enabled",
+      "value": "true"
+    },
+    {
+      "key": "toggle.customerList.enabled",
+      "value": "true"
+    },
+    {
+      "key": "assistedservicewebservices.api.restrictions.disabled.endpoints",
+      "value": ""
+    },
     ...
   ],
    ...,
 }

Configuration

To configure middleware to work with ASM, provide the base URL of the assistedserviceswebservices extension in middleware.config.ts and configure the SDK to make use of it.

1. Add a new environment variable for holding the ASM URI in your .env file:

 ...
 SAPCC_API_URI=...
 # This is an example URI, replace it with the URI to your SAP CC's instance
+SAPCC_ASM_API_URI=https://api.abcdf-123replacewithyourenvironment-d1-public.model-t.cc.commerce.ondemand.com/assistedservicewebservices

2. Use the new environment variable in middleware.config.js:

import { MiddlewareConfig } from "@vsf-enterprise/sapcc-api";
import { Integration } from "@vue-storefront/middleware";

export function getSapccConfig() {
  const {
    SAPCC_OAUTH_URI,
    SAPCC_OAUTH_CLIENT_ID,
    SAPCC_OAUTH_CLIENT_SECRET,
    SAPCC_OAUTH_TOKEN_ENDPOINT,
    SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
    SAPCC_API_URI,
    NODE_ENV,
  } = process.env;

  if (!SAPCC_OAUTH_URI) throw new Error("Missing env var: SAPCC_OAUTH_URI");
  if (!SAPCC_OAUTH_CLIENT_ID) throw new Error("Missing env var: SAPCC_OAUTH_CLIENT_ID");
  if (!SAPCC_OAUTH_CLIENT_SECRET) throw new Error("Missing env var: SAPCC_OAUTH_CLIENT_SECRET");
  if (!SAPCC_OAUTH_TOKEN_ENDPOINT) throw new Error("Missing env var: SAPCC_OAUTH_TOKEN_ENDPOINT");
  if (!SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT) throw new Error("Missing env var: SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT");
  if (!SAPCC_API_URI) throw new Error("Missing env var: SAPCC_API_URI");

  return {
    location: "@vsf-enterprise/sapcc-api/server",
    configuration: {
      OAuth: {
        uri: SAPCC_OAUTH_URI,
        clientId: SAPCC_OAUTH_CLIENT_ID,
        clientSecret: SAPCC_OAUTH_CLIENT_SECRET,
        tokenEndpoint: SAPCC_OAUTH_TOKEN_ENDPOINT,
        tokenRevokeEndpoint: SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
        cookieOptions: {
          "vsf-sap-token": { secure: NODE_ENV !== "development" },
        },
      },
      api: {
        uri: SAPCC_API_URI,
+       asmUri: process.env.SAPCC_ASM_API_URI,
        baseSiteId: "apparel-uk",
        catalogId: "apparelProductCatalog",
        catalogVersion: "Online",
        defaultLanguage: "en",
        defaultCurrency: "USD",
      },
    },
  } satisfies Integration<MiddlewareConfig>;
}

4. Export the AsmEndpoints interface from the storefront-middleware/types.d.ts file. This interface contains the endpoints for the SAPCC integration that are going to be used in the SDK.

export { AsmEndpoints as SapccAsmEndpoints } from "@vsf-enterprise/sapcc-api";

3. Navigate to sdk.config.ts and add the new configuration to communicate with the ASM.

// ...
+ import { SapccAsmEndpoints } from 'storefront-middleware/types';

// ...

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
  commerce: buildModule(middlewareModule<SapccEndpoints>, {
    apiUrl: `${middlewareUrl}/sapcc`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
  // ...
+  asm: buildModule(middlewareModule<SapccAsmEndpoints>, {
+    apiUrl: `${middlewareUrl}/sapcc/asm,`,
+    defaultRequestConfig: {
+      headers: getRequestHeaders(),
+    },
+  })
  ...
}));

export type Sdk = ReturnType<typeof getSdk>;

Emulating a customer

In the context where we're not using ASM, the methods execute the action (e.g. create cart) for the account connected token that is passed in the vsf-sap-token cookie. In other words, the value current will be passed to the userId parameter of the SAP CC methods.

In the case of Assisted Service Module, the mechanism of action is different. The token of the Customer Support Agent employee has the permission to execute actions (e.g. create carts) not only in their own name (e.g. employee customer.support@nakano.com), but also in the name of regular customers. So the token of the Customer Support agent employee is sent with e.g. the request createCart, but the userId parameter of the SAP CC method is set to a customer's e-mail (e.g. akiro.nakamura@pronto-hw.com) instead of current. The end result is that the customer.support@nakano.com account has no cart, and the akiro.nakamura@pronto-hw.com account has a cart.

Emulating a customer in the SDK

SDK methods that support passing userId in SAP CC will also have an optional userId property, that allows running the method in the name of another customer.

await sdk.commerce.signUserIn({ username: 'customer.support@nakano.com', password: 'hunter2'});
await sdk.asm.getOrgUser({ userId: "e7bb713a-50d1-4e20-9347-e48e0ccdd001" }); // UUID of SAP customer's account, e.g. `akiro.nakamura@pronto-hw.com`

Please make sure to always pass the userId prop if the intention is to emulate a customer. If you forget to pass it, the method will be called in the name of the customer support agent employee.

await sdk.commerce.signUserIn({ username: 'customer.support@nakano.com', password: 'hunter2'});
await sdk.asm.getOrgUser(); // WRONG! Did you forget to pass `userId`?