# Contentstack

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

## Configuration walkthrough

{% embed url="<https://drive.google.com/file/d/16_dxJ4dxLNkkConKiFVAyVusdmCEIrg9/view?usp=share_link>" %}

## 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](https://www.contentstack.com/docs/developers/apis/content-management-api/#base-url), [CDN](https://www.contentstack.com/docs/developers/apis/content-delivery-api/#base-url)) 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](https://www.contentstack.com/docs/developers/create-content-types/multiple/) 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

| Property           | Purpose                                                                                                                                    |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 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

| Name          | Description                                                                                                                                                                                                                                                                      | Data Type | Required | Default 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](https://www.contentstack.com/docs/developers/apis/content-delivery-api/#queries) 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](https://www.contentstack.com/docs/developers/apis/content-delivery-api/#queries) 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
