Contentful Integration

iContentForge seamlessly connects to your Contentful space, allowing you to automatically publish AI-generated articles as entries in your specified content model. This guide walks you through the setup process, from finding your credentials to configuring the field mapping.

Prerequisites

Before you begin, ensure you have:

An active iContentForge project with articles in the Ready status.
Editor or Admin access to the target Contentful space and environment.
Knowledge of the Content Type (model) you wish to publish articles to.

Recommended: The Official Zero-Config Template

If you aren't sure how to configure a Content Type or are running into mapping issues, you can instantly import our perfect schema. This guarantees 100% compatibility and zero manual mapping.

Download contentful-icontentforge-model.json
In your Contentful dashboard, use the Contentful CLI to import the model: contentful space import --content-model-only --config contentful-icontentforge-model.json
Use the Content Type ID icfPost in your iContentForge settings. Everything will map automatically!

Step 1: Gather Your Contentful Credentials

To connect, iContentForge requires four key pieces of information from your Contentful workspace.

1. Space ID

Your Space ID is a unique identifier for your Contentful project.

Log in to your Contentful dashboard.
Navigate to Settings > General Settings.
Your Space ID is displayed at the top of the page.

2. Environment

This is typically master for the primary environment, but you can select any environment you have access to (e.g., staging, production).

3. Content Management API (CMA) Access Token

This token grants iContentForge permission to create and publish entries in your space.

In Contentful, go to Settings > API keys.
Click Add API key.
Select the Content management tokens tab.
Click Generate personal token.
Give it a descriptive name (e.g., "iContentForge Auto-Publish").
Copy the generated token immediately. You will not be able to see it again.

鈿狅笍

Security Note: Treat your CMA token like a password. Store it securely. In iContentForge, it is encrypted. If the token is compromised, revoke it immediately in Contentful and generate a new one.

4. Content Type ID

This is the API identifier for the content model (e.g., blogPost, article) where your articles will be created.

In Contentful, go to Content Model.
Click on the content type you want to use.
The Content Type ID is listed in the main panel, separate from its display name.

鈩癸笍

How we explicitly target your blogs (Schema Isolation): Contentful stores all of your website's elements (e.g., Pages, Products, Menus, Articles) inside the same Space. To prevent iContentForge from messing up your other pages, we enforce strict routing using the Content Type ID. When you provide the ID exclusively for your blog posts (like blogPost), our system will only ever create entries tagged with that specific model ID. Contentful automatically silos these new entries into your blog section, ensuring your landing pages and other models remain totally secure and untouched.

Step 2: Connect in iContentForge

In your iContentForge project, go to the CMS section.
Click Add CMS and select Contentful from the list.
Enter the four credentials you collected in the previous step.
Click Test Connection. A success message confirms your credentials are valid and iContentForge can access your space.

Step 3: Configure Field Mapping

After a successful connection, you must map the article data from iContentForge to the fields in your Contentful content type. This tells the system where to put the title, body, slug, etc.

In the connection settings, locate the Field Mapping section.
You will see a list of standard iContentForge article properties (e.g., title, content, slug, excerpt, featuredImageUrl, author, publishDate).
For each property, select the corresponding Field ID from your Contentful content type from the dropdown menu.

馃挕

Mapping Tips:

content: Map this to your main rich-text field (e.g., body, postBody). Note that iContentForge stores content as Markdown/plain text map it to a Long Text or Rich Text field.
slug: Map this to your URL slug field. iContentForge will generate an SEO-friendly slug from the title.
featuredImageUrl: Map to a Short Text field that stores the image URL, or configure a linked asset field.
publishDate: Map this to a date/time field if you want to control the entry's publication date within Contentful.

Once all desired fields are mapped, click Save Configuration.

How Publishing Works

Status Flow: An article moves from ready to queued when it's next in line for your configured Drip Feed schedule.
Creation: iContentForge uses the CMA token to create a new entry in your specified Contentful space, environment, and content type.
Asset Handling: If a featuredImageUrl is mapped and an image is present, iContentForge will create an asset, process it, and link it to the entry.
Publication: If Auto-Publish is enabled in your connector settings, iContentForge will immediately publish the entry using the Contentful CMA publish endpoint. This requires the current entry version number, which iContentForge reads automatically from the creation response (sys.version).
Final Status: In iContentForge, the article's status updates to published. The new Contentful entry ID is stored for reference.

鈩癸笍

Drip Feed Publishing: If enabled, iContentForge will automatically publish ready articles from the queue to your connected CMS approximately every 5 minutes, ensuring a steady, natural flow of content.

鈿狅笍

Auto-Publish Note: The Contentful publish step (PUT /entries/{id}/published) requires your CMA token to have Publish permissions. If the auto-publish step fails (e.g., due to insufficient token permissions), the entry will still be created as a Draft in Contentful it will not be lost. You can then manually publish it from the Contentful dashboard, or regenerate a token with the correct permissions and retry.

Troubleshooting

Issue	Likely Cause	Solution
"Test Connection Failed"	Invalid Space ID, Environment, or CMA Token.	Double-check each credential. Ensure the CMA token has not expired or been revoked.
"Field Mapping Error" on publish	Mapped Field ID does not exist or is the wrong field type.	Verify the Field IDs in your Contentful content model. Ensure `content` maps to a Long Text or Rich Text field.
Entry created as Draft, not published	CMA Token lacks Publish permission, or Auto-Publish is disabled.	Check your connector settings to enable Auto-Publish. When generating the CMA token, ensure it has permission to publish entries.
Auto-Publish fails with 409 Conflict	Version mismatch (internal issue, should be handled automatically).	Contact support. iContentForge reads the `sys.version` from the create response automatically, but the entry has been created as a draft and is recoverable from Contentful.
Image fails to upload	Asset field constraints or processing timeout.	Check that the target asset field in Contentful accepts the image MIME type (e.g., `image/jpeg`, `image/png`).

Next Steps

Learn how to manage your publishing queue with Drip Feed Settings.
Understand the complete Article Generation Workflow.
Explore other available CMS Integrations.