Third party orchestration

What is Third party orchestration?

The Third party orchestration feature allows you to resolve content referenced from other product information systems using the Contentful GraphQL API.

Use Third party orchestration

Currently, the Third party orchestration feature supports integrations with Shopify and Commercetools (third parties onwards). It requires a corresponding Contentful App to be installed and configured in your Space.

NOTE: The Commercetools integration is only available through our Early Access Program (EAP).

We enabled an integration between Contentful and third parties in our GraphQL API which allows for streamlined access to data from both systems with a single request. The integration adds a new field to the source type with a _data suffix, that is specifically designed to establish a connection to the third party data. This field serves as a link, bridging the gap between the Contentful type and the underlying third party type.

Authentication

For authenticating calls to the third parties, we use the information provided while configuring the corresponding Contentful App.

Technical and query complexity limits

• Only GraphQL support.
• Only Symbol fields are supported.
• Time to live (TTL) for response caching for GraphQL queries with third party data is 60 seconds.
• Rate limits of the respective platform are applied.
• Requests to the Third party sources are not counted against complexity limits.

Get started with Third party orchestration

Step 1: Install and Configure Apps with Third party orchestration

Follow the steps defined in the installation instructions to install and configure the Shopify App or commercetools App (EAP) into the target environment.

Step 2: Configure your field to resolve third party content

Third party content only works if the field has the appropriate annotation. You can set the annotation in the content-model-editor in the field settings under the appearance tab by clicking Resolve content on delivery checkbox.

Step 3: Use GraphQL API to query third party information

Open your preferred GraphQL client or use an online IDE, such as GraphiQL or GraphQL Playground.

Insert the following GraphQL query as an example, replacing "ENTRY_ID" with the ID of the product you want to query:

{
  topicProduct(id: "ENTRY_ID") {
    sys {
      id
      spaceId
    }
    thirdPartyReference
    thirdPartyReference_data {
      title
      description
    }
  }
}

Run the query and you should receive a JSON response containing the product details, such as title and description:

{
    "data": {
        "topicProduct": {
            "sys": {
                "id": "dzpSfj0LhgtldEHkwFxMV",
                "spaceId": "8tlo7deo9l8e"
            },
            "thirdPartyReference": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzgxMDg5MDY2NzY1NDA=",
            "thirdPartyReference_data": {
                "title": "Long sleeve t-shirt",
                "description": "A long sleeve t-shirt is a classic and versatile piece of clothing that provides comfort and style. With its long sleeves, it offers additional coverage and warmth compared to a traditional t-shirt. Made from soft and breathable fabric, this t-shirt is perfect for layering or wearing on its own. It is available in various colors and sizes, making it suitable for everyone's personal taste and style."
            }
        }
    }
}

You can also use the JavaScript example provided in the original input to query Shopify Products directly from the Contentful GraphQL API. Make sure to replace 'YOUR_CDA_TOKEN' and 'YOUR_SPACE_ID' with your respective access token and space ID.

const access_token = 'YOUR_CDA_TOKEN';
const spaceId = 'YOUR_SPACE_ID';

const productQuery =
  /* GraphQL */
  `
    {
      topicProduct(id: "dzpSfj0LhgtldEHkwFxMV") {
        sys {
          id
          spaceId
        }
        thirdPartyReference
        thirdPartyReference_data {
          title
          description
        }
      }
    }
  `;

const requestOptions = {
  method: 'POST',
  headers: new Headers({
    'Content-Type': 'application/json',
    Authorization: `Bearer ${access_token}`,
  }),
  body: JSON.stringify({
    query: productQuery,
  }),
};

fetch(
  `https://graphql.contentful.com/content/v1/spaces/${spaceId}`,
  requestOptions
)
  .then((response) => response.json())
  .then((result) => console.log(JSON.stringify(result, null, 2)))
  .catch((error) => console.log('error', error));

Explore the schema with GraphiQL

You can explore and inspect the schema of a space using GraphiQL, an in-browser GraphQL IDE (integrated development environment).

To open the GraphiQL server visit the https://graphql.contentful.com/content/v1/spaces/{SPACE}/explore?access_token={CDA_TOKEN} URL in your browser.

Supported integrations

Shopify

With Shopify integration, Third party orchestration resolves links to Shopify Products, Collections or Product Variants that were created using the Shopify App.

We support an integration on fields linked to the following Shopify entities:

• Product Variant
• Product
• Collection

commercetools

With commercetools integration, Third party orchestration resolves links to Products and Categories that were created using the commercetools App.

We support an integration on fields linked to the following commercetools entities:

• Product
• Category

{
  thirdPartyReference_data {
    masterData {
      current {
        name(locale)
      }
    }
  }
}

How to get help

Third party orchestration is in early preview and is NOT a supported Contentful product yet. To find help please ask a question in Contentful Community #help channel. If you are part of the Early Access Program, you will be provided with direct contacts in your welcome email.