Introduction

There is frequently a need to transfer articles into the Cortex platform from another content management system. For this purpose, Cortex provides a set of management endpoints to facilitate the import/export process.

Although the export/import process is principally the same in every case, there are likely to be critical differences in the detail that depend upon the current CMS environment and the composition of the source article.

This document provides an overview of the processes that your migration scripts will need to run and identifies the necessary management endpoints.

The content migration process

In general, the process is as follows:

1. Create a Cortex account specifically for content migration purposes, and use Role Manager to assign appropriate permissions to create articles.
2. Export (post) media to the media API.
3. Export (post) localisations to the localisations API.
4. Export (post) categories to the categories API.
5. Export (post) article content to the articles API.
6. Refine the article content and settings within Cortex as required.

Management APIs

Management endpoints are provided by Cortex to facilitate the transfer of resources, such as media and content, without the involvement of Cortex technical support. Indeed, a ‘bot’ account can be set up to automate updates to Cortex content with no technical staff involvement from either the server-side or the client-side. More on this shortly.

This section details the steps required for a developer to create an article in the Cortex platform using the management APIs.

Account creation

The management APIs require both authentication and the necessary roles to be assigned to gain access. This can be achieved in Role Manager within the Cortex platform.

Using the account that has the appropriate Cortex access, you must then acquire an authentication token from the Cortex OAuth 2.0 service, using the following request criteria:

curl --location '<BASE_URL>/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'client_id=BRIDGE' \
  --data-urlencode 'username=<USERNAME>' \
  --data-urlencode 'password=<PASSWORD>' \
  --data-urlencode 'deviceId=b8786ea5-4ec9-4e1c-8a68-7d34a610e118'

Note that the request for an authentication token for use with the management endpoints must designate the Cortex client ID: client_id=BRIDGE. Interactions with the management endpoints are only available to accounts registered to this Cortex client ID. You will have a separate client ID to identify your organisation's more general transactions.

⚠️

You are strongly advised to create a dedicated user account for automation purposes, and to ensure this account is granted appropriately restricted access to the Cortex platform.

It is important you set the correct roles for fetching and creating articles, media, categories and localisations, depending on your requirements.

Note that you can grant roles to a bot account via the Role Manager section of Cortex. The role groups Content (Admin) and Media are likely to include all of the roles you need.

🤖

A bot account is a dedicated user account specifically created for the purpose of automation. This account is designed to interact programmatically with the API, performing tasks and retrieving information without direct human intervention.

If the user has the appropriate roles assigned in role manager, then the access_token provided in the response allows authentication for management API requests within Cortex. From this point, requests can be authorised using an Authorization: Bearer token header.

The token will periodically expire based on the specified expiration in the JSON Web Token’s (JWT) exp claim. To renew it, use the refresh_token call (also provided in the response) through the following request:

curl --location '<BASE_URL>/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=BRIDGE' \
  --data-urlencode 'refresh_token=<REFRESH_TOKEN>'

Creating Articles

To create an article, the composition of your post to the management endpoint is as follows:

POST {environment-id}/v1/admin/{clientId}/articles?

In which:

{environment-id} is one of the following, depending on which environment you are using.

• Production (standard): https://article-cms.cortextech.io
• Production (USA): https://article-cms.cortextech.us

{clientId} is your organisation's Client ID, assigned during the onboarding process.

There are many potential fields and values that could be posted. For details, please refer to JSON response table for articles and pages

Uploading Media

Images, videos and other media can be hosted on Cortex's media Content Delivery Network (CDN). To send media to Cortex, the composition of your post to the management endpoint is as follows:

POST {environment-id}/v1/admin/{clientId}/media?

In which:

{environment-id} is one of the following, depending on which environment you are using.

• Production (standard): https://media.cortextech.io
• Production (USA): https://media.cortextech.us

{clientId} is your organisation's Client ID, assigned during the onboarding process.

For detail on the individual fields and values that can be posted, please refer to API call specifications for media.

Categories

Categories and tags are the main fields used to identify and filter articles and pages. While tags are free-form text and are created within each instance of content, categories are set up only once for all of a client’s content. Once set, categories are then selected from a drop-down list within each article or page when it is created.

Categories are therefore unique within the client context and can be reliably used, for example, as a flag for automating display criteria (such as changing the background colours) or in the creation of a unique URL. Tags are less reliable in this way, because they are free-text and might be unwittingly duplicated across articles and should not be used for such purposes

Creating a category

To post a category to Cortex, the composition of your post to the management endpoint is as follows:

POST {environment-id}/v1/admin/{clientId}/categories?

In which:

{environment-id} is one of the following, depending on which environment you are using.

• Production (standard): https://article-cms.cortextech.io
• Production (USA): https://article-cms.cortextech.us

{clientId} is your organisation's Client ID, assigned during the onboarding process.

There are many individual keys and values that can be posted. For details, please refer to Content categories for articles and pages.

Localisations

If you wish to produce articles in multiple languages, Cortex provides support for you to manage the relationships between them. Note that we do not provide linguistic or translation services. It is your responsibility to produce the multilingual content and each version of the article is treated as an item of content entirely in its own right. The localisations parameter allows you to add locales - various languages - to your client account. You can then use these to add different language versions to a single article ID to logically link the related content. The API POST call to add a locale to your client ID is as follows:

POST {environment-id}/v1/admin/{clientId}/locales?localeId={{"languageName": "languageName","languageTag:{"languageTag"}}

In which:

{environment-id} is one of the following, depending on which environment you are using.

• Production (standard): https://article-cms.cortextech.io
• Production (USA): https://article-cms.cortextech.us

{clientId} is your organisation's Client ID, assigned during the onboarding process.

{languageName} is the localisation you wish to add as a language option for your articles, and
{languageTag} is the identifier for that localisation, using The BCP 47 Standard for Language Tags. Together, they are formatted like this:

{
  "name": "English (United Kingdom)",
  "languageTag": "en-GB"
}

These fields are required.

For more on locales and the structure of related API calls, please refer to Localisation for articles and pages.