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.
- at least one Website in
- Install Node.js version >= 16.0 and < 19.0.
- Standard Alokai Enterprise
Storefront
installation - if you project does not useStorefront
, 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 add @vsf-enterprise/sapcc-api
- In the
apps/storefront-middleware/config
directory, add asapcc.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.
/* 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.
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.
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
andAsmEndpoints
interfaces from thestorefront-middleware/types.d.ts
file. This interface contains the endpoints for the SAPCC integration that are going to be used in the SDK.
export {
Endpoints as SapccEndpoints,
AuthEndpoints as SapccAuthEndpoints,
AsmEndpoints as SapccAsmEndpoints
} from "@vsf-enterprise/sapcc-api";
- Configure environment variables in your
.env
file.
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
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:
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.