Sitecore OrderCloud integration for Uniform Mesh

Sitecore OrderCloud is a headless commerce platform for B2B, B2C, and B2X.

This integration allows business users to build personalized landing pages and storefronts by repurposing product content from your OrderCloud marketplace. It also enables developers to use their preferred front-end tools to build these applications.

This section covers how to configure and use this integration.

Get OrderCloud settings

In order to configure a connection to OrderCloud, you need to retrieve several values that will enable Uniform to use the OrderCloud API:

• Marketplace identifier
• Client ID
• Client secret

This step guides you through the process of retrieving these values.

Get marketplace identifier

1. Log into the OrderCloud portal.

2. Navigate to the API Console.

3. Connect to your marketplace.

   About this step

   Note whether Sandbox is displayed next to the marketplace name. You will need this when you configure the integration in Uniform.

4. Under the marketplace name, click Expand

   About this step

   Note the marketplace identifier value. You will need this when you configure the integration in Uniform.

Create admin user

1. In the left menu click Admin Users

2. Click the hamburger button to see a list of operations.

3. Click POST Create a new admin user.

4. Enter the required fields.

   About this step

   Make sure you mark the user active.

5. Click Send

Create security profile

1. In the left menu click Security Profiles

2. Click the lightning bolt button to disable the Enhanced UI view.

3. Click the hamburger button to see a list of operations.

4. Click POST Create a new security profile.

5. Enter the following values:

   • ID: full-access-uniform
   • Name: Full Access Uniform
   • Roles: FullAccess

6. Click Send

7. Click the hamburger button.

8. Click POST Create or update a security profile assignment.

9. Enter the following values:

   • Security Profile ID: full-access-uniform
   • User ID: uniform

10. Click Send

Create API client

1. In the left menu click API Clients

2. Click Create New API Client

3. Enter the following values:

   • Application Name: Uniform
   • Enabled?: yes
   • Allow All Sellers: yes

4. Click Generate Random Client Secret

   About this step

   Note the value that is generated. You will need this when you configure the integration in Uniform.

5. Click Create New API Client

6. Click the new API client to return to its settings.

7. Find the field Client ID.

   About this step

   Note the value. You will need this when you configure the integration in Uniform.

8. For the field Default Context User, click the user uniform

9. Click Save Changes

Configure integration

This section describes how to add the OrderCloud integration to your Uniform project.

1. Log into Uniform.

2. Navigate to Settings > Integrations.

3. Add the integration for Sitecore OrderCloud.

4. Enter the required fields:

   Field	Description
   Client ID	The client ID from the OrderCloud API client.
   Client secret	The client secret from the OrderCloud API client.
   Sandbox environment	The your marketplace is running in the sandbox environment, tick this box. This changes the base URL for API requests to OrderCloud.
   Base URL	This setting allows you to override the base URL for API calls to OrderCloud. This is an optional field.

5. Click Test to confirm the values can be used to connect to OrderCloud.

6. Click Save.

Add parameter to Canvas component

This integration adds custom parameter types for Canvas components. The following parameter types are available:

OrderCloud Product Query

This parameter type is used in cases where the user doesn't want to explicitly select products for a parameter. Instead, the user specify search criteria that is used to determine the products to display. The actual products are determined at build-time.

The following properties are available:

Property	Description
Product Category	The product search is limited to the selected content type.
Keyword	The product search is limited to products with the specified text in the product name.
Count	The maximum number of products to retrieve.
Sort	The product property by which the products are sorted.
Sort Order	The order that the products are sorted.

OrderCloud Product Search

This parameter type is used when the user wants to explicitly select the products for a parameter. In cases where the product catalog has a large number of products, the user can filter the product list by category and/or product name.

Wire up your Next.js app

tip

Before wiring up your app, please make sure to get familiar with the concept of Data Enhancers. This chapter will walk you through the process of adding Order Cloud specific enhancers to your web application.

Pre-requisites

Make sure you already have a web application wired up to Canvas with Uniform API key and Project Id in the env vars.

If you don't have the Canvas enabled app up and running yet, please go through one this tutorials:

• Next.js
• Nuxt.js

Adding Order Cloud enhancers to a Next.js app

info

This tutorial will use a Next.js application as an example, but the same concepts apply to any other JavaScript framework.

1. Install our Data Enhancer for Order Cloud with this command:

   npm install@uniformdev/canvas-ordercloud

2. Add the following Order Cloud specific environment variables to your web app's .env file:

     ORDER_CLOUD_BASE_API_URL=<ORDER_CLOUD_BASE_API_URL>
     ORDER_CLOUD_CLIENT_ID=<ORDER_CLOUD_CLIENT_ID>
     ORDER_CLOUD_CLIENT_SECRET=<ORDER_CLOUD_CLIENT_SECRET>

3. Find the location where you retrieve your page content. In a Next.js app, this is typically a page file under /pages (index.tsx, [slug].tsx, etc.)

4. Find the location of the getStaticProps or getServerSideProps function (depending on what you use).

5. Add the following lines of code after the code that retrieves the raw composition from Canvas APIs:

   • A: import ehnancer for Order Cloud
   • B: run the enhance function, with will return post-enhanced composition
   • C: register enhancer for Order Cloud
   • D: return the post-enhanced composition as a page prop

/pages/[slug].js

// A. import ehnancer for Order Cloud
import { ordercloudEnhancer, ORDERCLOUD_PARAMETER_TYPES } from '@uniformdev/canvas-ordercloud';

export async function getStaticProps(context: GetStaticPropsContext) {
  // retrieving the raw composition content form Uniform Canvas API, before enhancing
  const compositionId = context?.params?.compositionId ?? '';
  const compositionString = Array.isArray(compositionId) ? compositionId.join('/') : compositionId;
  const { composition } = await canvasClient.getCompositionById({ compositionId: compositionString });

  // B: run the enhance function, with will return post-enhanced composition
  await enhance({
    composition,
    // C: register enhancer for Order Cloud:
    enhancers: new EnhancerBuilder().parameterType(ORDERCLOUD_PARAMETER_TYPES, ordercloudEnhancer()),
    context,
  });

  // D: return the post-enhanced composition as a page prop
  return {
    props: {
      composition,
    },
  };
}

Please note that your way of reading the environment variables may be different.

success

Congratulations! You successfully added Order Cloud Mesh integration to your Uniform project and your Uniform Canvas-enabled app. Now the composition JSON is expected to contain the data from Order Cloud, and you can proceed building amazing front-end experiences.

Next steps

If you haven't already done so, activate Personalization and A/B testing within your app by following this tutorial. This will enable your business users to personalize shopping experiences without developer effort.