Quick start

This guide is written for Alokai Enterprise Storefront Applications. If you are using a custom setup, please refer to the Custom Installation guide.

Prerequisites

SAP Commerce Cloud configured - before following this guide, make sure you have an already configured SAP Commerce Cloud project. It includes creating and configuring:
- at least one Website in WCMS > Websites tab,
- at least one Base Store connected to your Website in Base Commerce > Base Store tab,
- an OAuth Client in System > OAuth > OAuth Clients tab,
- a Catalog in the Catalog > Catalogs tab,
- a Catalog version in the Catalog > Catalog Versions tab.
Install Node.js version >= 16.0 and < 19.0.
Standard Alokai Enterprise Storefront installation - if you project does not use Storefront, see our Custom Installation guide.

Adding the integration

In this guide, we will explain how to add the SAPCC integration to your Storefront application.

Middleware

Install SAPCC integration, in the storefront-middleware application:

Install the SAP Commerce Cloud API Client. This package is used to create a connection with the SAP Commerce Cloud backend and build endpoints for the server middleware.

Middleware directory

If you don't have apps/storefront-middleware directory, you are likely using a custom setup. Please refer to the Custom Installation guide.

yarn

yarn add @vsf-enterprise/sapcc-api

In the apps/storefront-middleware/config directory, add a sapcc.config.ts file with the following content. The file contains the configuration for the SAPCC integration. You can find more information about the configuration properties in the MiddlewareConfig API Reference.

apps/storefront-middleware/config/sapcc.config.ts

/* eslint-disable complexity */
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,
        baseSiteId: "apparel-uk",
        catalogId: "apparelProductCatalog",
        catalogVersion: "Online",
        defaultLanguage: "en",
        defaultCurrency: "USD",
      },
    },
  } satisfies Integration<MiddlewareConfig>;
}

Now export the SAPCC integration config in the storefront-middleware/config/index.ts file. This allows you to use the SAPCC integration and other integrations you might add in your middleware config from a single file.

apps/storefront-middleware/config/index.ts

export * from "./sapcc.config";

Update apps/storefront-middleware/middleware.config.ts file. This file contains the configuration for the middleware. In this file, you will add the SAPCC integration config to the integrations config commerce section. You will also add the image transformation function to the Unified API extension config. This function is used to transform the image URLs in the SAPCC responses to the correct format.

apps/storefront-middleware/middleware.config.ts

import { getSapccConfig } from "./config";
...

//add SAPCC_MEDIA_HOST to env variables
const { ..., SAPCC_MEDIA_HOST } = process.env;
...
// add image transformation function to unified api extension config
const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
  // ...
  config: {
    transformImageUrl: (url) => {
      if (SAPCC_MEDIA_HOST) {
        return new URL(url, SAPCC_MEDIA_HOST).toString();
      }

      const [imagePathWithoutParams, searchParams = ""] = url.split("?");
      const segmentsParameter = imagePathWithoutParams.split("/").filter(Boolean);
      const sapContextSearchParameter = new URLSearchParams(searchParams).get("context");

      return `sap/${segmentsParameter}/context/${sapContextSearchParameter}`;
    },
    ...
  },
});

// add SAPCC integration config to integrations config commerce section
const config = {
  integrations: {
  //    ...,
      unified: {
      ...getSapccConfig(),
      extensions: (extensions: ApiClientExtension[]) => [...extensions, unifiedApiExtension],
    },
  },
};

Export the Endpoints, AuthEndpoints and AsmEndpoints interfaces 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.

apps/storefront-middleware/types.d.ts

export { 
  Endpoints as SapccEndpoints, 
  AuthEndpoints as SapccAuthEndpoints, 
  AsmEndpoints as SapccAsmEndpoints 
} from "@vsf-enterprise/sapcc-api";

Configure environment variables in your .env file.

server/.env

SAPCC_API_URI=<base_url>/occ/v2
SAPCC_OAUTH_URI=
SAPCC_OAUTH_CLIENT_ID=
SAPCC_OAUTH_CLIENT_SECRET=
SAPCC_OAUTH_TOKEN_ENDPOINT=
SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT=

Environment variables:

In the portal, your API url can be found in Deployment > Environments > select your environment view. In the Public Endpoints table, find the row named "API" and copy its URL, and add /occ/v2 at the end. It looks like: https://api.c1jvi8hu9a-vsfspzooa1-d1-public.model-t.cc.commerce.ondemand.com/occ/v2
For infomation about SAPCC_OAUTH vars see the MiddlewareOAuthConfig API Reference

SDK

As you are using a Alokai Enterprise Storefront Application, the commerce integration is already configured in your frontend application for you. No changes are required in your frontend application. Following are some example configuations on how to use the SDK in your application.

SDK Config example

storefront-unified-nextjs/sdk/sdk.config.ts

import { CreateSdkOptions, createSdk } from '@vue-storefront/next';
import { UnifiedEndpoints, SapccEndpoints, SapccAuthEndpoints, SapccAsmEndpoints } from 'storefront-middleware/types';

if (!process.env.NEXT_PUBLIC_API_BASE_URL) {
  throw new Error('NEXT_PUBLIC_API_BASE_URL is required to run the app');
}

const options: CreateSdkOptions = {
  middleware: {
    apiUrl: process.env.NEXT_PUBLIC_API_BASE_URL,
  },
  multistore: {
    enabled: process.env.NEXT_PUBLIC_MULTISTORE_ENABLED === 'true',
  },
};

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

export type Sdk = ReturnType<typeof getSdk>;

Usage

Here's an example of how you can use the SAP Commerce Cloud SDK module in your application:

Pages Router

import { getSdk } from "../sdk.config";

export function getServersideProps() {
  const sdk = getSdk();
  const { products } = await sdk.unified.searchProducts();

  return {
    props: {
      products,
    },
  };
}

That's it! You can now use SAPCC in your Next.js app ✨

OpenAPI SDK

Need more types? Extending the SAP Commerce Cloud integration? You might need the @vsf-enterprise/sap-commerce-webservices-sdk package, which includes the definitions of the types of SAP Commerce Webservices.