CONTENTSTACK CMS Connector API Contentful

• Produktas: CMS Connector API – Contentful
• Aprašymas: The migration-contentful package simplifies the process of migrating data from Contentful to Contentstack CMS by providing utility functions for extracting content types, mapping fields, and handling locales.

CMS Connector API – Contentful
This document outlines the functionalities and usage of the migration-contentful package, which is designed to simplify the process of migrating data from Contentful to Contentstack CMS. It provides key utility functions for extracting content types, mapping fields, and handling locales, ensuring a smooth and efficient migration process. The following sections detail the installation, available functions, and their specific behaviors.
migration-contentful Package

Baigėsiview

The migration-contentful package is used to simplify the process of migrating data from Contentful to Contentstack CMS. It helps with extracting content types, mapping fields, and handling locales. This package contains key utility functions to facilitate these tasks.

Montavimas

In your package.json, you reference this package from your local file system like this:

• JavaScript
• “dependencies”: {
• “migration-contentful”: “file:migration-contentful”
• }

This makes the migration-contentful package available locally without the need to fetch it from an external registry like npm.

Pagrindinės funkcijos

You can import the following functions from the package to use in your project:

1. extractContentTypes:
   • This function extracts content types from the exported Contentful data and saves them locally.
   • It processes the data to create a structured format that can be used for migration to another CMS. const { extractContentTypes } = require(‘migration-contentful’);
2. createInitialMapper:
   • Once the content types are extracted, this function transforms them into a mapping schema. This schema helps in migrating the data by ensuring fields are mapped correctly between systems. const { createInitialMapper } = require(‘migration-contentful’);
3. extractLocale:
   • This function extracts locale information (languages and region data) from Contentful exports. This is crucial for migrating content with language variations to the new CMS. const { extractLocale } = require(‘migration-contentful’);

Kaip naudoti

To use the functions in your code, simply import them like this:

• JavaScript
• const { extractContentTypes, createInitialMapper, extractLocale } = require(‘migration-contentful’);

These functions will allow you to:

• Extract content types from a Contentful export.
• Create a field mapping based on the extracted data.
• Extract and manage locales for migrating language data

extractContentTypes Function

Baigėsiview
This module provides utilities to extract and save Contentful content type definitions along with their associated editor interfaces. The data is processed and saved as structured JSON files for use in CMS migration or synchronization pipelines.

Funkcija: extractContentTypes(filePath, prefix)

Aprašymas

• Jei turite klausimų, kreipkitės į tso-migration@contentstack.com.
• Skaito a file containing Contentful content types and editor interfaces, processes them, and saves each content type in a structured format.

Parametrai:

• fileKelias (string): Path to the file containing the exported Contentful content model.
• priešdėlis (string): Prefix to namespace or label the saved field definitions.

Grąžinimai:

Promise<void>: Resolves when content types are successfully processed and saved.

Elgesys:

1. Checks if the folder at contentfulFolderPath exists. If not, it creates it.
2. Reads the input file and extracts contentTypes and editorInterfaces.
3. If contentTypes exist, it delegates processing to saveContentType(). Otherwise, it logs “No content-type found”.

Throws:
Logs and throws an error if reading the file or saving data fails.

Funkcija: saveContentType(contentTypes, editorInterface, prefix)

Aprašymas:
Processes each content type and its fields by matching them with their respective editor controls and saves the data to JSON files.

Parametrai:

• contentTypes (Array<Object>): Array of content type definitions.
• editorInterface (Array<Object>): Array of editor configurations for fields.
• prefix (string): Used to label field data.

Grąžinimai:

void: This function writes files and does not return anything.

Elgesys:

1. Converts the sys.id of each content type into snake_case.
2. Finds the matching editor interface by comparing content type IDs.
3. Merges field definitions with their widget/editor info.
4. Saves each content type as a prettified .json file in the target folder.

Išvestis File

Each content type gets its own .json file named after its cleaned-up title (special characters removed, first letter capitalized).

Output Format (per field):
Each saved JSON array contains objects with the following keys:

• priešdėlis
• contentUid
• contentDescription
• contentfulID
• id, name, type, localized, required, validations, disabled, omitted (from field definition)
• widgetId (from editor interface)
• contentNames (list of all content type IDs)

createInitialMapper Function

Baigėsiview

• The createInitialMapper function reads content model data exported from Contentful, transforms each model into a Contentstack-compatible schema format, and returns a complete mapping of content types.
• It is typically used during CMS migrations or synchronization processes between Contentful and Contentstack.

Funkcijos parašas

• JavaScript
• const createInitialMapper = async () => { … }

Įėjimai
None were directly passed.

Skaito files iš:

• JavaScript
• path.resolve(process.cwd(), `${config.data}/${config.contentful.contentful}`)
• where each file contains field definitions for a Contentful content type.

Išvestis
An object in the following structure:

• JavaScript
• contentTypes: [ … ] // array of content type mapping objects

Each contentType object contains:

Laukas	Tipas	Aprašymas
statusą	numerį	Indicates active state (1 = active)
isUpdated	loginis	Whether the mapping was updated
updateAt	styga	Laikuamp (left blank initially)
otherCmsTitle	styga	Content type title from Contentful
otherCmsUid	styga	UID from Contentful (contentfulID)
contentstackTitle	styga	Transformed title for Contentstack (Capitalized)
contentstackUid	styga	UID for Contentstack, corrected with uidCorrector()
tipo	styga	Always ‘content_type’

fieldMapping

masyvas

An array of field definitions, including system laukus

Vidinė logika

Skaityti Files

• JavaScript
• konst files = await fs.readdir(…);

Gets all JSON files representing Contentful content types.

Iterate Files

• JavaScript
• for (const file of files) { … }

Kiekvienam file:

• Reads field definitions
• Derives content type title from filepavadinimas

Build Schema Object
Each object includes:

• Metadata about the content type
• Default fields (title and url) added manually
• Custom fields generated via contentTypeMapper()

Generate Fields

• JavaScript
• const contentstackFields = […uidTitle, …contentTypeMapper(data)].filter(Boolean);
• uidTitle: Hardcoded default fields for title and url
• contentTypeMapper(data): Dynamically maps Contentful fields to Contentstack schema

Delete Temporary Folder

• deleteFolderSync(path.resolve(…));
• Removes the data folder after processing to avoid re-use or conflicts.

Grąžinimo rezultatas
Returns the final list of mapped content types for further use.

Klaidų tvarkymas

Any error during file reading, transformation, or folder deletion is caught and logged: js

CopyEdit
console.error(‘Error saving content type:’, error);

Example Return

• JavaScript
• “contentTypes”: [
• “status”: 1,
• “isUpdated”: false,
• “updateAt”: “”,
• “otherCmsTitle”: “blogPost”,
• “otherCmsUid”: “blogPostID”,
• “contentstackTitle”: “BlogPost”, “contentstackUid”: “blog_post”, “type”: “content_type”,
• “fieldMapping”: [
• “uid”: “title”,
• “contentstackFieldType”: “text”, …
• },
• …

Related Functions

• contentTypeMapper: Converts each Contentful field to Contentstack schema.
• uidCorrector: Normalizes field UIDs.
• extractAdvancedFields: Injects metadata (e.g., mandatory, unique).
• deleteFolderSync: Cleans up local temporary directories.

contentTypeMapper Function

Baigėsiview
The contentTypeMapper function is a comprehensive mapping utility that transforms a content model structure (typically from a CMS like Contentful) into a schema array suitable for another CMS (like Contentstack). Here’s a breakdown of how it works and what each section does — suitable for use in developer documentation:

Function Purpose
The contentTypeMapper function takes an array of content field definitions (data) and returns a normalized array of schema objects formatted for Contentstack. It supports various field types, widget configurations, and advanced metadata.

Funkcijos parašas

• JavaScript
• const contentTypeMapper = (data) => { … };
• Įvestis: data – An array of field definition objects, typically exported from a CMS source.
• Išvestis: schemaArray – An array of transformed field objects structured for Contentstack.

Core Logic (How it Works)

Iterate Through Input Data

• data.reduce((acc, item) => { … }, []);
• Each field (item) in the data array is processed based on its type and widgetId.
• Jei turite klausimų, kreipkitės į tso-migration@contentstack.com.

Handle Different Field Types

• Turiningas tekstas
  • Calls arrangeRte to resolve references.
  • Uses createFieldObject with json type.
• Symbol, Text
  • Handles widgets like singleLine, urlEditor, slugEditor, multipleLine, markdown, dropdown, radio, tagEditor, and listInput.
• Number, Integer
  • Maps editors to number, or re-maps to dropdownNumber, radioNumber, etc.
• Data
  • Mapped directly to isodate.
• Array, Link
  • Assets (Images, Files): Mapped to file, with .multiple = true if it’s an array.
  • Entries (References):
  • Parses linkContentType from validations.
  • Derives references (referenceFields) using helper logic.
  • Uses createFieldObject with reference type.
  • Žymimasis langelis, Tag Editor, List Input: Mapped appropriately.
• Būlio
  • Mapped to boolean.
• Objektas
  • If widgetId is an objectEditor, marked as app type.
  • Otherwise, enriches the name using app metadata from appDetails.
• Vieta
  Creates a group field plus subfields for lat and lon.

Helper Function: createFieldObject
This standardizes the schema field output:

• JavaScript
• {
• uid,
• otherCmsField
• otherCmsType,
• contentstackField,
• contentstackFieldUid,
• contentstackFieldType,
• backupFieldType,
• backupFieldUid,
• pažengęs

Where advanced comes from extractAdvancedFields, providing details like:

• privalomas
• unikalus
• nonLocalizable
• referenceFields (when applicable)

Special Logic

• uidCorrector() is used to standardize IDs for compatibility.
• Conditional checks on item.items, validations, and widgetId ensure the mapper handles deeply nested or loosely structured fields gracefully.
• References are deduplicated and capped for performance (slice(0, 9) or length < 25).

Console Logging
For widgets like tagEditor or listInput, a console.info() is called — likely for debugging purposes.

Santrauka
This function is critical in migrating or transforming content model definitions from one CMS to another. It ensures:

• Widget-specific logic is respected
• Reference relationships are preserved
• Fields are enriched with necessary metadata
• Complex widgets like Location, Object, and Reference are handled correctly

extractLocale Function

Aprašymas
This function extracts unique locale codes (e.g., en-us, fr-fr) from a Contentful JSON export and returns them in an array. These locale codes are later pushed to the database via a backend API to support localization in a new CMS like Contentstack.

Priklausomybės

• jsonFileKelias: Path to the exported JSON file from Contentful.
• fs (Node.js built-in): Used to read the file turinį.

Function: extractLocale

Tikslas

• Extracts and returns a list of unique locale codes used in the legacy CMS. Parameters
• jsonFilePath (string) – File path to the exported Contentful data (JSON format).

Grąžina
Array<string> – A list of unique locale codes.

ExampLe:

• JavaScript
• [‘en-us’, ‘fr-fr’]
• Returns an empty array [] if:
  • No locales are found.
  • The file is missing or invalid.

Elgesys

• Patvirtina file path and JSON structure.
• Parses the JSON and extracts values from the locales array.
• Collects unique locale codes (locale.code).
• Handles and logs errors gracefully.

Example Naudojimas

• JavaScript
• const extractLocale = require(‘./libs/extractLocale’);
• (async () => {
• const locales = await extractLocale(‘./legacy-export.json’); console.log(‘Locales found:’, locales);
• })();

Validator Contentful

Baigėsiview
The Contentful Validator verifies that a JSON content model exported from Contentful contains all required properties as defined in a configuration schema (contentful.json). It is used as a pre-validation step before transforming or migrating content models into another CMS like Contentstack.

Function: contentfulValidator(data: string)

Aprašymas:
Validates a raw JSON string exported from Contentful against a required schema definition provided in contentful.json.

Parametrai:  data (string): Raw JSON content model as a string (from Contentful)

Grąžinimai:

• true if:
  All required properties listed in the config are present in the parsed JSON object.
• false if:
  Any required property is missing.
• The JSON is malformed or cannot be parsed.

Vidinė logika

1. Parse the JSON input
   • JavaScript
   • jsonData = JSON.parse(data);
     1. Attempts to parse the input string into a valid JavaScript object.
     2. If parsing fails, the function returns false.
2. Iterate Over Config Schema
   • JavaScript
   • Object.values(jsonConfig).every((prop: any) => { … });
     1. Loops through each field defined in the contentful.json schema.
3. Validate Each Property
   • JavaScript
   • if (jsonData?.hasOwnProperty(prop?.name)) {
   • grįžti tiesa;
   • }
   • else if (prop?.required === ‘true’) {
   • return false;
   • }
   • grįžti tiesa;
     1. Checks if the required properties exist in the parsed jsonData.
     2. If a required property is missing, the function short-circuits and returns false.
4. Klaidų tvarkymas
   JavaScript
   try { … } catch (error) {
   return false;
   1. The function handles all parsing or runtime errors.
   2. If parsing fails or unexpected data structures are encountered, false is returned without throwing.

Example Naudojimas

• JavaScript
• import contentfulValidator from ‘./validators/contentful-validator’;
• import fs from ‘fs’;
• const rawData = fs.readFileSync(‘contentful-export.json’, ‘utf-8’);
• if (contentfulValidator(rawData)) {
• console.log(‘✅ Contentful schema is valid!’);
• } dar {
• console.error(‘❌ Invalid schema: Missing required fields or bad JSON.’);

Running the upload-api Project on Any Operating System

• The following instructions will guide you in running the upload-api folder on any operating system, including Windows and macOS.
• Jei turite klausimų, kreipkitės į tso-migration@contentstack.com.

Starting the upload-api Project

• There are two methods to start the upload-api project: Method 1:
• Run the following command from the root directory of your project:
• Lukštas
• npm run upload
• This command will directly start the upload-api package.

2 būdas:
Navigate to the upload-api directory manually and run the development server:

• Lukštas
• cd upload-api
• npm run start

This approach starts the upload-api from within its own directory.

Restarting After Termination
If the project terminates unexpectedly, you can restart it by following the same steps outlined above. Choose either Method 1 or Method 2 to relaunch the service.

Apribojimai

1. Not handle the use case of deletion of existing destination stack in runtime
2. Content mapper module | existing stack | existing content type mapped | Modular blocks, taxonomy these fields can be matched with Single Line Textbox field
3. Content Type Migration Limitations in Test Stacks
   When migrating content types in a test stack, the handling of attached references depends on your organization’s reference limit:
   • Organizations with a reference limit of 50: Full data migration is supported if a content type has more than 10 references.
   • Organizations with a reference limit of 10: If a content type has more than 10 references, only the ‘title’ and ‘URL’ fields will be migrated.
4. Problema: Data migration may encounter unforeseen problems if the Contentful data contains duplicate UIDs.

Jei turite klausimų, kreipkitės į tso-migration@contentstack.com.

DUK

What is the purpose of the migration-contentful package?

The package simplifies data migration from Contentful to Contentstack CMS by providing utility functions for content extraction, field mapping, and locale handling.

How do I install the migration-contentful package?

You can reference the package in your package.json file to use it locally without fetching from an external registry.

What functions are available in the migration-contentful package?

Key functions include extractContentTypes, createInitialMapper, and extractLocale for content type extraction, mapping, and locale handling.

Dokumentai / Ištekliai

CONTENTSTACK CMS Connector API Contentful [pdfNaudotojo vadovas CMS Connector API Contentful, Connector API Contentful, API Contentful, Contentful

Nuorodos

• Vartotojo vadovas