enonic-content-migration

Enonic Content Migration

Procedures

Step 1: Identify the Enonic XP project and operation scope

1. Inspect the workspace for Enonic XP project markers: build.gradle with com.enonic.xp dependencies, src/main/resources/ directory structure, or gradle.properties with xpVersion.
2. Execute node scripts/find-enonic-targets.mjs . to scan for Enonic XP project markers and existing content operation files when a Node runtime is available.
3. If no Enonic XP project is detected, stop and explain that this skill targets Enonic XP content operations only.
4. Determine the target XP version from gradle.properties or build.gradle to select the correct API surface.
5. Classify the requested operation:
   • Bulk create: Importing content from external sources (JSON, CSV, APIs).
   • Bulk update: Modifying existing content matching query criteria.
   • Bulk delete: Removing content matching query criteria.
   • Migration: Moving or transforming content between paths, sites, or environments.
   • Query/Aggregation: Retrieving and analyzing content with NoQL and aggregations.
   • Long-running task: Any operation processing more than ~100 items that needs progress reporting.

Step 2: Select the API layer and context

1. Read references/migration-reference.md for query DSL patterns, batch processing strategies, and branch handling rules.
2. Choose lib-content when the operation works with CMS content and needs publish/unpublish, content-type validation, and the content domain abstraction.
3. Choose lib-node when the operation needs low-level node manipulation, custom repositories, or bypasses content-type validation for raw data migration.
4. Determine the required context:
   • Use lib-context to run operations in draft branch for modifications and master branch for reading published content.
   • Use lib-context with role:system.admin principal when the operation requires elevated permissions.
5. If the operation processes more than ~100 items, wrap it in a task controller using lib-task. Read references/migration-reference.md section on task controllers for the pattern.

Step 3: Build the query

1. Construct the NoQL query string or DSL expression to match the target content.
2. For content-type filtering, use the contentTypes parameter on contentLib.query() or a type property comparison in node queries.
3. For date-range queries, use instant() or dateTime() functions and the range() query function.
4. For full-text search, use fulltext() with the appropriate field paths and operator (AND/OR).
5. For path-scoped operations, use _path LIKE '/content/site-path/*' to match descendants. Note: the _path property in NoQL queries includes the internal /content/ prefix, but hit._path in results returns the content-domain path without it. Always prepend /content/ when building queries from result paths.
6. Add filters for efficient post-query narrowing using exists, notExists, hasValue, or boolean combinations.
7. Add aggregations when the operation needs grouped statistics (term counts, date histograms, numeric ranges, stats).
8. Read references/examples.md for complete query and aggregation patterns.

Step 4: Implement batch processing

1. Use paginated retrieval with start and count parameters to avoid loading all results into memory.
2. Set count to a batch size between 50 and 200 depending on the complexity of per-item processing.
3. Loop until result.hits.length === 0 or start >= result.total, incrementing start by the batch size each iteration.
4. For contentLib.create() in bulk, set refresh: false to avoid per-item index refresh; call a manual refresh after the batch completes.
5. For contentLib.modify(), use the editor callback pattern to safely transform each content item.
6. For contentLib.publish(), batch keys into groups of 50–100 to avoid timeout on large publish sets.
7. Track success and failure counts for reporting.
8. Read assets/bulk-update.template.ts for the reusable batch update controller template. Note: templates use TypeScript/ESM syntax (import, const, arrow functions); adapt to CommonJS JavaScript (require(), var, function()) for XP runtime deployment as .js files.

Step 5: Handle branch operations and publishing

1. Run content modifications in the draft branch context.
2. After modifications complete, publish changed items to master using contentLib.publish(). On XP < 7.12, pass sourceBranch: 'draft' and targetBranch: 'master'. On XP 7.12+, these parameters are ignored (publish always goes draft→master).
3. Set includeDependencies: false when publishing bulk-updated items to avoid unintended dependency publishing.
4. For operations comparing draft and master state, use repo.diff() from lib-node with target: 'master' and includeChildren: true.

Step 6: Wrap long-running operations in a task controller

1. Use taskLib.executeFunction() for inline task functions or taskLib.submitTask() for named task descriptors.
2. Report progress using taskLib.progress({ info, current, total }) at regular intervals during batch processing.
3. Read assets/task-migration.template.ts for the reusable task controller template with progress reporting.
4. Check for existing running instances with taskLib.isRunning() before starting a duplicate operation.
5. Use taskLib.sleep() for throttling between batches if the operation generates excessive load.
6. For named tasks on XP 7.13+, the run function receives taskId as its second argument: exports.run = function(params, taskId) { ... }.

Step 7: Validate and report results

1. After the operation completes, log a summary: items processed, items created/updated/deleted, items failed, total duration.
2. For migration operations, verify target content exists by querying the destination path.
3. For publish operations, verify published state by querying the master branch.
4. If errors occurred, collect error details (content path, error message) into a structured report.

Error Handling

• If scripts/find-enonic-targets.mjs finds no Enonic XP project, explain that the workspace does not contain an Enonic XP application.
• If a content operation fails with contentAlreadyExists, check whether the target exists and decide whether to update or skip. Read references/troubleshooting.md for duplicate handling patterns.
• If a query returns zero results, verify the query syntax, branch context, and property paths. NoQL string-format mismatches (e.g. missing instant() wrapper for date comparisons) are a common cause.
• If a task fails or times out, check taskLib.get(taskId) for state and progress details. Read references/troubleshooting.md for timeout and permission issues.
• If an AccessDeniedException occurs on publish or modify, ensure the context includes role:system.admin principals via lib-context.