Payload CMS Connector

What You Get

Bidirectional sync:

• Push content from ILLIXIS to Payload
• Pull existing content from Payload to ILLIXIS
• Update existing articles without duplicates

Features:

• JWT authentication (email/password)
• Configurable field mapping
• Media upload handling (featured images)
• Bilingual content support (separate collections per language)
• Category management (auto-create missing categories)
• Sibling linking for translated content
• On-demand frontend revalidation

Powers these workflows:

• Publish articles from Content Hub to Payload
• Sync bilingual content (English + Spanish articles)
• Import existing articles for editing in ILLIXIS
• Schedule publishing to Payload CMS
• Connect landing pages and lead magnets to Payload

Setup Steps

1. Start the Connection

Go to Settings > Integrations > Content & CMS tab.

Click Add New Connector and select Payload CMS.

2. Enter Connection Details

Required fields:

Base URL: Your Payload CMS API endpoint (e.g., https://cms.example.com)

• Do NOT include /api in the base URL
• ILLIXIS adds API paths automatically

Email: Admin email for Payload CMS login Password: Admin password for Payload CMS login

Note: Payload uses JWT authentication. ILLIXIS logs in with these credentials and receives a JWT token for API requests.

3. Configure Collection Settings

Collection: The Payload collection to sync (default: articles)

• Most Payload sites use articles for blog posts
• Check your Payload admin to verify collection names

Field Mapping (optional customization):

• Title field: title (default)
• Content field: content (default)
• Slug field: slug (default)
• Status field: status (default)
• Excerpt field: excerpt (default)

Status values:

• Draft status: draft (default)
• Published status: published (default)

Leave these as defaults unless your Payload schema uses different field names.

4. Configure Category Settings

Category Mode:

• Relationship: Categories are stored as relationships (recommended for Payload 3.x)
• Select: Categories are stored as string slugs (legacy)

Relationship mode:

• ILLIXIS fetches categories from /api/categories
• Auto-creates missing categories when publishing
• Returns integer category IDs

Select mode:

• Category must be a valid slug from your Payload schema
• Set valid_categories in sync settings JSON (e.g., ["general", "news", "guides"])
• Defaults to general if category doesn't match valid list

5. Test Connection

Click Test Connection.

Success response shows:

• Total documents in articles collection
• Total documents in articles-es collection (if bilingual)
• Connected and authenticated status

Common errors:

• "Invalid email or password": Check credentials
• "Collection 'articles' not found": Check collection name
• "JWT token rejected": Token expired, reconnect

Click Save to complete setup.

6. Configure Bilingual Settings (Optional)

If you publish content in multiple languages:

English collection: articles (default) Spanish collection: articles-es (default)

ILLIXIS uses two separate collections for bilingual content:

• English articles → /api/articles
• Spanish articles → /api/articles-es

Each language gets its own document. Articles are linked via siblingId field.

Revalidation settings:

• Revalidation secret: Secret key for Next.js on-demand revalidation
• Used to clear cache after publishing
• Get this from your frontend .env file

Publishing Content

Publish Single-Language Article

1. Go to Content Hub and select an article
2. Click Publish
3. Select Payload CMS as destination
4. Choose Draft or Published status
5. Click Publish Now

ILLIXIS will:

• Upload featured image to /api/media collection
• Create or update article in Payload
• Store Payload document ID for future updates
• Trigger revalidation if published (not draft)

Publish Bilingual Article

1. Create or translate article in Content Hub
2. Select both English and translated versions
3. Click Publish Bilingual
4. Choose Draft or Published
5. Click Publish Now

ILLIXIS will:

• Publish English to /api/articles
• Publish Spanish to /api/articles-es
• Link articles via siblingId field (bidirectional)
• Upload featured images for both languages
• Trigger revalidation for both languages if published

Repair Bilingual Links

If you published English and Spanish articles separately and need to link them:

1. Go to Content Hub > Content Sources
2. Select your Payload connector
3. Click Repair Bilingual Links
4. Enter English article Payload ID
5. Enter Spanish article Payload ID
6. Click Repair

ILLIXIS patches both articles with correct siblingId references.

Importing Content

Pull Articles from Payload

1. Go to Content Hub > Content Sources
2. Select your Payload connector
3. Click Pull Content
4. Configure pull options:

• Collection: Which collection to pull from
• Language: Language code for imported content (e.g., en, es)
• Status filter: draft, published, or all
• Limit: Max articles to import (leave blank for all)

5. Click Pull Now

ILLIXIS will:

• Fetch articles from Payload API
• Convert Slate JSON rich text to HTML
• Create UnifiedContent records
• Store Payload document IDs for future sync
• Map external categories to ILLIXIS categories

Pull Specific Articles

To import specific articles by ID:

1. Click Pull Content
2. Enter comma-separated Payload document IDs
3. Select collection and language
4. Click Pull Now

Field Mapping

How ILLIXIS Maps Fields

Payload → ILLIXIS:

• title → UnifiedContent.title
• content → UnifiedContent.content (Slate JSON converted to HTML)
• slug → UnifiedContent.slug
• excerpt → UnifiedContent.meta_description
• status → UnifiedContent.status
• heroImage → UnifiedContent.featured_image (URL)

ILLIXIS → Payload:

• UnifiedContent.title → title
• UnifiedContent.content → content (HTML as string)
• UnifiedContent.slug → slug (auto-generated if missing)
• UnifiedContent.meta_description → excerpt
• UnifiedContent.featured_image → heroImage (uploaded to media collection)
• UnifiedContent.category_name → category (relationship ID or select slug)
• UnifiedContent.target_keyword → target_keyword (SEO field)

Rich Text Conversion

Payload uses Slate JSON for rich text. ILLIXIS converts Slate nodes to HTML:

Supported elements:

• Paragraphs, headings (h1-h6)
• Lists (ul, ol, li)
• Text formatting (bold, italic, underline, strikethrough, code)
• Links
• Images
• Blockquotes
• Code blocks

When pulling from Payload:

• Slate JSON → HTML
• Stored as HTML in ILLIXIS

When pushing to Payload:

• HTML → Plain string (Payload can store HTML strings in text fields)
• For rich text fields expecting Slate, use Payload's rich text editor post-import

Handling Media

Featured Images

When publishing to Payload:

1. ILLIXIS downloads the featured image (from R2, Unsplash, or local storage)
2. Uploads to /api/media collection via multipart form
3. Receives media document ID from Payload
4. Includes media ID in article payload as heroImage field
5. Payload links the image as a relationship

Alt text:

• Uses UnifiedContent.image_alt_text if set
• Falls back to UnifiedContent.title

Image formats supported:

• JPEG, PNG, WebP, GIF

Self-Healing Updates

If an article exists in ILLIXIS mapping but was deleted from Payload:

• ILLIXIS detects 404 when trying to update
• Logs warning: "Payload item not found (deleted from Payload?)"
• Deletes old mapping
• Creates new article in Payload
• Updates mapping with new Payload ID

No manual intervention required.

Category Management

Auto-Create Categories

When publishing content with a category that doesn't exist in Payload:

Relationship mode (recommended):

• ILLIXIS calls /api/categories to fetch existing
• If category not found, creates it automatically
• Uses name and slug fields
• Returns new category ID
• Includes in article payload

Select mode:

• Checks if category slug is in valid_categories list
• If not valid, falls back to general
• Does NOT create categories (must exist in Payload schema)

Mapping Strategy

Set create_missing_categories: true in connector settings to enable auto-creation.

Example:
```json
{
"category_mode": "relationship",
"create_missing_categories": true
}
```

Bilingual Architecture

How ILLIXIS Handles Multiple Languages

Payload CMS uses two separate collections for bilingual content:

Collections:

• /api/articles (English)
• /api/articles-es (Spanish)

Linking:

• Each article has a siblingId field
• Points to the Payload document ID of the translated version
• Bidirectional (EN → ES and ES → EN)

Publishing flow:

1. Push English:

• POST to /api/articles
• Upload English featured image
• Receive EN document ID

2. Push Spanish:

• POST to /api/articles-es
• Upload Spanish featured image
• Include siblingId pointing to EN document
• Receive ES document ID

3. Link English to Spanish:

• PATCH /api/articles/{en_id}
• Update siblingId field with ES document ID

Result: Both articles reference each other for language switcher on frontend.

Language Collection Mapping

Default mappings:

| Language | Payload Collection |
|----------|--------------------|
| English | articles |
| Spanish | articles-es |

To add more languages, contact support to update the language mapping, and create corresponding collections in Payload.

Frontend Revalidation

On-Demand Cache Clearing

When publishing articles to Payload (not draft), ILLIXIS triggers Next.js revalidation:

How it works:

1. Article published to Payload
2. ILLIXIS determines frontend path based on language:

• English: /learn/{slug}
• Spanish: /es/aprender/{slug}

3. Sends POST to /api/revalidate with path and secret
4. Next.js clears cached page
5. Next visitor gets fresh content

Configuration:

Set revalidation_secret in connector sync settings:

```json
{
"revalidation_secret": "your-secret-from-env"
}
```

Get this secret from your Next.js .env file:
```
REVALIDATE_SECRET=your-secret-here
```

Without revalidation:

• Published changes won't appear until ISR timeout (e.g., 60 seconds)
• Revalidation shows changes immediately

Publishing Lead Magnets

ILLIXIS can publish lead magnets (quizzes, calculators, assessments) to Payload as pages.

Cascade Logic

ILLIXIS tries publishing to these collections in order:

1. pages (default)
2. forms
3. landing-pages
4. content (fallback)
5. Embed code (if all collections fail)

Publish Form to Payload

1. Go to Lead Magnets
2. Select a quiz/calculator/assessment
3. Click Publish to CMS
4. Select Payload CMS
5. Choose collection (default: pages)
6. Click Publish

ILLIXIS will:

• Create page in Payload with form HTML
• Set status to published
• Store form ID in metadata field _illixis_form_id
• Return public URL

If collection doesn't exist:

• ILLIXIS returns available collections
• Try different collection from list
• Or use embed code as fallback

Sync Logs

Every pull/push operation creates a sync log.

View Sync History

1. Go to Content Hub > Content Sources
2. Select your Payload connector
3. Click View Sync Logs

Sync log details:

• Operation type (pull/push)
• Records processed
• Records failed
• Error details (if any)
• Timestamp

Troubleshooting Failed Syncs

"Authentication failed":

• Token expired, reconnect via Settings > Integrations
• Check email/password are correct

"Collection not found":

• Verify collection name in connector settings
• Check Payload admin for correct collection slug

"Failed to upload image":

• Check image URL is accessible
• Verify Payload media collection exists
• Check file size (Payload may have limits)

"Category creation failed":

• Check Payload categories collection exists
• Verify API permissions allow category creation
• Enable create_missing_categories in connector settings

Disconnecting

To disconnect Payload CMS:

1. Go to Settings > Integrations > Content & CMS
2. Find the Payload connector card
3. Click Disconnect
4. Confirm the action

This removes the stored JWT credentials. Your mapped content remains in ILLIXIS until you manually delete it.

Privacy & Permissions

ILLIXIS uses JWT authentication with admin credentials. We can:

• Read collections and categories
• Create, update, and delete articles
• Upload media files
• Create categories (if enabled)

Security:

• JWT tokens are stored encrypted
• Tokens auto-refresh on each request
• No access to Payload admin settings
• No access to user management

Your Payload credentials are encrypted and stored securely. ILLIXIS re-authenticates on each API call to ensure fresh tokens.

Advanced Configuration

Custom Field Mapping

To map custom Payload fields, update sync settings JSON:

```json
{
"title_field": "headline",
"content_field": "body",
"slug_field": "urlSlug",
"status_field": "publishStatus",
"excerpt_field": "description",
"draft_status": "unpublished",
"published_status": "live"
}
```

Collection-Specific Settings

For different collections with different schemas:

```json
{
"collection": "blog-posts",
"title_field": "postTitle",
"content_field": "postContent",
"category_mode": "select",
"valid_categories": ["tech", "design", "marketing"]
}
```

Bilingual Configuration

For custom language collection mappings, contact support with your desired language-to-collection mapping (e.g., English → "articles", Spanish → "articulos", French → "articles-fr").

Next Steps

With Payload CMS connected:

• Publish articles from Content Hub to Payload
• Import existing Payload articles for editing
• Schedule bilingual content publishing
• Use lead magnets with Payload-hosted forms
• Monitor sync logs for troubleshooting

All published content syncs bidirectionally between ILLIXIS and Payload CMS.