add documentation and test case for hooks to handle

Author: paulpopus

docs/plugins/import-export.mdx

@@ -483,6 +483,109 @@ export: {
 },
 ```
 
+### Column name mapping for foreign systems
+
+When importing from or exporting to a foreign system (a third-party CRM, an analytics dump, a legacy CSV), column names rarely match your Payload field names. Both directions are handled with the existing batch hooks — no new API is required.
+
+#### Exporting with renamed CSV columns
+
+Use `export.hooks.before` to rewrite every row's keys to the foreign system's column names. The returned shape is what gets written to the file.
+
+```ts
+import { importExportPlugin } from '@payloadcms/plugin-import-export'
+
+const exportRenameMap: Record<string, string> = {
+  title: 'Post Title',
+  excerpt: 'Summary',
+  count: 'View Count',
+}
+
+importExportPlugin({
+  collections: [
+    {
+      slug: 'posts',
+      export: {
+        hooks: {
+          before: ({ data }) =>
+            data.map((row) => {
+              const renamed: Record<string, unknown> = {}
+              for (const [key, value] of Object.entries(row)) {
+                renamed[exportRenameMap[key] ?? key] = value
+              }
+              return renamed
+            }),
+        },
+      },
+    },
+  ],
+})
+```
+
+JSON exports work the same way — the hook receives the fully-transformed batch, and the returned keys become the top-level JSON keys.
+
+#### Importing from foreign CSV columns
+
+Use `import.hooks.before` to rewrite incoming keys back to Payload field names. The hook receives already-unflattened documents, so foreign top-level keys like `Post Title` are still present and can be remapped to `title` before the DB write. Keys you don't include in the returned object are dropped.
+
+```ts
+const importRenameMap: Record<string, string> = {
+  'Post Title': 'title',
+  Summary: 'excerpt',
+  'View Count': 'count',
+}
+
+importExportPlugin({
+  collections: [
+    {
+      slug: 'posts',
+      import: {
+        hooks: {
+          before: ({ data }) =>
+            data.map((doc) => {
+              const renamed: Record<string, unknown> = {}
+              for (const [key, value] of Object.entries(doc)) {
+                const payloadKey = importRenameMap[key]
+                if (payloadKey) {
+                  renamed[payloadKey] = value
+                }
+                // Foreign keys not present in the rename map are dropped.
+              }
+              return renamed
+            }),
+        },
+      },
+    },
+  ],
+})
+```
+
+CSV cell values arrive as strings. Payload coerces basic scalar types automatically on write, but if a target field has stricter validation you can coerce inside the hook (`renamed.count = Number(value)`).
+
+#### Field-level export rename for shared fields
+
+When a field definition is shared across collections and the rename should travel with the field, use the field's own `hooks.beforeExport`. Mutate `siblingData` to add the renamed key and return `undefined` so the original field key is dropped from the output:
+
+```ts
+import type { FieldBeforeExportHook } from '@payloadcms/plugin-import-export'
+
+const sharedNameField = {
+  name: 'sharedName',
+  type: 'text' as const,
+  custom: {
+    'plugin-import-export': {
+      hooks: {
+        beforeExport: (({ siblingData, value }) => {
+          siblingData['Display Name'] = value
+          return undefined
+        }) satisfies FieldBeforeExportHook,
+      },
+    },
+  },
+}
+```
+
+This pattern is export-only. Field-level `hooks.beforeImport` does **not** fire for foreign columns — it's keyed by the incoming column name, so it can't pick up a column whose name doesn't already match a Payload field. For the reverse direction, use the collection-level `import.hooks.before` recipe above.
+
 ## Field Options
 
 In addition to collection-level hooks, you can configure field-level export and import behavior directly on any field's `custom['plugin-import-export']` config. This is especially useful when:

test/plugin-import-export/collections/PostsWithColumnMap.ts

@@ -0,0 +1,43 @@
+import type { FieldBeforeExportHook } from '@payloadcms/plugin-import-export/types'
+import type { CollectionConfig } from 'payload'
+
+import { postsWithColumnMapSlug } from '../shared.js'
+
+// Payload field name -> foreign system column name.
+// Used by collection-level export.hooks.before in config.ts and mirrored
+// in import.hooks.before.
+export const exportRenameMap: Record<string, string> = {
+  title: 'Post Title',
+  excerpt: 'Summary',
+  count: 'View Count',
+}
+
+export const importRenameMap: Record<string, string> = {
+  'Post Title': 'title',
+  Summary: 'excerpt',
+  'View Count': 'count',
+}
+
+export const PostsWithColumnMap: CollectionConfig = {
+  slug: postsWithColumnMapSlug,
+  admin: { useAsTitle: 'title' },
+  fields: [
+    { name: 'title', type: 'text', required: true },
+    { name: 'excerpt', type: 'text' },
+    { name: 'count', type: 'number' },
+    {
+      name: 'sharedName',
+      type: 'text',
+      custom: {
+        'plugin-import-export': {
+          hooks: {
+            beforeExport: (({ siblingData, value }) => {
+              siblingData['Display Name'] = value
+              return undefined
+            }) satisfies FieldBeforeExportHook,
+          },
+        },
+      },
+    },
+  ],
+}

test/plugin-import-export/config.ts

@@ -17,6 +17,11 @@ import { Posts } from './collections/Posts.js'
 import { PostsExportsOnly } from './collections/PostsExportsOnly.js'
 import { PostsImportsOnly } from './collections/PostsImportsOnly.js'
 import { PostsNoJobsQueue } from './collections/PostsNoJobsQueue.js'
+import {
+  exportRenameMap,
+  importRenameMap,
+  PostsWithColumnMap,
+} from './collections/PostsWithColumnMap.js'
 import { PostsWithFieldHooks } from './collections/PostsWithFieldHooks.js'
 import { PostsWithHooks } from './collections/PostsWithHooks.js'
 import { PostsWithLimits } from './collections/PostsWithLimits.js'
@@ -31,6 +36,7 @@ import {
 import { seed } from './seed/index.js'
 import {
   customIdPagesSlug,
+  postsWithColumnMapSlug,
   postsWithFieldHooksSlug,
   postsWithHooksSlug,
   postsWithS3Slug,
@@ -64,6 +70,7 @@ export default buildConfigWithDefaults({
     PostsWithS3,
     PostsWithHooks,
     PostsWithFieldHooks,
+    PostsWithColumnMap,
     Media,
     CustomIdPages,
   ],
@@ -282,6 +289,50 @@ export default buildConfigWithDefaults({
             },
           },
         },
+        {
+          slug: postsWithColumnMapSlug,
+          export: {
+            disableJobsQueue: true,
+            hooks: {
+              before: ({ data }) => {
+                return data.map((row) => {
+                  const renamed: Record<string, unknown> = {}
+                  for (const [key, value] of Object.entries(row)) {
+                    renamed[exportRenameMap[key] ?? key] = value
+                  }
+                  return renamed
+                })
+              },
+            },
+            overrideCollection: ({ collection }) => {
+              collection.slug = 'posts-with-column-map-export'
+              collection.upload.staticDir = path.resolve(dirname, 'uploads')
+              return collection
+            },
+          },
+          import: {
+            disableJobsQueue: true,
+            hooks: {
+              before: ({ data }) => {
+                return data.map((doc) => {
+                  const renamed: Record<string, unknown> = {}
+                  for (const [key, value] of Object.entries(doc)) {
+                    const payloadKey = importRenameMap[key]
+                    if (payloadKey) {
+                      renamed[payloadKey] = value
+                    }
+                  }
+                  return renamed
+                })
+              },
+            },
+            overrideCollection: ({ collection }) => {
+              collection.slug = 'posts-with-column-map-import'
+              collection.upload.staticDir = path.resolve(dirname, 'uploads')
+              return collection
+            },
+          },
+        },
       ],
     }),
     s3Storage({

test/plugin-import-export/e2e.spec.ts

@@ -21,7 +21,13 @@ import {
 import { AdminUrlUtil } from '../__helpers/shared/adminUrlUtil.js'
 import { initPayloadE2ENoConfig } from '../__helpers/shared/initPayloadE2ENoConfig.js'
 import { POLL_TOPASS_TIMEOUT, TEST_TIMEOUT_LONG } from '../playwright.config.js'
-import { postsWithS3ExportSlug, postsWithS3ImportSlug, postsWithS3Slug } from './shared.js'
+import { readCSV } from './helpers.js'
+import {
+  postsWithColumnMapSlug,
+  postsWithS3ExportSlug,
+  postsWithS3ImportSlug,
+  postsWithS3Slug,
+} from './shared.js'
 
 test.describe('Import Export Plugin', () => {
   let page: Page
@@ -1634,4 +1640,113 @@ test.describe('Import Export Plugin', () => {
       await expect(importCount).toContainText('10 documents to import')
     })
   })
+
+  test.describe('column mapping e2e', () => {
+    const tempFiles: string[] = []
+    const createdTitles: string[] = []
+
+    test.afterEach(async () => {
+      for (const filePath of tempFiles) {
+        if (fs.existsSync(filePath)) {
+          fs.unlinkSync(filePath)
+        }
+      }
+      tempFiles.length = 0
+
+      for (const title of createdTitles) {
+        await payload.delete({
+          collection: postsWithColumnMapSlug,
+          where: { title: { equals: title } },
+        })
+      }
+      createdTitles.length = 0
+    })
+
+    test('should import a CSV with foreign column headers through the admin UI', async () => {
+      const csvContent =
+        '"Post Title","Summary","View Count"\n' +
+        '"E2E Foreign A","e2e summary a","11"\n' +
+        '"E2E Foreign B","e2e summary b","22"\n'
+      const csvPath = path.join(__dirname, 'uploads', 'e2e-column-map-import.csv')
+      fs.writeFileSync(csvPath, csvContent)
+      tempFiles.push(csvPath)
+      createdTitles.push('E2E Foreign A', 'E2E Foreign B')
+
+      const columnMapImportsURL = new AdminUrlUtil(serverURL, 'posts-with-column-map-import')
+      await page.goto(columnMapImportsURL.create)
+      await expect(page.locator('.collection-edit')).toBeVisible()
+
+      await page.setInputFiles('input[type="file"]', csvPath)
+      await expect(page.locator('.file-field__filename')).toHaveValue('e2e-column-map-import.csv')
+
+      const importModeField = page.locator('#field-importMode')
+      await importModeField.click()
+      await page.locator('.rs__option:has-text("create")').first().click()
+
+      await saveDocAndAssert(page)
+
+      await expect(async () => {
+        const { docs } = await payload.find({
+          collection: postsWithColumnMapSlug,
+          where: { title: { in: ['E2E Foreign A', 'E2E Foreign B'] } },
+        })
+        expect(docs).toHaveLength(2)
+      }).toPass({ timeout: POLL_TOPASS_TIMEOUT })
+
+      const imported = await payload.find({
+        collection: postsWithColumnMapSlug,
+        sort: 'title',
+        where: { title: { in: ['E2E Foreign A', 'E2E Foreign B'] } },
+      })
+
+      expect(imported.docs[0]!.title).toBe('E2E Foreign A')
+      expect(imported.docs[0]!.excerpt).toBe('e2e summary a')
+      expect(imported.docs[0]!.count).toBe(11)
+      expect(imported.docs[1]!.title).toBe('E2E Foreign B')
+      expect(imported.docs[1]!.count).toBe(22)
+    })
+
+    test('should export CSV with renamed column headers via admin save', async () => {
+      await payload.create({
+        collection: postsWithColumnMapSlug,
+        data: { title: 'E2E Export Rename', excerpt: 'exported summary', count: 99 },
+      })
+      createdTitles.push('E2E Export Rename')
+
+      const columnMapExportsURL = new AdminUrlUtil(serverURL, 'posts-with-column-map-export')
+      await page.goto(columnMapExportsURL.create)
+      await expect(page.locator('.collection-edit')).toBeVisible()
+
+      await saveDocAndAssert(page, '#action-save')
+
+      await expect(async () => {
+        await page.reload()
+        const exportFilename = page.locator('.file-details__main-detail')
+        await expect(exportFilename).toBeVisible()
+        await expect(exportFilename).toContainText('.csv')
+      }).toPass({ timeout: POLL_TOPASS_TIMEOUT })
+
+      const exports = await payload.find({
+        collection: 'posts-with-column-map-export',
+        sort: '-createdAt',
+        limit: 1,
+      })
+
+      expect(exports.docs).toHaveLength(1)
+      const exportDoc = exports.docs[0]! as unknown as { filename: string; id: number | string }
+      const csvPath = path.join(__dirname, 'uploads', exportDoc.filename)
+      const rows = await readCSV(csvPath)
+
+      const matching = rows.find((row) => row['Post Title'] === 'E2E Export Rename')
+      expect(matching).toBeDefined()
+      expect(matching!.Summary).toBe('exported summary')
+      expect(matching!['View Count']).toBe('99')
+      expect(matching!.title).toBeUndefined()
+
+      await payload.delete({
+        collection: 'posts-with-column-map-export',
+        id: exportDoc.id,
+      })
+    })
+  })
 })