Skip to main content

Custom Fields

Migrating Custom Fields with Claude Code

dotCMS provides a Claude Code skill, dot-ui-vtl-migration, that updates older custom fields for you. It works on one field you paste in, or on every custom field of a dotCMS site, and it always keeps your original code so the old editor keeps working. The changes it makes are the ones described in Migrating Legacy Custom Fields.

Install the Skill#


Copy the .claude/skills/dot-ui-vtl-migration folder from the dotCMS core repository into the .claude/skills/ folder in your home folder. Claude Code picks it up the next time it starts.

Migrate One Field#


Paste the field's code into Claude Code and ask:

Migrate this custom field to the new DotCustomFieldApi:

<script>
  dojo.ready(function () { … });
</script>

You get the updated code back, ready to paste into the field's Value, with your original kept after #else. Then switch the field to Recommended. If the two versions can't safely share one field, for example because both define a macro with the same name, Claude Code says so and offers to split the code into separate files instead.

Migrate a Whole Instance#


The skill can also find every older custom field on your site, update them in batches you choose, and publish the results. You need:

  • uv installed. It also installs the Python version the skill needs (3.11 or later).
  • An API token for a user who can edit content types and publish the content the fields' code files belong to. Claude Code needs it as the DOTCMS_TOKEN environment variable; create it in Users: select the user, then the API Tokens tab. Use a dedicated user that has only these permissions, and give the token a short expiry; revoke it when the migration is done.

Ask Claude Code to Migrate All Custom Fields#

For example: "migrate all the custom fields on https://my-env.dotcms.dev". Claude Code guides you through the steps below and runs the commands for you.

Find What Needs Updating#

It checks every content type and downloads a copy of each custom field that still uses the old code. Nothing on your site changes in this step.

Pick a Batch#

Claude Code shows a numbered list of what it found, something like this:

| # | VTL              | Kind         | Used by                                     |
|---|------------------|--------------|---------------------------------------------|
| 1 | text-count.vtl   | /dA/ file    | 5 fields: Destination.pageTitleCount, …     |
| 2 | Banner.widget    | inline field | Banner.widget                               |
| 3 | Switch to Recommended only: Activity.urlTitle, Product.urlTitle  |

25 load core files, 3 use unhandled paths — say "details" to see them.

Which rows should I do now: all, row numbers (1,3), or none?

Answer all, some numbers such as 1,3, or none. A row can be a code file that several fields share; choosing it updates that file and switches every field that uses it to Recommended.

Review the Changes#

Claude Code updates the fields you chose and tells you what changed in each. Nothing is published until you confirm.

Publish#

The updated fields are published and switched to Recommended. If a shared code file has unpublished changes, publishing it publishes those changes too. If a field was changed on the site in the meantime, it's skipped and reported, and the rest continue.

Repeat#

Claude Code tells you what was published and what's left, and offers the next batch. You can stop at any time and continue later.

Fields the Skill Skips#


Some fields are reported but not changed. Claude Code tells you how many, and lists them when you ask; update those by hand or one at a time with Migrate One Field:

  • Fields that load their code from a file that ships with dotCMS (with mergeTemplate or #parse('static/…')).
  • Fields that load their code with #dotParse from a folder path, such as #dotParse("/application/custom-fields/url-slug.vtl"), rather than from a /dA/ address.
  • Fields that load their code with #dotParse from a specific version of a file (a /dA/ address with an inode).
  • Fields whose /dA/ file can't be found.

Fields whose code is already migrated keep their code. If they aren't set to Recommended yet, Claude Code offers to switch them. When publishing, the skill also skips a field if it was changed on the site in the meantime, or if its updated code doesn't keep the original version intact.