Skip to main content

Elastic Path integration for Uniform Mesh

Elastic Path Commerce Cloud provides API-first, headless commerce products & services.

This integration allows business users to build personalized landing pages and storefronts by repurposing product content from your Elastic Path product catalog and enables developers to use modern performance-optimized front-end tooling like Next.js and have a fantastic developer experience.

This section describes how to configure and use this integration.

Pre-requisites​

  1. Access to Elastic Path and retrieve the API keys, we will need those to configure the integration. Untitled

  2. Uniform account with at least one project. Signup for free here.

Step 1: Install and configure the integration​

  1. Locate the Elastic Path integration in the list of available integrations within your Uniform project's Settings -> Integrations:

    Untitled

  2. Click on the plus icon to install the integration.

  3. After the installation, the empty configuration screen will display, fill out the configuration settings as described (use the Client ID and Client Secret from the earlier step):

    Untitled

We recommend using the PCM (Product Content Management) API version, but you can also switch to Legacy, depending on your preference.

  1. Click "Save". That's it, the configuration is installed and configured.

Step 2: Create a component parameter​

Now let's connect the product data with one of your components in Canvas.

The integration ships with two types of Elastic Path parameters, each targeting a specific scenario:

Untitled

"Product selector" parameter type​

Allows to pick one or many products from a specific catalog. This type saves a specific product selection within a given parameter.

  1. Let's add a new parameter to any of the existing or new components in Canvas Component library.

For example, let's create a new component called Product and add a new parameter:

Untitled

  1. Specify a name "Product" (remember the name as we will be referring to it from our component's front-end code using Public ID).

  2. Pick the "Product selector" parameter type from the list of types and select a specific catalog. You have a choice to allow multi-selection or not:

Untitled

  1. Make this component a composition component by toggling the Composition checkbox.

Unless you have other composition component already, then allow this component into a slot of another composition component.

  1. In order to create an instance of this component, head over to the Composition section and create a new composition.

  2. After the composition is created and the newly created/modified component with the Product parameter is placed, you should be able to see the following experience, allowing to pick one or many products from your catalog and save the component:

Untitled

"Product selector" parameter value​

If you are wondering what value does Uniform store, here is a sample below. The value includes the product id in a given catalog, the id of the catalog and the API version.

important

Uniform doesn't store the actual product details data. This is a job of an Enhancer to resolve at build-time or run-time, depending on your application architecture. Enhancers can be added to your web app, or deployed separately as an API proxy. The section below describes how the enhancers are added.

{
  "_id": "da7ed430-4fee-4d60-9a88-8730caa1ed3c",
  "type": "product",
  "_name": "Elastic Path",
  "parameters": {
    "product": {
      "type": "elastic-path-product-selector",
      "value": {
        "value": ["5660251b-7431-4d21-8125-d8508f909d30"],
        "version": "pcm",
        "catalog": "043800f6-db04-4754-be82-55a3ce195271"
      }
    }
  }
}

"Product query" parameter type​

Allows to create a query criteria for your product catalog. In contrast to the Product selector type, this parameter type does not persist the specific product matches, and it saves the search criteria iteself, which allows to defer the product selection to runtime.

The process of adding the Product query parameter is identical to the one described above.

The difference is in the way the component UX is implemented and what value is stored in Uniform.

The UX of this parameter type allows to configure a query criteria:

Untitled

"Product query" parameter value​

If you are wondering what value does Uniform store, here is a sample below. The value includes the query criteria parameters, if specified:

  • category id
  • count
  • catalog id
  • keyword
  • API version
important

Uniform doesn't store the actual product details data. This is a job of an Enhancer to resolve at build-time or run-time, depending on your application architecture. Enhancers can be added to your web app, or deployed separately as an API proxy. The section below describes how the enhancers are added.

{
  "_id": "60c91cdb-bf2e-4322-8a3f-f8d4314fc51d",
  "type": "products",
  "_name": "Products",
  "parameters": {
    "products": {
      "type": "elastic-path-product-query",
      "value": {
        "count": 1,
        "catalog": "043800f6-db04-4754-be82-55a3ce195271",
        "keyword": "Lightweight Jacket",
        "version": "pcm",
        "category": "8aae05c6-93df-4dc7-a6be-5d821ee32ea5"
      }
    }
  }
}

What else can you do?​

Now that you have the components that are connected to your commerce content, you can leverage Uniform Personalization and A/B testing, as well as activating the Elastic Path integration with your web application.

Step 3: Wire up your 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 Elastic Path 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:

Adding Elastic Path 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 Elastic Path with this command:

    npm install @uniformdev/canvas-elastic-path

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

    ELASTIC_PATH_API_HOST=api.moltin.com
    ELASTIC_PATH_CLIENT_ID=aaaa
    ELASTIC_PATH_CLIENT_SECRET=bbb

  1. 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.)

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

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

    • A: import ehnancer for Elastic Path
    • B: run the enhance function, with will return post-enhanced composition
    • C: register enhancer for Elastic Path
    • D: return the post-enhanced composition as a page prop
/pages/[slug].js
// A. import ehnancer for Elastic Path
import { elasticPathEnhancer, ELASTIC_PATH_PARAMETER_TYPES } from '@uniformdev/canvas-elastic-path';

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 Elastic Path:
    enhancers: new EnhancerBuilder().parameterType(ELASTIC_PATH_PARAMETER_TYPES, elasticPathEnhancer()),
    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 Elastic Path Mesh integration to your Uniform project and your Uniform Canvas-enabled app. Now the composition JSON is expected to contain the data from Elastic Path, 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.