@websolutespa/payload-plugin-ws-contentmachine-connector

Websolute content machine connector plugin for Payload CMS.

Overview

A plugin that seamlessly connects your Payload CMS instance with the Websolute Content Machine web application. It automates the creation and updating of documents in Payload based on the content from your Content Machine datasets, ensuring that the CMS data stays synchronized with your content source.

Features

• Automated document sync: automatically creates, updates, unpublish or deletes Payload documents by reading dataset items exposed from the Content Machine web application.
• Scheduled sync: configure an automatic sync task using a cron schedule expression.
• Manual sync: trigger manual synchronization for specific collections directly from the Payload admin UI.
• Localization support: supports both localized and non-localized fields.
• Field type compatibility: syncs various Payload field types, including Text, Textarea, RichText, Checkbox, Email, Number, Select, Upload

Requirements:

• Payload version 3.29.0 or higher is required.

Installation

Install the plugin using npm:

npm i @websolutespa/payload-plugin-ws-contentmachine-connector

Usage

To use the plugin, import it into your Payload configuration and add it to your plugins array. You'll also need to configure individual collections that you want to synchronize.

import { buildConfig } from 'payload/config';
import { contentMachineConnector, ContentMachineCollection } from '@websolutespa/payload-plugin-ws-contentmachine-connector';

// Collection config example
export const ExampleCollection: ContentMachineCollection = {
  slug: 'example-collection',
  versions: { drafts: true },
  fields: [
    {
      name: 'title',
      type: 'text',
      localized: true,
    },
    {
      name: 'abstract',
      type: 'richText',
      localized: true,
    },
    {
      name: 'type',
      type: 'select',
      options: [
        { label: 'Mystery', value: 'mystery' },
        { label: 'Non-Fiction', value: 'non-fiction' },
        { label: 'Fantasy', value: 'fantasy' },
      ],
    },
    {
      name: 'author',
      type: 'group',
      fields: [
        {
          name: 'name',
          type: 'text',
        }
      ],
    },
    {
      name: 'cover',
      type: 'upload',
      relationTo: 'media',
    },
  ],
  custom: {
    contentMachine: {
      enabled: true,
      projectId: 'projectBooks',
      datasets: ['it', 'en'],
      orphanedDocStrategy: 'unpublish', // 'ignore' | 'delete' | 'unpublish'
      fieldMappings: {
        title: { outputColumn: 'title' },
        abstract: { outputColumn: 'description' },
        'author.name': { outputColumn: 'author' },
        type: { outputColumn: 'type' },
        cover: { outputColumn: 'cover' },
      },
      onBeforeSync: ({ data, datasetItem }) => {
        // set the _status field based on the approved field in the dataset
        const approved = datasetItem.data[locale].approved ?? datasetItem.data['it'].approved;
        if (typeof approved === 'undefined') {
          throw new Error(`approved field is missing in the dataset for item ${datasetItem.id}`);
        }
        data._status = approved === 'true' || approved === '1' ? 'published' : 'draft';
        return data;
      },
    },
  },
  // The rest of the collection config goes here
};

export default buildConfig({
  plugins: [
    contentMachineConnector({
      enabled: true,
      apiUrl: 'https://content-machine.ws-deploy-02.wslabs.it/api',
      auth: {
        type: 'none',
      },
      syncSchedule: '0 * * * *', // automatic sync every 1 hour
    }),
    // The rest of your plugins config goes here
  ],
});

Plugin options

These options are passed directly to the contentMachineConnector function in your payload.config.ts:

| Option | Type | Description | |----------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | enabled | boolean | Set to true to enable the plugin, false to disable it. | | apiUrl | string | The base URL of your Content Machine web application. | | auth | ContentMachineAuth | Content machine web application authentication options: - type: either none, basic or apiKey- username - password - apiKey | | syncSchedule | string [optional] | A valid cron schedule expression to set up automatic synchronization. If omitted, automatic sync is disabled, but manual sync via the admin UI remains available. |

Collection configuration options

These options are defined within the custom.contentMachine property of each Payload collection's configuration:

| Option | Type | Description | |----------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | enabled | boolean | Only enabled collections will be synced (either automatically or manually). | | projectId | string | The ID of the Content Machine project that contains the datasets relevant to this Payload collection. | | dataset | string[] | An array of Content Machine dataset IDs. Each ID should correspond to a locale configured in your Payload CMS, enabling content synchronization for different languages. | | orphanedDocStrategy | ignore | delete | unpublish | Defines the strategy for handling documents in Payload that are no longer present in the Content Machine dataset: - ignore: Does nothing. - delete: Deletes documents that are not found in the dataset. - unpublish: Unpublishes documents that are not found in the dataset. Note: This strategy only works if the collection has drafts enabled; otherwise, it will do nothing. | fieldMappings | ContentMachineFieldMappings | An object defining how Payload collection fields map to Content Machine output columns. The key is the Payload field name (use dot notation for nested fields, e.g., 'author.name'), and the value is an object specifying the outputColumn name from the Content Machine dataset. | | onBeforeSync | function | An optional function that is executed before a document is created or updated. It receives an object with the following properties: data (the Payload document data), datasetItem (the item from the Content Machine dataset), and locale (the current locale). The function can modify and return the data object before it's saved. This is useful for custom data transformations or setting default values. | useAsTitle | string | Specifies which output column from the Content Machine dataset should be used as the document's title for reporting and error messages during import. This helps identify items in logs and error reports by a human-readable name. If omitted, it defaults to "title". | |

this library is for internal usage and not production ready