Contentstack
Last updated
Last updated
The destination Contentstack connector allows content to be transformed from Motation any synced to Contentstack.
IDs in the ID map report for Contentstack uses the following convention.
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
Contentstack has both a and APIs. Access to the CMA API is required for the destination connector. The CDN can be used as well for some calls as it is more efficient for returning results. However, if tokens and URL is not set for the CDN, the CMA will be used.
Contentstack has two types of tokens, . The destination connector requires a management token. If a delivery token is provided, some calls will be made to the CDN.
Contentstack supports a single field referencing multiple different content types. System properties are required to fully map a reference field to multiple content types. The key ImpulseSync_Referenced_Content_Type_Mapping take a JSON object as a value to map source content types to destination content types.
i.e., If a source reference field references content from keywords and news but the destination field references new_keywords and articles you can add system properties to the field as follows.
and
This will map the reference to keywords to new_keywords and the reference to news to articles.
Best practice is to set a system property for every referenced content type that does not exactly match. (keywords to keywords does not need a system property map but keywords to news_keywords does even if no entries currently have a reference to that content type)
Note: when Contentstack is the source, you can simply use the nested JSON object.
and
When a reference/relationship field is created in the content through a manipulator (i.e., liquid field manipulator), you will need to add the following system property.
i.e.,
This will ensure the Contentstack destination's reference field will reference the content type configured in the system property.
This only supports a single content type to be referenced.
If you are creating a reference field that is nested in a group/global field you need to add the group/global field to the content using a manipulator. i.e., the add-replace manipulator.
This will allow the connector to set the value for the nested field appropriately in the group/global field.
This field also needs the field system type "global_field" or "group" as appropriate. The field type of the field is "System".
It is suggested that this manipulator be run before the manipulator to create the reference field runs.
An example of creating this field group/global field can be found below.
Contentstack's global and group fields require a system property to map a change in name between source and destination Contentstack stacks.
This can also allow you to map a source field that is not part of a global or group field into a destination group/global field.
A dot pathing notation is used to refer to a field inside a global or group field.
Example: Unique ID for field inside Global/Group
Example: Unique ID for field inside nested Global/Group
NOTE: When using the system property to set a global/group field the unique ID must not use dot pathing ('.' in the value). Instead, the Unique ID would only be the UID of the inner most field (i.e., inner_field_uid). This system property is not the recommend mapping. Instead use the Unique ID with dot pathing as explained above.
Be aware that field to add to the content mapping is the field inside the global or group field. Then add the system property to that field with the uid of the destination global or group field. Mapping the global or group field directly is not supported. Instead, map the inner fields of the over arching global or group field and add the system property for the destination global/group field uid.
Example: Global system property
Example: Group system property
Example: Nested Global/Group system property
When mapping from a source global or group field and the destination is not a global or group field you will need to perform two steps.
You will need to set the appropriate unique IDs.
The origin unique ID will include a dot pathing as stated above. And the destination will not include a dot pathing since there is no global/group field at the destination.
You will need to set a system property for global_field or group as an empty string.
Contentstack's Select field type allows for either Text or Number data type. The Text data type is the default behavior for syncing a Select value. However Number can be forced by adding a system property to the mapping for the field. This is not required when syncing between two Contentstack systems and both the source and destination field are Select with data type Number.
Example: Select Number data type
Contentstack modular block field is only supported when syncing from a source Contentstack system. To map the modular block field and it's inner fields system properties are required to be set in the content mapper for each field.
A modular block has a few parts:
The modular block field itself
The individual blocks of a modular block
The inner fields of each block
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.
Set fieldType to "System".
To map a change in UID of each individual block add a system property to the main modular block field created above.
If source modular block has a block with UID sub_menu and the destination modular block has a block with UID main_submenu set a system property as follows:
Add as many system properties as required for changed blocks to the modular block field in the content mapper.
To map a change in UID of an inner field add a new field to the content mapper. This field is separate from the previous modular block field.
This field should be mapped similar to a regular field, except the uniqueIds follow a "dot pathing" instead.
For instance, lets assume there is a modular block field menu_items and it has the block sub_menu with the field title. But the destination requires a map from title to headline. The following values should be used.
Origin Unique ID:
Mapping Unique ID:
This dot pathing also includes the UID of the global or group a field is part of. If the field title is in the group menu_group the Origin Unique ID would be as follows:
Without the proper origin unique ID, the mapping will not take effect. Be careful to use the correct unique ID value for modular block fields.
This inner field mapping can have system properties for mapping group and global fields in the same way a regular field would.
i.e., if menu_group should be mapped to sub_menu_group add the following value as a system property.
NOTE: Nested group and global fields within a modular block fields is unofficially supported. While it may work in select cases, it is likely that it will not work.
Folders that have non-alphanumeric characters in their name are not supported in Contentstack. As a result those folders will be renamed by removing the non-alphanumeric characters.
However, this will result in files in those folders to be synced to the incorrect location.
The recommended use case is to remove all non-alphanumeric characters from folder names before syncing.
To publish entries Contentstack requires an environment. When the job option environmentis set, a request will be made to publish entries to that environment. Be careful to populate all required fields when using the environment option. Otherwise, Contentstack will fail to publish the entry.
Contentstack allows for setting Key/Value pairs for the select field. The value to be used in the content is the "Value" set in Contentstack as the Key/Value pair. This specifically applies when using a Motator to adjust values. Without a valid select value set in the content, the content will not sync.
Only one asset will be created per Motation of type File.
A binary field will be automatically from the Motation of type File will be used as the binary of the asset.
Other than the binary field, Assets have the following fields in Motation that can be mapped to.
Title
Type: String
Unique Name: title
The title of the asset
Permanent URL
Type: String
Unique Name: permanent_url
The permanent url of the asset. This value will follow the rules for Contentstack uses for generating a permanent url with the value.
Content Type
Type: String
Unique Name: content_type
The content type or mime type of the asset
Description
Type: Textarea
Unique Name: description
The description for the asset
Tags
Type: Array
Unique Name: tags
The tags for an asset
Note: tags are not supported from other systems
To ignore a field you can set the mapping unique ID to a value that does not exist and will not exist in the destination Contentstack system.
i.e., You can set the value to completelyignoredvaluetoneverset as seen in the following example image.
This value set cannot exist in the destination Contentstack system during the time of the sync. Otherwise it would treat it like a regular mapping.
The value set should also not exist in the future for the destination Contentstack system. This may cause unexpected conflicts if the value used to ignore the mapping is later added as a field in the destination Contentstack system.
The URL field can be synced into by using the "String" field type in the content mapper. However be aware that Contentstack has special rules for the URL field that may alter the destination value. Be aware of what rules are set for the field in the content type to avoid any unexpected values.
Group/Global fields with the multiple property expect each instance of the nested fields explicitly set. Each instance is treated as an individual field in the content. Each field unique ID expects following string value appended --# .
i.e., {{group.field}}--0 , {{group.field}}--1 , {{group.field}}--2
All fields nested in the group/global field must be mapped. Any field not mapped will be ignored by default.
If syncing from Contentstack to Contentstack, only {{group.field}}--0 requires a mapping.
If syncing from Contentstack to Contentstack, the mapping.uniqueId must be {{old-group.old-field}}->{{new-group.new-field}}
If syncing from another system to Contentstack the appended number must start at 0, then iterate from there.
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.
Creating a link field in Contentstack destination requires being able to set multiple values to a field.
The first value of the field is the url of the link field while the second value of the field is the title of the link field.
The field type is System .
The field system type is link .
If the link field is multiple the url and title values are paired. Meaning every odd numbered value is the url of the link field, and every even numbered value is the title of the link field.
Additionally, the following system property must be set.
Setting a time zone is not supported. You must provide the time for the time zone the system uses.
When syncing folders, the connector will first check if the folder exists by ID. If it does not exist by ID, then it will check by name. If the folder does not exist by name, a new folder will be created.
If the folder does exist by ID or name , the folder will be updated. This can cause nested folders with the same name as a non nested folder to update the non-nested folder to become a nested folder. This may also cause assets that live in a folder with the same name, (but different paths at the source system) to be synced to the same folder.
Syncing content types. A content type should be created prior to a sync and the content mapper used to map incoming content to the existing content type.
Syncing global field content model. The values of entries using global fields are synced but the content model of the global field is not synced. Global fields should be created prior to a sync and the content mapper used to map into global fields as documented under Mapping Global and Group fields section.
Nested Group/Global fields within modular block fields.
Nested Modular Block fields.
Multiple value fields.
Proper folder hierarchy from other systems.
Tags and categories.
Syncing multiple file references to a single field (i.e., strapi multiple file field to Contentstack file field). Only the first file will be set as the value.
Modular block fields to non modular block fields. This is not officially supported and may have unintended side effects if it does sync.
authToken
The delivery token to use Contentstack's CDN API.
managementToken
The content management token to use Contentstack's CMA API.
branch
The branch to pickup content from.
apiKey
The API Key for the stack to pickup content from.
CMABaseURL
CDNBaseURL
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).
contentType
The content type to pickup content IDs from.
Text
No
No Default Value
branch
The branch to sync content to.
Text
No
No Default Value
environment
The environment to sync content to.
Text
No
No Default Value
apiKey
The API Key of the stack to sync content to.
Text
Yes
No Default Value
assetTitleAsID
Whether the asset title should be used as an identifier when syncing.
Boolean
No
false
query
Text
No
The value of the apiKey job option should match the API Key generated for the stack that content should be delivered into.
The value of the contentType job option should match the Content Type UID from Contentstack for the content type being checked/synced to.
The value of the branch job option should match the name of the branch content should be delivered to in the stack.
The value of the environment job option should match the name of the environment content should be delivered to in the stack.
When assetTitleAsID is set to true, the title of the asset will be used as an identifier when syncing the asset. Meaning if an asset already exists at the path with the same title, the existing asset will be updated and a new asset will not be created.
When assetTitleAsID is set to false, the title of the asset will not be used as an identifier when syncing the asset. Meaning if an asset already exists at the path with the same title, a new asset will be created with a duplicate title.
Note: When assetTitleAsID is set to false, due to the asynchrounous nature of Impulse, if multiple assets are synced with the same title and no asset exists in the destination with that title, there is a chance that multiple assets will be created at the destination with the same title.
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:
The base URL for CMA must be provided in the adapter properties. Base URL values can be found in Contentstack's documentation (, ). The CMA base URL should always be provided.
When a group or global field has the set in the content model in Contentstack, there are special rules to syncing and mapping these properties.
The to access Contentstack's CMA API.
The to access Contentstack's CDN API.
A json object with values to query content to pick up. Follow the for formatting and options. Only queries that are a value for the key "query" can be used.
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 for query values and options.
