Create an app to support Native external references

Table of contents

• Overview
• Prerequisites
• Example
  • Instructions to create and run the app
    • Copy the example
    • Create a custom app definition
    • Build and upload the app
    • Create resource entities
    • Install the app
    • Configure your content model
    • See your app in action
• Code structure
  • Functions
  • App manifest
  • Set up ResourceEntities
  • Property mapping
• Available scripts

Overview

Contentful supports external content integration through the App Framework. While the App Marketplace offers ready-made solutions tailored for systems like Shopify or commercetools, connecting to other systems requires developing custom frontend apps with bespoke implementation.

To overcome these challenges, we offer a more streamlined and cohesive approach to linking third-party systems through existing content model Reference Fields. This upgraded version of fields is referred to as Native external references.

With Native external references you can connect any third-party system to existing reference fields.

Prerequisites

• We are assuming you are familiar with the following concepts:
  • App Framework, including App Definition and App Installation
  • Functions
• Your organization is on a paid plan (except Lite).
• The space where you will install the application has the Orchestration feature set enabled.
• Your system has the latest LTS version of Node.js installed.

Example

For the purpose of this example, we will be connecting to the MockShop external system and resolving its data through the Contentful GraphQL API.

With Native external references we introduce the following new entity types that allow us to model the data from third-party systems in Contentful:

• Resource Provider - a third-party system that provides resources. Each provider can have multiple resource types. In our example: a MockShop provider.
• Resource Type - a specific type of resource (not the resource itself) that is provided by a resource provider. In our example: Product.

Instructions to create and run the app

Copy the example

To get started with your application, you need to make a local copy of the example code by running the following command in your terminal:

npx create-contentful-app@latest <name-of-your-app> --example native-external-references-mockshop

Once the process finishes, navigate to the directory that was created by running this command:

cd <name-of-your-app>

Create a custom app definition

To see your app within Contentful, you must first set it up. To do that, we will create an app definition, which is an entity that represents an app in Contentful and stores general information about it.

To create the app definition, run this command:

npm run create-app-definition

You will need to answer the following questions in the terminal when prompted. Feel free to proceed with the default options provided.

1. Name of your application. This is how your app will be named and it will be displayed in a few places throughout the UI. The default is the name of the folder you created.

2. Select where your app can be rendered. This shows potential app locations where an app can be rendered within the Contentful web app. We don’t need to configure any app locations in this example. Simply press Enter to skip setting them up.

3. Contentful CMA endpoint URL. This refers to the URL used to interact with Contentful's Management APIs. In most cases the default CMA URL should be selected. For EU data residency, api.eu.contentful.com should be used instead of the default.

4. App Parameters. Parameters can be used to set default values or define custom validation rules for the app configuration. We won't define any in this example, but might be helpful for your use-case, for instance to configure an API access token parameter. For more details see the App Parameters documentation.

   • Opt for N to skip the process of defining the parameters.

5. The next steps will lead you through the process of providing a Contentful access token to the application and specifying the organization to which the application should be assigned.

You now have a basic application that can be enriched with additional information that will enable the example project you downloaded to function properly.

Build and upload the app

After creating the app definition, we can take care of uploading the code by running these commands:

npm run build
npm run upload

The interactive CLI will guide you through the process of providing the necessary details, such as a Contentful Management API (CMA) endpoint URL. The default value is api.contentful.com, but you can specify a different one if needed. Select Yes when prompted if you’d like to activate the bundle after upload.

Create resource entities

Executing the provided command in your terminal will generate resource entities within the app definition, which are described in more detail under the Set up ResourceEntities step.

npm run create-resource-entities

This will tell Contentful that we want to connect to MockShop via the function we uploaded under the Build and upload the app step and that the same function can provide MockShop:Product Resource Types.

If you would like to list all the previously created entities, you can utilize a similar script that prints out more verbose details: npm run show-resource-entities. If the entities were incorrectly created, you can run npm run delete-resource-entities to delete the incorrect entities and try again.

Install the app

• After you have successfully uploaded your app, install it into an existing space by running the npm run install-app command.
• Select the space with the Orchestration feature enabled and environment in which you would prefer to install the example app from the dialog that is displayed:

You will have to grant access to the space the app will be installed in.

Your example app is now configured and installed.

Configure your content model

To render content from MockShop, we must first create and configure the content model.

To create and configure the content model:

1. Open the Contentful web app and navigate to the space where you have installed the MockShop app.

2. Navigate to the "Content model" tab, and click Create content type. The "Create new content type" modal is displayed.

3. Enter your preferred name, and click Create. The content type is created.

4. Click Add field and select Reference as the field type. The "Add field modal" is displayed.

5. Enter a field name, in our case Product, and select the Different spaces and external sources option.

6. Select the Type. You can choose between having a single link, One reference, or a group of links, Many references.

7. Click Add and configure. The field configuration page is displayed.

8. Under the "Validation" section, specify the sources that are allowed as potential sources of data in the field being configured.

9. Set the Source dropdown field to MockShop. Once selected, the Entity type dropdown allows you to choose the MockShop: Product we previously configured when we created the resource entities.

   NOTE: If you choose Contentful as the source, you can combine cross-space Contentful resources with MockShop entities when dealing with fields that have multiple references.

10. Click Confirm. The field is added to your content model.

11. Once you are done configuring your fields, click Save.

See your app in action

Now that the content model has been configured to display resources from MockShop, an entry can be created to incorporate data from particular external sources.

To create an entry:

1. Open the Contentful web app and navigate to the space where you configured the content model in the previous step.

2. Navigate to the "Content" tab and click Add entry.

3. Select the content type you previously created with the configured field for linking to external sources. The entry editor is displayed.

4. Under Product, click Add existing content. The "Add content" modal is displayed.

5. You can search through the available content from the external provider, and select the one you want. The function built in our app fetches this content from MockShop.

   • If your field is a single reference field, select one of the entries. The "Add content" modal closes itself automatically.
   • For multiple references fields, you can select as many entries as needed. Click Add once you are satisfied with your choices.
   NOTE: If you are using a field with multiple references, you are not limited to only one source. You can combine cross-space links with resources from MockShop.

6. Your first entry with Native external references is ready! Click Publish once you are done with the editing.

7. Access the published entry data using the GraphiQL app and query it.

Code structure

Functions

The example app is using Functions to provide a connection between Contentful and the MockShop API. In the functions/mockShop.ts file, we are defining the following events that are necessary for Native external references to function properly:

• resources.search - retrieval of specific content based on search queries.
• resources.lookup - retrieval of specific content based on URNs (IDs).
• graphql.resourcetype.mapping - retrieval of resource type mappings, which determines what fields map to an external type.
• graphql.query - handles GraphQL queries for the external third-party API.

App manifest

The app manifest, located in the root of the project as contentful-app-manifest.json, describes the app and its capabilities. It contains a functions property, which is an array of functions the app can run.

The function properties are:

• id: The id of the Function.
• name: A readable name for the Function.
• description: A brief description of the Function.
• path: This is the path to the transpiled source file of the Function in your bundle, exposing a handler function
• entryFile: Path pointing to the source file of the Function. Exposing a handler function.
• allowNetworks: A list of endpoints the Function should be allowed to connect to, this is a security feature to prevent unauthorized access to your network.
• accepts: An array of event types the Function can handle, which have an effect on where the functions can be used within Contentful. In this case we configure these event types: [resources.search, resources.lookup graphql.resourcetype.mapping,graphql.query].

Set up ResourceEntities

All ResourceEntities (such as the Resource Provider and various Resource Entities) are created and managed via the utility code in src/tools. These helper methods allow you to:

• create-resource-entities.ts - Create new ResourceEntities.
• delete-resource-entities.ts - Delete ResourceEntities.
• show-resource-entities.ts - Show configured ResourceEntities.

You can customize the ResourceEntities located in src/tools/entities according to your specific requirements using these helper methods.

Property mapping

Resource Type Mappings are used to define how a third-party schema, such as an external GraphQL type, maps to a Contentful ResourceLink entry. This allows Contentful to understand how to reference and display your external resource data in your Contentful entries.

For example, if your external type is Product and contains the id, name, or price fields, you can configure the mapping located in functions/mockShop.ts so that all the fields in the product type are connected to the corresponding reference field in Contentful.

A typical resource type mapping response looks like this:

{
  "resourceTypes": [
    {
      "resourceTypeId": "MockShop:Product",
      "graphQLOutputType": "Product",
      "graphQLQueryField": "product",
      "graphQLQueryArguments": {
        "id": "/urn"
      }
    },
  ]
}

Available scripts

In the project directory, you can run:

npm start

Creates or updates your app definition in Contentful and runs the app in development mode.

Open your app to view it in the browser. The page will reload if you make edits. You will also see any lint errors in the console.

npm run build

Builds the app for production to the build folder. It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes. Your app is ready to be deployed!

npm run upload

Uploads the build folder to Contentful and creates a bundle that is automatically activated. The command guides you through the deployment process and asks for all required arguments. For more information about the deployment process, see the Deploy with Contentful section.

npm run upload-ci

Similar to npm run upload, this command will upload your app to Contentful and activate it. The only difference is that with this command, all required arguments are read from the environment variables (e.g., when you add the upload command to your CI pipeline).

For this command to work, the following environment variables must be set:

• CONTENTFUL_ORG_ID - The ID of your organization.
• CONTENTFUL_APP_DEF_ID - The ID of the app to which to add the bundle.
• CONTENTFUL_ACCESS_TOKEN - A personal access token.
• HOST - Required for EU data residency and used in npm run create-resource-entities.

npm run open-settings

Opens the settings in the Contentful web app so that you can use the UI to change the settings of an App Definition.

npm run install-app

Opens a dialog to select the space and environment where the app associated with the given App Definition should be installed.

npm run create-app-definition

An interactive CLI that will prompt you to provide necessary details to create an App Definition.

npm run create-resource-entities

A script that reads the entities folder and creates new entities within the system. It will print out a minimal log when the operation has succeeded.

npm run show-resource-entities

A script that lists all the previously created entities. It will print out more verbose details about the entities.

npm run delete-resource-entities

A script that deletes previously created entities.