• What is the Shelf Content Integration Layer?
• What purposes does this feature serve?
• What is a Contentful connector?
• How is it configured?
• How is it used in practice?

For proper operation of your Contentful connector and successful synchronization of your content from the Contentful platform into Shelf KMS, the following preconditions must be met:

• Admin Panel must be accessible on your Shelf KMS account
• Settings menu must be accessible for you on your Contentful account
• Content items (articles, documents, etc.) must be available on your Contentful account.

In-depth configurations and use cases of the Shelf Content Integration Layer are described in the dedicated Shelf Content Integration Layer Feature User Guide mentioned above, but the short example of the CIL workflow is as follows:

1. You access the Content Integration Layer feature in your Shelf KMS (Admin Panel).
2. You select one of Shelf-preconfigured connectors or create your custom one (based on the external content repository from which you need to sync content)
3. You create a connection profile that uses the selected or created connector, and configure it: indicate credentials (username/password/API key/token/etc.) to access your external repository. All these credentials and access details can be taken from that external platform, and in the respective section below we will show you how to get them on Contentful.
4. You create a sync flow that uses the created connection profile and configure this sync flow to run either on some specific schedule or on demand. It is here where you can apply filters to tell CIL which exactly content needs to be synced.
5. You run the created sync flow manually (if set to run on demand) or wait for the scheduled run, and get your content from the needed external source right in Shelf KMS.

For the proper operation of the Contentful connector to sync your content from Contentful into Shelf KMS, you need to do certain actions both in Contentful and in Shelf. Read the chapters below to learn what exactly you need to do.

To create a dedicated API key, follow the below steps.

1. Go to the Settings menu and select the API keys option.

Figure 3. Accessing API keys parameters in Settings

Figure 4. Starting the API key creation process in Contentful

• Name (1): a mandatory field you need to fill in that contains the name of the API key you are creating.
• Description (2): an optional field so you may or may not add some description for the API key.
• Space ID (3): a platform-generated identifier of your Contentful storage that is needed for configuring communication between Shelf and Contentful. Copy and save it somewhere for further use.
• Content Delivery API - access token (4): a platform-generated identifier that acts as an authentication and authorization means for your Contentful storage and can be used by other systems - Shelf KMS - to access and sync your content. You also need to copy and save it for further use.
• Content Delivery API - access token and Environment parameters are not needed for the purposes of this document.

Figure 5. Working with the API key parameters

If you don’t need to create a new API key to let Shelf KMS connect to your Contentful storage, you may use one of the existing keys, if any.

To do so, go to the API keys option in the Settings menu (Figure 3), select and open the needed API key in the APIs page (Figure 4), and, finally, find and copy the Space ID and Content Delivery API access token values (Figure 5).

Once you have created a new API key or used an existing one and copied the relevant values, you are done with the configurations on the Contentful side. Before proceeding to the configurations on the side of Shelf KMS, make sure you have content in your Contentful storage.

From the standard workflow described above you see that to start configuring and using your Contentful connector you need to access the Content Integration Layer feature. To do so, perform the following steps:

1. Log into your Shelf KMS account using valid credentials.
2. Once logged in, go to the Admin Panel by selecting the respective option in the dropdown menu.

Figure 6. Accessing Admin Panel in Shelf KMS

Figure 7. Accessing CIL modules in Admin Panel

In fact, no configurations are needed for your Contentful connector. It is prebuilt and preconfigured by Shelf. You can see it in the connector list that appears once you select the Connectors option in the Content Integration Layer section.

Figure 8. Viewing the Contentful connector in CIL

What you need to do next is to create and configure a connection profile dedicated to work with the external content source such as your Contentful instance.

The Contentful connection profile is a feature that uses the prebuilt Contentful connector and allows Shelf KMS to access, authenticate on Contentful, and communicate with it to find and sync content stored there. But to enable its proper operation, you need to create and configure it as described in the procedure below.

1. In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Connection Profiles option.
2. In the Connection Profiles window that appears, you see the list of available connection profiles. Neither the prebuilt nor other custom connection profiles can be used for communicating with Contentful, so you need to create a new connection profile. Click the Create Connection Profile button to start.

Figure 9. Accessing CIL connection profiles and starting creating a new connection profile 

Figure 10. Configuring the Contentful connection profile in Shelf

In the Runtime Settings section, you need to use your Contentful Space ID you have previously copied from the Contentful settings. In this section, you also fill in other fields required to identify content collections and items stored in Contentful.

• Сollection сontent type ID: This parameter identifies the type of content in a specific collection. The value 'wikiCollection' suggests this collection contains wiki-type content
• Collection field ID: With the value ‘collection’ this parameter identifies the field in the data that contains information about the collection
• Primary content type ID: - This parameter identifies the main type of content in the collection. In our case, the primary content is a 'wikiArticle'.
• Collection title field ID: This identifies the field that contains the title of the collection because our value is 'title'
• Rich text field ID: With the value 'body' this identifies the field that contains the main body of text in the content, likely formatted in a rich text format that allows for more complex layouts than just plain text
• Title field ID: With the value 'title' this identifies the field that contains the title of the individual content items.
• Description field ID: With the value 'description' this parameter identifies the field that contains a description
• Use single virtual collection: This parameter is used to tell Shelf how you want to categorize the content synced from Contentful: under individual collections (as used in Contentful) or under one virtual collection. The value here can be ‘false’ if you go with the first case or ‘true’ if you choose the second option
• Preview URL: This parameter allows you to preview content created in a Contentful space either in a local or an online version of your website or app. The value to be placed here looks as follows: https://[YOUR_PREVIEW_DOMAIN]/[PLACEHOLDER_TOKEN]. Details of this parameter and explanation of its operation can be found in the respective section below
• Sync empty content items: This parameter can have either “true” or “false” value and allows to sync the published global Contentful articles WITH local articles which are inside such global content items and have the draft or unpublished status. See the details in the relevant section below.

In the Credentials section, the Access token field, you need to enter the Content Delivery API - access token you have previously found and copied in the Contentful settings.

❗Note:

Fields with the asterisk symbol (*) are mandatory. If they are left blank, you are not able to save the connection profile you are creating.

Now that you have configured the Contentful connector and connection profile, you need to create and configure the Contentful sync flow. Sync flows are basically sets of instructions telling Shelf KMS what content and when it needs to pull from external sources, in our case - Contentful.

To create and configure the Contentful sync flow, perform the following steps.

1. In the Admin Panel in Shelf KMS, go to the Content Integration Layer section, find and select the Sync Flows option.

Figure 11. Starting creating Contentful sync flow

Figure 12. Configuring the Contentful sync flow

Figure 13. Configuring the scheduled run of Contentful sync flow

Once done, click the Create button to finish your Contentful sync flow creation.

Once you have created the Contentful sync flow, you can either wait until it performs the content sync per schedule (if you have selected the On-schedule option for the sync flow run type), or start the sync manually at any time (if you have selected the On-demand option for the run type).

To manually start syncing your content from Contentful into Shelf, follow the below steps.

1. Open the newly created Contentful sync flow, find and go to the Jobs tab in its window.
2. In the tab window, find and click the Trigger Now button to start syncing content.

Figure 14. Manually running content syncing from Contentful into Shelf

Figure 15. Confirming the sync start

Figure 16. Viewing the running Contentful sync job

❗Note:

The sync job can be triggered manually both for the on-schedule and on-demand sync flows, unless there is a sync job running at that time. 

In the first case, the manually triggered job overrides the schedule set for the sync flow. At the same time, the sync flow execution will resume to occur per schedule after the manually triggered sync job is finished. If you manually trigger the sync flow job, it starts immediately.

If there is a running sync job in this sync flow when you attempt to start a new job, this new job will not be created and, respectively, the content sync will not be started. In this case you will see the error message informing that the job is already running. 

If there are no other sync jobs running in this sync flow, the Jobs tab window refreshes, and a new job with the IN PROGRESS status appears in the table grid.

Figure 17. Stopping the sync job

Once the sync job triggered manually or on schedule is finished, you will see it to change the status to SUCCESS (if the sync was successful) or FAILED (if some issues occurred during the sync). In the latter case, check your configurations in the Contentful connection profile and sync flow and rerun the sync job.

If the sync was successful, you can see the recently sync content directly from this window. To do so, open the Recent Sync tab and check the content items synced from Contentful into Shelf.

Figure 18. Viewing the recently synced content from Contentful

Note that the tab shows not more than 50 content items, so if you have synced more items, you will see them only after going back to the Shelf KMS Homepage and selecting the respective source - Contentful.

Even when you successfully configured the Contentful connector, connection profile, sync flow, run the sync job and pulled the content from your Contentful repository, you need to add Contentful collections to the permitted sources via Shelf’s User Groups feature. Otherwise, you will not be able to search for the synced content and otherwise manage it in Shelf KMS.

To set the mentioned collection permissions, go back to the Admin Panel where find and select the User Groups option in the left sidebar menu. Select the needed user group from the list to open it.

Figure 19. Accessing User Groups in Shelf

In the selected user group window that opens, go and select the Collection Permissions tab. Once it opens, click the Add Collection button.

Figure 20. Starting to set Contentful collection permissions in Shelf

In the form that opens, find and select the needed Contentful collections you want to allow.

Figure 21. Selecting Contentful collections

Confirm your choice by clicking the Add button. Once the collections are added, they appear in the list.

Figure 22. Viewing the added Contentful collections

Once done, you are finished with all the configurations needed to sync content from Contentful into Shelf KMS using the Contentful connector.

As mentioned in the Configuring Contentful connection profile section above, the Preview URL parameter in the Connection Profile settings allows viewing Contentful articles on other platforms, even when such articles are synced to Shelf KMS via Contentful Connector.

To make it possible, we need to adapt the Preview URL template shown below to our needs.

Preview URL template: https://[YOUR_PREVIEW_DOMAIN]/[PLACEHOLDER_TOKEN]

In this template,

YOUR_PREVIEW_DOMAIN - is the base path of your preview platform, website, or app (for example, https://ring.com/support/articles/), and

PLACEHOLDER_TOKEN - is a token that resolves into an actual value when you click on the preview link.

For better understanding, we take a real-world example, where you want to display your content on the Ring platform.

In Shelf, the template displayed above is transformed into the following one, which is then entered in the Preview URL field in the Contentful Connection Profile settings:

https://example.com/{entry.fields.HelpId}/{entry.fields.slug} (generic)

https://ring.com/support/articles/{entry.fields.ringHelpId}/{entry.fields.slug} (Ring-specific)

where

https://ring.com/support/articles is YOUR_PREVIEW_DOMAIN

{entry.fields.ringHelpId} is an additional parameter of the Ring platform that points Contentful and Shelf at the specific section of the Ring Help Knowledge Base, and

{entry.fields.slug} is the article name on Ring.

Figure 28. Indicating Preview URL to enable the article display on Ring

URL of the article we expect to see is https://ring.com/support/articles/qzhz4/how-to-reconnect-your-video-doorbell-or-security-camera-to-wifi

Figure 29. Viewing the article on Ring and understanding the article’s URL 

Once you created the Contentful connection profile, you can go back to our Contentful space and make the appropriate configurations there.

To enable Contentful to redirect us to our external platform (Ring) for viewing the needed content, you need to follow these steps.

1. Once in your Contentful space, go to the Content tab.

2. Then, click Add entry in the right corner of the window.

3. In the menu that expands, select the Article - Global option.

Figure 30. Creating an article (Article - Global) in Contentful space

4. On the article page that opens, fill in the needed fields such as the article title and others as required.

5. Scroll down the page and find the Ring Help Id and Slug fields. Enter their respective values as explained above.

Figure 31. Adding Preview URL configurations in Contentful

Once done, click Publish to publish your article in Contentful.

Figure 32. Publishing article in Contentful

Now we need to create a dedicated sync flow to sync the article we want to see. Follow the steps displayed in the respective section above, but choose the Connection Profile where the Preview URL value has been added.

Figure 33. Creating dedicated Sync Flow in Shelf 

Figure 34. Running Sync Flow job

Figure 35. Viewing Sync Flow job status

Following that, add the needed permissions to the Contentful collection(s) via Shelf’s User Group feature as described in the relevant section above.

Once all the above configurations are made, go to your Shelf KMS homepage, select Contentful as the needed source, and look for the needed article in the synced content.

Figure 36. Selecting Contentful as content source in Shelf

Figure 37. Searching for the needed article in the synced content

After the article is found, click it to open. If everything is configured properly, the article will open in the specified external platform, in our case - on www.ring.com.

Figure 38. Viewing the synced Contentful article on Ring

❗Note:

If you want to change the way the Preview URL is created in the future, you will need to set up a new connection profile with the updated value and sync your content again.