The commercetools integration

Adding the commercetools integration to your Uniform project brings your structured content from commercetools into your Uniform project. Team members can then leverage commercetools data to create experiences without needing a developer.

The integration comes with these archetypes to help connect commercetools items to Uniform elements:

Before you start

You must the following available to complete this setup:

  • commercetools account with administrator access.
  • Uniform account with administrator access. If you don't already have one, you can request an account at https://uniform.dev/try.

To configure a connection to commercetools, you need to create an API client. This gives you the settings that will enable Uniform to use the commercetools API:

  1. Log into the commercetools Merchant Center.
  2. Navigate to Settings > Developer Settings.
  3. Click Create new API client.
  4. Provide a name.
  5. Under Scopes, make the following selections:
    • Categories > View
    • Products (all) > View
    • Products (published) > View
  6. At the bottom of the screen, in the download your credentials section, switch to Environment Variables (.env).
  7. API credentials are displayed. Save these values because you will need them in the next section.

  1. In Uniform, open your project.

  2. Navigate to the Integrations tab.

  3. Scroll to the section Browse integrations.

  4. Click commercetools.

    add-integration-to-project
    The screen to add the integration to your project.

  5. Click Add to project.

    settings-empty
    Once the integration is added you'll be prompted to enter some settings.

  6. Enter the required fields:

    Fieldcommercetools environment variable
    Project KeyPROJECT_KEY
    Client IDCLIENT_ID
    Client SecretCLIENT_SECRET
    API URLAPI_URL
    Auth URLAUTH_URL

  7. Enter the optional fields, if applicable:

    FieldDescription
    LocaleSets the locale for product titles Canvas users see in product fields.
    Currency CodeSets the currency displayed to Canvas users on products.

  8. Click Save.

Once you've installed the integration, the next step is to connect your commercetools merchant account to your Uniform project by creating a new data source.

  1. Navigate to Experience > Data Types. A data type is an element that can be retrieved from a data source, so the first step is to identify a data source.

  2. Create a new data source by clicking the Add data type button and select the "Create new" option under the commercetools label.

    add-data-source
    Add a data type.
create-new-data-source
Where to create a new data type from the available data sources.

  1. Provide details specific to the commercetools project you are connecting to:

    FieldDescription
    Project keyPROJECT_KEY
    API client IDCLIENT_ID
    Secret keyCLIENT_SECRET
    API URLAPI_URL
    Auth API URLAUTH_API_URL

  2. Name your data source. Choose a name that helps to inform your editorial users where the content is coming from.

Before you start connecting commercetools data to Uniform, it's important to first create some data types. Data types define which types of data editors can use. This could be simple, like allowing an editor to select a single "product name" entity, or more perhaps a more complex query such as "the five latest product article entries."

Go to Experience > Data Types and click the Add data type button from below the commercetools data source that you set-up earlier.

add-data-type
Add a data type after selecting the data source.

Next, you will want to select and configure an archetype from the options below.

Archetype: Single entry#

The single entry archetype will always return a single entry from commercetools, based on a selection by the editor in Uniform. This is useful for non-list elements that render as an independent item, such as a single product entry. It can accept a variable from a dynamic token (such as a slug) and retrieve the corresponding entry.

single-entry
A test fetching data for a single entry.

The multiple entry archetype lets an editor hand pick multiple entries to render as a list. This is useful when a small selection of specific entries is required, such as in a "featured products" list.

mutliple-entries
A test fetching data for two selected entries.

Once you have configured your data types, you will be ready for the final step of connecting your commercetools data to your Uniform elements.

For commonly used components, Uniform recommends using patterns. This is the best approach when content architects want to create a reusable connection between a data type and a component, and avoids mapping data every time you use commercetools data.

With patterns, you define exactly how a component (or set of components) should be configured ahead of time, including the data bindings to external services. Once configured, composing with commercetools is as simple as selecting the pattern you need (such as a set of product information), just like you would select a standard component. The difference is that this time, you can also select the commercetools resource that should supply the data and Uniform will handle the rest.

select-pattern
Selecting the pattern component for insertion into a composition.
implemented-pattern
You can update which record the pattern connects to by selecting a new entry. All fields will update automatically.

To learn more about how to use patterns, check out the pattern guide.

The most granular approach for bringing your commercetools data into Uniform is to connect a resource to a component field directly. To do this, open the composition and component you want connect to commercetools data.

  1. Select a field within the component that you wish to connect commercetools data to.

  2. Click the on the top left of the field you can open up the data resource mapping dialog.

    connect-data-to-resource
    Fields and parameters that support data connections will have an icon by which you access data resources.

    From here, you will be guided through the process of setting a data resource for the composition, if none are available already. To set up the data resource, provide a name. Choose something that connects it to the resource is used in the composition (such as "Featured product"), and select your data by using the data types you defined earlier.

    select-data-resource
    Selecting a data resource to connect to the composition.

  3. After you select your data resource, map the appropriate field from the data resource to the parameter on your component. For example, map the title field from your Contentful entry to the title field of your Uniform component.

    map-field
    Map the field from commercetools to the parameter.

    Now that you have a data resource configured, you can use this resource to connect fields across the entire composition without needing to recreate the resource. This also means that if you update the data resource to a different selection or query, then all the components that map to the original data resource will update automatically with no remapping.

Last modified
Next
commercetools parameters