Home Pricing Contact Us

Contentstack

The source Contentstack connector allows content to be picked up from Contentstack, using API version 3, and transformed into motation.

Configuration walkthrough

Specifics

The source Contentstack connector is able to sync both content and files.

ID Map Report Convention

IDs in the ID map report for Contentstack uses the following convention.

<content-type-uid>::<content-uid>

Endpoint Config

When saving an endpoint for a Contentstack repository via REST intead of the UI you must use the following key:value pairs in the payload.

  • contentRepo:contentstack

  • contentRepoVersion:v3

CMA vs. CDN

Not all content data can be picked up using the CDN. (i.e., languages and folders) As such, it is required that CMA values be set. Both CMABaseURL and managementToken must be set in the adapter read properties.

However, when the CDN values (CDNBaseURL and authToken) are set and the CDN can be used to pickup that data, the CDN will be used.

Base URLs

The CMABaseURL and CDNBaseURL adapter properties should be one of the values found from Contentstack's documentation. (CMA, CDN) It is recommended that CMABaseURL always be set.

Duplicated Folder Names

When using folder name instead of folder UID, best practice is to have each folder uniquely named. Multiple folders with the same name are not supported for pickup. Only one folder would be picked up.

Mapping Global and Group fields

To map Global and Group fields the Origin Unique ID used following a dot pathing notation. This dot pathing is every global or group field UID and the inner most field UID.

Example: Unique ID for field inside Global/Group

"uniqueId": "global_group_uid.inner_field_uid"

Example: Unique ID for field inside nested Global/Group

"uniqueId": "global_group_uid.nested_global_group_uid.inner_field_uid"

Mapping Modular Block field

To map the modular block field simply add it to the content mapper as you would a regular field.

Map the origin.uniqueId and mapping.uniqueId as appropriate.

Syncing group/global fields with multiple property

When a group or global field has the multiple property set in the content model in Contentstack, there are special rules to syncing and mapping these properties.

Convention

For every field nested in the group/global field with the multiple property Impulse will recognize each instance of the nested fields for a content. There is a default maximum value of 20 instances. The job option multipleLimit can be used to increase the maximum number of instances. Any instance of a field greater than the limit will be ignored.

When multipleLimit is set, every field with the multiple property will use it as the maximum number of instances. Meaning you must set the highest value based on the content and field with the greatest number of instances.

Each instance is treated as an individual field in the content. Each field unique ID will append the following string value --# .

i.e., {{group.field}}--0 , {{group.field}}--1 , {{group.field}}--2

requirements

  1. All fields nested in the group/global field must be mapped. Any field not mapped will be ignored by default.

  2. If syncing from Contentstack to Contentstack, only {{group.field}}--0 requires a mapping. If syncing from Contentstack to another system, all {{group.field}}--# require a mapping.

  3. If syncing from Contentstack to Contentstack, the mapping.uniqueId must be {{old-group.old-field}}->{{new-group.new-field}}

  4. When selecting a field for a content manipulator, the exact field ID must be used. i.e., {{group.field}}--0 , and {{group.field}}--1

limitations

  • The string value -> cannot be part of the field unique ID.

  • The string value --# cannot be part of the field unique ID.

  • Only a single group/global field with the multiple property is supported. Nested group/global fields each with the multiple property are not supported.

Pickup Date time

Setting a time zone is not supported. You must provide the time for the time zone the system uses.

Gotchas

Branch/Environment Flag

Be aware of picking up content and assets with the environment or branch flag set. If the content or asset does not exist in the environment or branch, it will not be picked up. The connector often uses Contentstack's CMA, you can manually make a call with the appropriate environment/branch to check if the content/asset is returned.

Unsupported

Multiple value fields OTHER than group/global fields.

Nested group/global fields each with multiple property set.

Nested Modular Block fields.

Tags and categories.

Adapter Properties

PropertyPurpose

managementToken

The management token used to access Contentstack's CMA.

authToken

The authorization token used to access Contentstack's CDN.

branch

The branch to pickup content from.

apiKey

The API Key for the stack to pickup content from.

CMABaseURL

Base URL to access CMA.

CDNBaseURL

Base URL to access CDN.

rateLimitPerSecond

It is used to control the rate at which certain operations can be executed to prevent excessive usage or abuse of resources (default: 10).

Job Options

NameDescriptionData TypeRequiredDefault Value

contentType

The content type to pickup content from.

Text

false

No Default Value

environment

The environment to pickup content from.

Text

false

No Default Value

branch

The branch to pickup content from.

Text

true

No Default Value

apiKey

The API Key for the stack to pickup content from.

Text

true

No Default Value

folder

The folder to pickup assets from.

Text

false

No Default Value

multipleLimit

The max number of instances for all fields with the 'multiple' property.

Integer

false

20

query

A json object with values to query content to pick up. Follow the contentstack API doc on querying for formatting and options. Only queries that are a value for the key "query" can be used.

Text

false

No Default Value

Note: Either contentType OR folder is required. A job without either option is not supported.

apiKey Job Option

The value of the apiKey job option should match the API Key generated for the stack that content should be picked up from.

contentType Job Option

The value of the contentType job option should match the Content Type UID from Contentstack for the content type being checked/synced to.

contentType:restraunt

Picking up Assets from a Folder

Assets can be picked up directly by using the folder job option. You can get a folder by either setting the name of the folder or the UID of the folder. If you wanted to pick up content from the root folder simply use set folder option to "/".

Best practice would be to use the folder UID value since Contentstack allows for multiple folders with the same name. Since setting a file path is not a supported value, the folder UID can be used to pickup assets from any folder exactly.

This will only pickup the assets in the requested folder, this will not pick up nested folders and their assets.

Folder by Name Example:

folder:folder1

Folder by UID Example:

folder:blt33dea1872eb93635

Root Folder Example:

folder:/

branch Job Option

The value of the branch job option should match the name of the branch content should be delivered to in the stack.

branch:mybranch

environment Job Option

The value of the environment job option should match the name of the environment content should be delivered to in the stack.

environment:staging

query Job Option

The value to set is a JSON object with values that can be set for the "query" parameter key in a Contentstack CMA call. View this section of the Contentstack API doc for query values and options.

Because only options that are values of the "query" parameter are valid, queries such as pagination and include are not valid options.

example using regex:

{"title":{"$regex":"PROD"}}

Troubleshooting

PreviousContentfulNextdotCMS

Last updated