Docs/CMS Integrations/Contentful Integration

Contentful Integration

CMS Integrations
5 min read

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.

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.

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

Location of Space ID in Contentful General Settings

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.

  1. In Contentful, go to Settings > API keys.
  2. Click Add API key.
  3. Select the Content management tokens tab.
  4. Click Generate personal token.
  5. Give it a descriptive name (e.g., "iContentForge Auto-Publish").
  6. 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.

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

Location of Content Type ID on a Contentful model page

Step 2: Connect in iContentForge

  1. In your iContentForge project, go to the CMS section.
  2. Click Add CMS and select Contentful from the list.
  3. Enter the four credentials you collected in the previous step.
  4. 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.

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

iContentForge field mapping interface showing dropdowns for Contentful Field IDs

💡

Mapping Tips:

  • content: Map this to your main rich-text field (e.g., body, postBody).
  • slug: Map this to your URL slug field. iContentForge will generate an SEO-friendly slug from the title.
  • featuredImageUrl: Ensure your target field in Contentful accepts a single image. iContentForge will upload the image asset, create an entry, and link it.
  • publishDate: Map this to a date/time field if you want to control the entry's publication date within Contentful.
  1. Once all desired fields are mapped, click Save Configuration.

How Publishing Works

  1. Status Flow: An article moves from ready to queued when it's next in line for your configured Drip Feed schedule.
  2. Creation: iContentForge uses the CMA token to create a new entry in your specified Contentful space, environment, and content type.
  3. 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.
  4. Publication: The entry is saved and then published via the CMA, making it available through your Contentful Delivery API.
  5. 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.

Troubleshooting

IssueLikely CauseSolution
"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 publishMapped 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 rich-text field, for example.
Entry created but not publishedInsufficient permissions on the CMA token.When generating the token, ensure it has permissions to publish entries/manage content.
Image fails to uploadAsset 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

Previous
Strapi
Next
Sanity.io
Edit this page on GitHub
Contentful Integration — iContentForge Docs | iContentForge