Knowledge Base

External Content Syncer

Last Modified:
14 Jan 2019
User Level:
Administrator

Description

The External Content Syncer is used to import and update content from an external data source like a database, XML file or even a CSV file. When content is synced, each row in the data source is added to TERMINALFOUR as a content item. Syncing can ensure that the link between the external data source persists. This means that updates made to content in the external data source are reflected in the synced content in TERMINALFOUR. Synced content can also be edited and amended in TERMINALFOUR.

For instance, if your staff profile information was stored on an external database, that content can be synced with TERMINALFOUR so it can be published on your website. The external database may not include photos but these can be managed directly within TERMINALFOUR.

Content edits are synced in one direction only – from the data source to TERMINALFOUR – so while synced content can be edited in TERMINALFOUR, those edits will not update content back in the data source. Edits to synced content in TERMINALFOUR will be overwritten by changes to content in the data source when the next sync occurs.

Before configuring the External Content Syncer you will need to set up the data source connection details in a Data Source.

Using the External Content Syncer

To use, go to Content > Integration Tools > External Content Syncer:

From this page you can:

This page does not become populated until Content Syncers are configured.

Configuring the External Content Syncer

Before configuring the External Content Syncer, you must set up a  Data Source to use.

Once a Data Source is has been set up, go to Content > Integration tools > External Content Syncer and click the Create new data store.

Screenshot of the Create New Data Store General Settings screen

There are two tabs here – General Information and Type Mapping:

General Information 

ItemDescription
Name Give your Data Store a name. It is recommended to make the name as descriptive as possible.
This is required.
Description This is used by the filter on the External Content Syncer listing and can be useful for finding Data Stores.
Data Source Select a Data Source to use. This must be already configured.
This is required.
Root Section Set the Section to import the content into via Browse or Search
This is required.
Channel Select the Channel to publish the imported content.
This is required.
Site Structure Creator

By default, either all content will be added to one Section, or a separate Section will be created for each Content Item, under the Root Section selected above. This depends on the option to Create individual Section for each piece of content below.

Using a custom Site Structure Creator plugin allows you to generate a custom Site Structure rather than using the default.

Leave it as Use default creator to use the default.

Section and content options
  • Create individual Section for each piece of content: Checkbox to create a separate Section for each Content Item imported. The Section name is the same as the name of the content item imported.
  • Cache each piece of content individually: Rebuilds the cache after each content item is imported rather than at the end of a sync. NOTE: Performance can degrade for large amounts of content.
Set imported language as Select the language into which content is imported. This is particularly important for multi-language websites.
Archive section Set the Section to move content to when it is no longer found in the external database. If left blank, content is not moved but is marked as Inactive.
Status of new content Choose from Approved, Pending, Inactive, or Draft. If set to Pending, this may allow users to review new content before it is published on the site. This only applies for new content; updates to existing content do not alter the content status i.e. if content is approved and then updated by the external content syncer, the content remains as approved.
Get external content via
  • Connection to database to get table: the content is all within one database table within the source database.
  • SQL Query: the syncer needs to us a SQL query to retrieve the content
Database table If Get external content via is Connection to database to get table, select the database table.
SQL Query If Get external content via is SQL Query, enter the SQL query that should be used to retrieve the content. 

Type Mapping

When syncing content, you must select the Content Type that the synced content will use. When a Content Type is selected from the drop-down list, the Content Type Elements will be listed on the left. To map, just input the Table column name from the external data source in the corresponding Type Element field:

Screenshot of the Type Mapping tab in the External Content Syncer

It is currently possible to sync into plain text, HTML, date, select box and radio button elements. For date elements the date format needs to be yyyy-MM-dd HH:mm:ss (e.g., 2018-03-31 23:59:59). When the elements are select box or radio button elements, the value in the database must match the list entry name (rather than the value).

While using multi-select lists may be possible, they are not currently officially supported. It may work in the following scenarios:

  • the value in the database must match the list entry name (rather than the value)
  • there is only one entry in the list (e.g., a list with one entry that is "Yes" that is a checkbox in the Content Type)

At least one of the elements or database fields should be selected as the Link. This should be the element that can uniquely identify the content item, and which may be used as a Primary Key in the external database. Examples could be a Staff ID or a Staff Email Address. If there is no one unique element, a combination of two can be used, meaning that the combination of the two elements will always be unique. This is used to match the TERMINALFOUR content item with the relevant record in the external database. It is worth noting that a unique element/field can be imported, and used internally as the Link, but not output by the Content Layout and not published with the content.

If connecting to a CSV file, refer to the article on Content Syncers with CSV files for information on the Table Column Names in CSV files.

Run a Sync

For each Data Store that is being updated, select the Sync Type and select Sync:

ItemDescription
Initial Sync Used on the first import. It creates a new Content Item for each entry in the database
Data Sync Refresh Refreshes content synced initially and updates with new content, if changed
Data Sync New & Refresh Creates new content for each new entry and updates content which has already been synced
Data Sync Old Status Compares the status of content on the database and changes the status of content already synced and marks as inactive if missing. It moves all inactive content to the Archive Section if specified in the configuration
Clean & Initial Sync Deletes all content and does Initial Sync

Schedule Sync

Click Schedule sync. A popup window appears with the following fields to be completed:

ItemDescription
Next due The starting day and time of the next sync.
Execution interval How often you wish this schedule to be run.
Data store The data store to sync.
Sync type The sync type you want to run in this schedule.
Email address The email address of the person(s) you want to be notified in case of a failure of the sync.

Click Confirm and the task is added to the Task Scheduler.

The most common sync that is needed is "Data Sync New and Refresh" and "Data Sync Old Status." To scheduled both of these, create two separate scheduled syncs, one of each type.

Active Syncs

After you confirm your schedule request, in the active syncs column, the sync you requested is shown:

You can choose several syncs for your content. This screen shows three syncs in the queue: