CMS Connector API Guide
New CMS Connector API Guide
This document serves as a guide for extending the CMS Connector API to support new Content Management Systems (CMS) and file types. It outlines the process of creating new CMS packages, updating validator and mapper logic, and handling various file extensions and CMS configurations in the `/validator` route and `handleFileProcessing` function. The goal is to maintain a modular and CMS-agnostic architecture, allowing for seamless integration of different CMS platforms by following a structured approach for validation, processing, and data mapping.
Creating a Similar CMS Package
කැමති migration-contentful, migration-sitecore, migration-wordpress
To support a new CMS (e.g., Drupal), create a new package like this:
TypeScript
migration-drupal/
Inside it, implement the required structure:
TypeScript
// migration-drupal/index.js
කොන්ස්ට් validator = (data) => {
// Validate file format, structure, required fields
};කොන්ස්ට් උපුටා ගැනීමFiles = async (filePath) => {
// Unzip or parse content
};
If you have any questions, please reach out to tso-migration@contentstack.com.
කොන්ස්ට් contentTypes = {
// Drupal-specific content type definitions
};
කොන්ස්ට් reference = {
// Drupal-specific field references
};
කොන්ස්ට් extractLocales = (data) => {
// Return locale array
};
මොඩියුලය.exports = {
validator,
උපුටා ගැනීමFiles,
contentTypes,
යොමු,
extractLocales
};
Where It’s Plugged In
Once your package (e.g., migration-drupal) is ready:
1. Add it to package.json:
If you have any questions, please reach out to tso-migration@contentstack.com.
JSON
“migration-drupal”: "file:migration-drupal”
2. Update your validator logic:
TypeScript
කොන්ස්ට් { validator: drupalValidator } = අවශ්යයි(‘migration-drupal’);
මාරු කරන්න (CMSIdentifier) {
නඩුව ‘drupal-zip’:
ආපසු drupalValidator({ data });
}
3. Update createMapper logic and Add the case in createMapper switch::
TypeScript
නඩුව ‘drupal’:
ආපසු await createDrupalMapper(…);
✅ ශ්රේණිය සාරාංශය
To add a new CMS, simply:
- Scaffold a package like migration-drupal
- Follow the existing method structure
- Add it to validator and mapper switch blocks
This keeps the architecture modular and CMS-agnostic, all the explanations provided in subTabs.
If you have any questions, please reach out to tso-migration@contentstack.com.
validator Route
This route is used to validate and process a file (local or from AWS S3), based on file type and CMS configuration.
✅ ශ්රේණිය ක්රියාකාරීත්වය අවසන්view
- Accepts a GET request to /validator
- යන්න තීරණය කරයි file source is local or from S3
- මත පදනම්ව file දිගුව:
○ If XML → reads as string
○ Else (e.g., ZIP) → reads as binary buffer - Calls handle File Processing with file දත්ත
- On success, maps the processed file using create Mapper
Where to Add Support for New File වර්ග
In this route, file extensions are determined using:
JavaScript
කොන්ස්ට් fileExt = fileName?.split?.('.')?.pop() ?? ”;
Then based on file extension, logic is handled like this:
JavaScript
if (fileExt === ‘xml’) {
// Process XML as string
} වෙනත් {
// Process as buffer (e.g., zip)
}
If you want to add a new file type, you can add it inside this condition: If you have any questions, please reach out to tso-migration@contentstack.com.
JavaScript
if (fileExt === ‘xml’) {
//…
} else if (fileExt === ‘yourNewExtension’) {
// Add logic to read and handle this new file වර්ගය
} වෙනත් {
// Default processing for binary files
}
You may also need to extend handleFileProcessing to handle the new file වර්ගය.
Where to Add Support for New CMS Types
The cmsType is retrieved from:
const cmsType = config?.cmsType?.toLowerCase();
Later, this variable is passed to:
const data = await handle File Processing (file Ext, file Data, cms Type, name);
If you want to add a new CMS, you can extend logic inside handle File Processing or wherever you handle CMS-specific processing.
Also update:
createMapper(filePath, projectId, app_token, affix, config); To support your new CMS type, add logic to createMapper to handle it accordingly.
✅ ශ්රේණිය සාරාංශය
● You can add new file extensions by modifying the fileExt condition If you have any questions, please reach out to tso-migration@contentstack.com.
● You can add new CMS types by extending handleFileProcessing and createMapper
● The system already separates XML (string) and ZIP (buffer) handling — follow that structure
හසුරුවන්න File සැකසීම
This document explains how to integrate a new CMS platform into the existing file validation and processing flow using the functions:
● handleFileProcessing()
● validator()
අරමුණ
The backend currently supports multiple CMS types (like Sitecore, Contentful, WordPress, AEM). The goal is to validate uploaded files and transform them into a structured format specific to each CMS.
The system identifies a CMS + file type pair using this format:
type-extension → e.g., sitecore-zip, contentful-json, wordpress-xml
Where to Add a New CMS
Step 1: Update the validator () Function
Located inside:
JavaScript
කොන්ස්ට් validator = ({ data, type, extension }: { data: any; type: string; extension: string }) => { … }
Find the switch statement on CMSIdentifier. Each case handles one CMS-type and file-extension combination.
To add a new CMS, add a new case in this switch block:
Exampලෙ:
If you have any questions, please reach out to tso-migration@contentstack.com.
JavaScript
නඩුව ‘newcms-json’: {
ආපසු newCMSValidator(data); // Your new validation logic }
සහතික කරගන්න:
● CMSIdentifier format matches the expected {type}-{extension}
● The validation function (e.g., newCMSValidator) is imported or defined
You can add multiple variations, like:
case ‘newcms-zip’:
case ‘newcms-xml’:
Step 2: Create the Validator Function
In your project, define the validator logic for the new CMS. Exampලෙ:
JavaScript
කොන්ස්ට් newCMSValidator = (data) => {
// Your custom validation logic for JSON, ZIP, etc.
ආපසු true; // or false if validation fails
};
Input: This could be:
● A JSZip object (for zip)
● Raw XML string
● JSON object/string
Output: Boolean (true = valid, false = rejected)
If you have any questions, please reach out to tso-migration@contentstack.com.
Step 3: Test with handleFileProcessing()
The validator() function is used inside handleFileProcessing():
JavaScript
if (await validator({ data: zipBuffer, type: cmsType, extension: fileExt })) { //…
}
Make sure your new CMS validator is covered in the condition by passing the correct:
● cmsType (from config.cmsType)
● ● ශ්රව්ය දෘශ්යකරණය fileExt (from the uploaded file)
✅ ශ්රේණිය Summary Checklist
කාර්යය විස්තරය
Add new case Update validator() switch block
Implement logic Write your own newCMSValidator function
ආපසු
සත්ය/අසත්ය
Ensure validator returns a boolean
Use correct key Follow type-extension format (e.g., newcms-zip)
�� Optional: Debugging Tips
If you have any questions, please reach out to tso-migration@contentstack.com.
● Log the CMSIdentifier inside validator() to ensure your case is reached.
● Ensure handleFileProcessing is passing correct fileExt and cmsType.
Adding Mapper Support for a New CMS
After validating and processing a file, the backend prepares mapping data using the createMapper function. This step transforms the extracted content into a standardized format that can be used to generate dummy data and locale mappings in your CMS.
How Mapping Works (High-Level Flow)
1. ✅ ශ්රේණිය File is successfully validated and saved (ZIP, XML, JSON, etc.)
2. 
Path to the processed file is determined:
JavaScript
කොන්ස්ට් filePath = path.join(__dirname, ‘..’, ‘..’, ‘extracted_files', fileName);
3. The createMapper function is invoked:
JavaScript
createMapper(filePath, projectId, app_token, affix, config);
4. 
This function routes logic based on the CMS type (e.g., sitecore, contentful, wordpress)
createMapper Function – Structure
JavaScript
කොන්ස්ට් createMapper = අසමමුහුර්ත (
fileමාර්ගය,
projectId,
app_token,
If you have any questions, please reach out to tso-migration@contentstack.com.
affix,
config
) => {
කොන්ස්ට් CMSIdentifier = config?.cmsType?.toLowerCase();
මාරු කරන්න (CMSIdentifier) {
නඩුව ‘sitecore’:
return await createSitecoreMapper(filePath, projectId, app_token, affix, config);
නඩුව ‘contentful’:
return await createContentfulMapper(projectId, app_token, affix, config); නඩුව ‘wordpress’:
ආපසු createWordpressMapper(filePath, projectId, app_token, affix); පෙරනිමිය:
ආපසු false;
}
};
Each case corresponds to a CMS and calls its mapper function.
How to Add a New CMS
Step 1: Add Case in createMapper
Add a new case for your CMS identifier:
JavaScript
නඩුව ‘newcms’: {
return await createNewCMSMapper(filePath, projectId, app_token, affix, config);
If you have any questions, please reach out to tso-migration@contentstack.com.
}
Step 2: Create the Mapper Function
Implement a new function like:
JavaScript
කොන්ස්ට් createNewCMSMapper = අසමමුහුර්ත (filePath, projectId, app_token, affix, config) => {
// 1. Read and transform file අන්තර්ගතය
// 2. Generate field mapping object
// 3. Send to /v2/mapper/createDummyData
// 4. Generate locale mapping and call /v2/migration/localeMapper };
Step 3: Make Dummy Data API Call
Use axios like the existing implementation:
JavaScript
කොන්ස්ට් config = {
ක්රමය: ‘post’,
maxBodyLength: අනන්තය,
url:
`${process.env.NODE_BACKEND_API}/v2/mapper/createDummyData/${projectId}`, headers: {
app_token,
‘Content-Type’: ‘application/json’
},
දත්ත: JSON.stringify(fieldMapping),
If you have any questions, please reach out to tso-migration@contentstack.com.
};
කොන්ස්ට් { data } = await axios.request(config);
if (data?.data?.content_mapper?.දිග) {
deleteFolderSync(infoMap?.path);
logger.info(‘Validation success:’, {
status: HTTP_CODES?.OK,
message: HTTP_TEXTS?.MAPPER_SAVED,
});
}
පියවර 4: Handle Locale Mapping
If your CMS supports localization, add this or add en-us as default:
JavaScript
කොන්ස්ට් mapperConfig = {
ක්රමය: ‘post’,
maxBodyLength: අනන්තය,
url:
`${process.env.NODE_BACKEND_API}/v2/migration/localeMapper/${projectId}`, headers: {
app_token,
‘Content-Type’: ‘application/json’
},
දත්ත: {
If you have any questions, please reach out to tso-migration@contentstack.com.
ස්ථානය: අරාව.from(localeData) ?? []
}
};
await axios.request(mapperConfig);
ධාවනය කිරීම 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.
ආරම්භ කිරීම upload-api ව්යාපෘතිය
There are two methods to start the upload-api project:
ක්රමය 1:
Run the following command from the root directory of your project:
ෂෙල්
npm run upload
This command will directly start the upload-api පැකේජය.
ක්රමය 2:
වෙත සංචාලනය කරන්න upload-api directory manually and run the development server:
ෂෙල්
cd upload-api
npm run start
This approach starts the upload-api from within its own directory.
Restarting After Termination
If you have any questions, please reach out to tso-migration@contentstack.com.
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.
If you have any questions, please reach out to tso-migration@contentstack.com.
ලේඛන / සම්පත්
 |
CONTENTSTACK CMS Connector API Guide [pdf] පරිශීලක මාර්ගෝපදේශය CMS Connector API Guide, Connector API Guide, API Guide |