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.
AttributeTypeDescription
idstringA unique item identifier for internal use only. The identifier should not be reused upon deleting an item. This field is required.
bodystringAn item title for internal use only. This field is required.
created_onintDate in ISO (UTC Timezone) for internal use only, e.g., 2019-11-21T12:51:03+00:00.
changed_onintLast changed date in ISO (UTC Timezone) for internal use only, e.g., 2019-11-21T12:51:03+00:00.
descriptionstringAn item description for internal use only.
image_urlstringAn image thumbnail URL for internal use only.
external_urlstringAn optional URL to open a page in a web application from within Prepr. The value is for internal use only.
dataarrayAn optional single-dimensional key-value array of data returned by the Prepr API in the content item response. The Source API ID's you choose in the remote source fields should correspond with the key values returned in data.
  1. (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.

Custom remote source

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

Field
Description
Display nameA unique name to identify this source in Prepr.
Type nameA name used for accessing this source through the API. The value is generated automatically and matches the Display name you specified.
Base URLThe endpoint URL that is used to make the API calls. Refer to your external system API specification.
Domain(s)An external system domain to be allowed in Prepr. It guarantees Prepr will use only domains approved for authorized access to data.
HeaderAdd the key-value pair to pass additional information about your API request. This key-value array will be returned within the Content item response.
ButtonA unique name to identify this source in a content item.
IconAn icon to identify this source in a content item.
  1. 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:

Select a field

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:

Fill in a field

Note

Once you set up the custom remote source in Prepr, an access token will be generated automatically. You can find it under Settings > Access tokens. Prepr will use the token as a credential when making API requests.

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.

Add remote content to a content item

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: