Set up a custom remote source

Follow this guide to add 3rd party content to your web application using Prepr.

Introduction

When creating content items for your web application, you may want to reference content stored in an external system such as another CMS, legacy system, or eCommerce platform. With Prepr, you can easily use any 3rd party system as a remote content source by following the steps below.

Check out the predefined remote sources doc if you want to integrate to Commercetools, Commerce Layer or Typeform.

Step 1: Set up your custom API endpoint

In this step you need to prepare the API endpoint so that Prepr can make the calls to your external system.

Data format

1. Make sure your custom API response conforms to the predefined structure and format as follows:

{
    "items": [
        {
            "id": "unique_reference_id",
            "created_on": "2019-11-21T12:51:03+00:00",
            "changed_on": "2019-12-21T12:51:03+00:00",
            "body": "Title that will be displayed in Prepr",
            "description": "Descrtiption text displayed with the title",
            "image_url": "https://picsum.photos/200/30",
            "external_url": "https://example.com/admin/edit/products/9387498273",
            "data": {
                "key": "value"
                // This key value array will be returned within the Content item response.
            }
        }
    ],
    "total": 256
}

The response must contain the following fields:

• items — an array containing all attributes that should be available as remote content in Prepr. See the detailed attribute description in the table below.
• total returns — the total number of items available. The total value also depends on the search parameters applied.

2. (Optional) Define Headers, specific key-value pairs, to add authentication or filters on the API's end. Check out the remote source setup for more details.

Supported parameters

To learn more about how Prepr interacts with the API endpoint, consider the following:

• Automatic synchronization. To keep your remote content constantly updated in Prepr, your custom API must support filtering on the last changed items. In this case, Prepr will call the API with a changed_since param to refresh your items every 15 minutes. For example, website.com/prepr/feed?changed_since=1583414373 (UTC timestamp).

• Pagination. The API must work with the skip and limit params to paginate params, and the API response should contain a maximum of 50 items. For example,

  • Page 1: website.com/prepr/feed?skip=0&limit=50
  • Page 2: website.com/prepr/feed?skip=50&limit=50
  • Page 3: website.com/prepr/feed?skip=100&limit=50, etc

• Search. To help editors search for a remote content item, Prepr calls the external system URL with the q param containing the editor's input, for example, website.com/prepr/feed?q=Looking%20for%20an%20item. In this case, the total response will be updated with the filtered number of matching items.

• Locale. To help editors search for a remote content item, Prepr calls the external system URL with the Prepr-Locale header. This header, which is based on ISO 639-1 standards (e.g., en-US), reflects the editor's current viewing language. This feature enables you to customize your feed according to the viewing language. (This is necessary only if your feed supports multiple languages).

Step 2: Add the custom remote source in Prepr

Now that you’ve set up your custom API endpoint, proceed with the configuration in Prepr. You’ll need to connect Prepr to your external system using the API credentials. To add a custom remote source, follow these steps:

1. Click the Schema tab to open the Schema Editor.
2. On the Schema Editor page, navigate to the Remote content section and click Add source.
3. In the opened dialog window, choose to add a custom source.

4. In the next screen, name and describe the source as follows, then click Add.

5. Add fields to your remote source in Prepr and map them to the corresponding fields in the external system. Prepr will use those fields to retrieve and store content from your external system.

a. To add fields to the remote source, drag and drop the desired field type from the list on the right into your source. You can choose from the following field types:

• Text
• Boolean
• Number

b. Then, set the Display name to the Prepr field name and set the Source API ID to the corresponding field name from your external system:

Step 3: Add remote content to your content item

Once you’ve connected to the external system and added the Remote content field to your model, you can add the remote content to a content item using the following steps:

1. Navigate to the Content tab and click on the desired content item from the list.
2. In the remote content section, click the button to add new items (in our example – Add product), search through the catalog and add the desired items to the content item.
3. Save and publish this content item to complete the setup.

All done

That’s it. Now your web page includes 3rd party content. Prepr will synchronize your remote content automatically to keep it up to date.

Next steps

Now that you’ve added products from your external system to the content item, you can retrieve the corresponding data using the API. Check out the following docs:

• Field types (remote content)