DEV Community

Cover image for Jira (migrated) custom fields: prevent and merge
Mihai Perdum
Mihai Perdum

Posted on Originally published at leanzero.net

Jira (migrated) custom fields: prevent and merge

If your Jira Cloud site lists "Customer ID" next to "Customer ID (migrated)", the migration found a custom field with the same name that it had no record of migrating, so it created a second field instead of guessing. It happens with JCMA (the Jira Cloud Migration Assistant, the free app that moves Data Center data to Cloud). It also happens with Copy product data, the admin tool that copies projects from one Cloud site to another. On 21 November 2026 we ran both on our own test sites, and one Copy product data run for a project with 3 work items created 654 custom fields on the destination (we counted them over the REST API before and after), 653 of them with a suffix.

You're in good company. An admin asked about custom fields renamed to "custom field(migrated)" on the Atlassian Community in October 2022, and that thread had 4,662 views when we read it. Atlassian's ticket for the Cloud-to-Cloud case, JRACLOUD-82762, has 127 votes and has been open since June 2022.

In both of our runs the migrated work items carried their values in the new "(migrated)" field, and the field we already had stayed empty. So you have two jobs. Before each migration, decide what should happen to each field whose name already exists in Cloud. After it, move the values into the field you want to keep, repoint the filters, and move the copy to the trash, where you can restore it for 60 days.

I ran JCMA 1.32.0 from a fresh Jira Data Center 11.3.13 into our Cloud test site in two waves, and Copy product data between two Cloud sites in our organisation. The steps come first, and the evidence from both runs follows them. Atlassian now calls a Jira project a space and an issue a work item, and its admin UI also says "Copy app data" and "Data transfer" for Copy product data.

[[steps]]

  1. Find every (migrated) field and the field it duplicates.
  2. Set the conflict rules before each JCMA wave in the pre-migration checks.
  3. Find the name clashes before a Copy product data run, which has no conflict step.
  4. Merge the values into the field you keep with a scheduled automation rule.
  5. Repoint filters, then move the copy to the trash and check the Deleted fields tab.

Before you start

Note

Prerequisites

  • Destination: Jira Cloud on any plan, a Jira admin account there, and an API token for it (the commands below use one).
  • For Data Center to Cloud: Jira Software or Jira Service Management Data Center with JCMA updated from Marketplace (we used 1.32.0; Atlassian states no minimum version for the conflict step), and a Jira system administrator on the source.
  • For Cloud to Cloud: an organisation admin for both sites.
  • curl and jq in a terminal.
  • A test Cloud site or sandbox for a rehearsal. Atlassian's KB says that to wipe duplicates before a new test run you "completely reset the site and restart migration from a new server".

When you're done you'll have one field per name with its values, filters pointing at it, and the copy in the trash.

Step 1: Find every (migrated) field and the field it duplicates

The Fields page search works for a quick look. On a site with hundreds of fields I use the REST API. field/search returns at most 50 fields per page, whatever you ask for. Its query also matches descriptions, so a field whose description says "Migrated on" comes back even without the suffix.

  1. In a terminal, set your site and credentials: SITE=your-site, EMAIL=you@example.com, TOKEN=<API token>.
  2. Run this loop. It pages through the custom fields matching "migrated" and keeps only the names that carry the suffix.
s=0
while :; do
  r=$(curl -s -u "$EMAIL:$TOKEN" \
    "https://$SITE.atlassian.net/rest/api/3/field/search?type=custom&query=migrated&startAt=$s&maxResults=50")
  echo "$r" | jq -r '.values[] | select(.name | test("\\(migrated")) | "\(.id)\t\(.name)"'
  [ "$(echo "$r" | jq .isLast)" = true ] && break
  s=$((s+50))
done | sort -t$'\t' -k2
Enter fullscreen mode Exit fullscreen mode

You should see one line per field, with its id. On the source site of our Cloud-to-Cloud copy, the search matched 648 fields and 14 of them carried the suffix. These are the first 5 lines:

customfield_10223   Actual end (migrated)
customfield_10171   Actual start (migrated)
customfield_10159   Approvers (migrated)
customfield_10113   Change reason (migrated)
customfield_10112   Change risk (migrated)
Enter fullscreen mode Exit fullscreen mode
  1. For each copy, look up the original by its plain name (here "Approvers"):
curl -s -u "$EMAIL:$TOKEN" "https://$SITE.atlassian.net/rest/api/3/field/search?type=custom&query=Approvers" | jq -r '.values[] | "\(.id)\t\(.name)"'
Enter fullscreen mode Exit fullscreen mode

You should see both fields. Write down both ids and mark which one is the copy, because Step 4 needs them. On that site it printed:

customfield_10003   Approvers
customfield_10159   Approvers (migrated)
Enter fullscreen mode Exit fullscreen mode

Don't use GET /rest/api/3/field for this. On that source site it listed all 14 at 04:32, while our test project existed, and none of them at 05:03. What it returns depends on what the site's spaces use, so it isn't a full list.

Step 2: Prevent duplicate fields before each JCMA wave with the conflict rules CSV

This step was in JCMA 1.32.0 on our Data Center 11.3.13, inside the pre-migration checks. Atlassian's docs on resolving configuration duplication still describe it as early access: "reach out to your Cloud migration manager". Its 30 October 2026 Community post calls it Config Deduplication in open beta and says to ask your migration contact "to enable the feature flag for your migration". I didn't ask anyone. The section was just there.

  1. In JCMA, create your migration plan and select Save and run pre-migration checks. The button stays disabled until each section of the plan has a choice.
  2. In the checks, open Entities, then Update rules for configuration entities. The page says "Please set rules on how to handle configuration entity conflicts arising from source entities that have the same name as the destination entities."
  3. Select Download CSV file. The file has one row per entity type with its allowed choices, for example "Source of truth for customField entity" with OVERRIDE, REUSE and DECIDE_LATER.
  4. In the custom field row, choose REUSE to keep the Cloud field or OVERRIDE to bring in the Data Center one. Atlassian defines them as "reuse the configuration from your Cloud instance" and "bring in the configuration from your Data Center". DECIDE_LATER defers the choice.
  5. Select Upload CSV file, then Run check next to "Check and update configuration entities manually" (the page says it "May take 30 minutes or longer"). Atlassian's doc says you then download a Conflicted configuration entities CSV and choose per entity by pasting a choice id into its Customer_selected_choice_id column.

JCMA pre-migration checks with the Entities section open on Update rules for configuration entities, showing Download CSV file and Upload CSV file buttons and a disabled Run check button.

I left the rules blank in both waves. I never uploaded the CSV either, so items 4 and 5 come from the page and Atlassian's doc, and I can't show you what REUSE does to the values. Blank rules gave us the duplicates, and I'd guess that's how a lot of sites get theirs. Atlassian's page on entity behaviour warns that for a field migrated in an earlier phase, OVERRIDE or REUSE "may change the field's name" and "can break existing or new filters", and that boards can only be reused or overridden, never merged. Rehearse it on a test site first.

On a JCMA version without this section, Atlassian's pre-migration checklist recommends renaming configuration in Data Center that has the same name as configuration in Cloud. That avoids the suffix but leaves you with two fields. To end up with one, I'd delete the hand-made Cloud field before the wave if it holds no data and nothing points at it, so that JCMA can create the field under its plain name. It's on the open questions list below.

Step 3: Find the name clashes before a Copy product data run

Copy product data has no conflict step. Nor does its validation warn: our run showed 14 checks, all Ready, and none was about field names that already exist. So the work happens before you start the copy.

Copy product data's Validate data page with a list of checks, each marked Ready, including No conflicting projects found and No duplicate boards and filters in the destination.

  1. On each site, list all custom field names into a file. Run this once with SITE set to the source and once with it set to the destination:
s=0
while :; do
  r=$(curl -s -u "$EMAIL:$TOKEN" \
    "https://$SITE.atlassian.net/rest/api/3/field/search?type=custom&startAt=$s&maxResults=50")
  echo "$r" | jq -r '.values[].name'
  [ "$(echo "$r" | jq .isLast)" = true ] && break
  s=$((s+50))
done | sort -u > "$SITE-fields.txt"
Enter fullscreen mode Exit fullscreen mode
  1. Print the names that exist on both sites, replacing the two file names with your sites':
comm -12 source-site-fields.txt destination-site-fields.txt
Enter fullscreen mode Exit fullscreen mode

You should see one name per line. Our two sites, after cleanup, had 698 and 705 custom field names, and 684 of them were on both (684 lines). The first 3:

2023 peak surcharge
API client id
AS400 batch id
Enter fullscreen mode Exit fullscreen mode

A field the copy carries whose name is in this list arrives as "(migrated)", unless an earlier copy from this source already linked it. A copy in the other direction doesn't count: our 644 fields from the 13 November copy came back with the suffix.

  1. For each clash, decide which field survives. My suggestion: delete an empty destination field before the copy, then check Deleted fields (whether a trashed field still blocks its name is an open question below). Renaming the source field avoids the suffix but still leaves two fields.
  2. After the copy, run Step 1 on the destination and count the new suffixes.

Step 4: Merge a duplicate custom field into the original in Jira Cloud

On 21 November 2026 our Fields page had no merge action. The row menu offered Edit field, Add field to screen, View field schemes, Contexts and default values and Delete. Atlassian's change feed lists duplicate field merging for the Jira Admin Agent, a Rovo beta for paid plans and company-managed spaces, rolling out since 16 November 2026. I didn't try it. So below is the route from Atlassian's merge two custom fields KB, which warns it can "irrevocably change issue data". Try it on a few work items first.

We built our rule over the REST API, so the labels below are the ones the rule editor showed afterwards (it calls rules "flows"). In the examples, customfield_14339 is the copy and customfield_13726 is the field we kept.

  1. On the Fields page, open the kept field's ... menu, select Add field to screen, and add it to the space's screens (we added ours over the REST API, so we haven't seen that dialog: pick every screen the space's work types use). Skip this and the rule writes nothing.
  2. Open Automation in Jira's settings (ours was at /jira/settings/automation) and create a rule scoped to the space, with the Scheduled trigger. Under Searches with:, enter this JQL. The copy's id goes in the "is not EMPTY" clause and the kept field's id in the "is EMPTY" clause. Ours ran every 5 minutes.
project = MIGF AND cf[14339] is not EMPTY AND cf[13726] is EMPTY
Enter fullscreen mode Exit fullscreen mode
  1. Add the action Edit work item fields, pick the field you keep, and set its value to the copy's smart value: {{issue.customfield_14339}}. The KB uses Copy from. Our Copy from action, built over the REST API, failed with an invalid configuration error, so we used the smart value.
  2. Turn the rule on and wait for its next scheduled run.
  3. Open a migrated work item and compare the two fields. They should hold the same value, and the JQL from item 2 should now return nothing.
  4. Turn the rule off.

A Jira Fields page searched for Customer ID showing Customer ID, Customer ID (migrated 2) and Customer ID (migrated), with the Delete Customer ID (migrated) dialog open.

Our first run said SUCCESS. It matched 3 work items, ran the edit 3 times and changed nothing. The original field wasn't on the space's screens. I added it, and the 04:45 run filled all 3. We merged a text field, and a select or user field stores a different value. The same KB also gives a CSV route. Its paste step "will overwrite all existing data" in the target column, so fill only the rows you mean to.

A tomato-red robot holding a sunflower gestures at a big yellow checkmark, while two blue robots crouch by three empty green crates and a violet chute pours green balls onto the floor next to them. A green robot with a wrench stands under a hanging lamp.

Step 5: Repoint filters, then move the copy to the trash

A deleted field leaves quiet holes. A JQL clause on a missing field can return 0 results without an error, which our audit tutorial on field ids shows in detail.

  1. List the filters your account can see that mention the copy's id:
curl -s -u "$EMAIL:$TOKEN" \
  "https://$SITE.atlassian.net/rest/api/3/filter/search?expand=jql&maxResults=100" \
  | jq -r '.values[] | select(.jql // "" | test("14339")) | "\(.id)\t\(.name)"'
Enter fullscreen mode Exit fullscreen mode

You should see the id and name of each filter to edit. No output means no filter you can see uses the field. The API returns 100 at a time (our site has 243 filters), so add &startAt=100 and repeat until isLast is true. It shows only filters your account can see, so ask filter owners to check private ones, and search for the field's name too.

  1. Change each filter's JQL to the field you keep. Our piece on filters that break after a migration covers the boards and dashboards built on them.
  2. On the Fields page, open the copy's ... menu and select Delete, then Delete field. The dialog tells you how many spaces lose the field.
  3. Open the Deleted fields tab. You should see the copy with a "Permanently deleting on" date 60 days out (ours said 20 January 2027). Until then, Restore brings it back "along with all of its data", in Atlassian's words on deleting and restoring a field.

For many copies at once, the REST API has POST /rest/api/3/field/{id}/trash, which put our test field in the trash with the same 60-day date. Avoid DELETE /rest/api/3/field/{id} for real data. Atlassian's API reference says it deletes the field "whether it is in the trash or not". Apps and integrations that store the field id outside Jira won't follow the merge, so check their settings too.

Why Jira renames a custom field to "(migrated)"

Atlassian's KB on JCMA duplicates and tracking entities gives the rule in two halves. If a field in your migration has the same name as one in the Cloud site and JCMA has a record of migrating it, "we will link your data to the existing entity". If there is no record, "we will modify the name by adding (migrated) to avoid duplicates and ensure there's no data loss (we cannot guarantee that a field with the same name is exactly the same field)".

The record is what matters. Names alone don't link. A field an admin created by hand in Cloud has no migration record, so a same-name field from Data Center collides with it, even when the two are identical. Renaming fields in Data Center can't fix that clash. Only the Cloud side, or the conflict rules in Step 2, can.

Copy product data follows the same rule. Atlassian's page on how data is linked between instances says an entity with the same name as one on the destination arrives "with the original name and a "(migrated)" tag". Both tools track custom fields, field configurations, screens, schemes, filters and workflows this way (13 entity types for JCMA and 15 for Copy product data, by our count of Atlassian's lists).

Atlassian's pages disagree on the numbering. The duplication doc shows "Customer ID(migrated 1)", one section of the KB lists "(migrated 1)", and both linking pages and another section of that KB show "(migrated 2)" after "(migrated)". Both of our runs produced "(migrated 2)" and never a "(migrated 1)".

The duplicates also cost something. Jira Cloud has enforced a limit of 700 fields per space since March 2026, counting the fields in the space's field schemes. Our copies arrived with a global context (all spaces), so each one counts in all of them. Fields in the trash don't count.

JCMA duplicate custom fields in a phased Data Center to Cloud migration

Our source was a fresh Jira Software Data Center 11.3.13 on PostgreSQL 16 on our Mac, with project MIGD, a "Customer ID" text field, a "Tier" select field with Gold and Silver, and 3 work items. The Cloud site already had a "Customer ID", a "Customer ID (migrated)" and a "Tier" from our other test.

Wave 1 took 5 minutes. It created "Customer ID (migrated 2)" and "Tier (migrated)", both with a global context, and put the values of MIGD-1 to MIGD-3 (CUST-001 to CUST-003) into them. It also brought the project's permission scheme in as "Default software scheme (migrated 2)" and its notification scheme as "Default Notification Scheme (migrated)". Schemes and screens named after the project kept their names, because nothing in Cloud had those names.

Before wave 2 I changed Tier's description in Data Center to see whether that would break the link. Atlassian's KB lists "different descriptions - even minor changes in the description text" as a reason fields don't match. Wave 2 moved project MIGE. Its work items carried Silver in "Tier (migrated)", with the same option id as wave 1. No new field appeared. The Cloud description didn't change either. So does the KB's description rule still apply? Maybe only to fields JCMA didn't create itself. On our one run, a field JCMA created stayed linked after a description edit, while the permission scheme came in again as "(migrated 3)".

The setup was slower than it should be, and you may hit the same snags. Jira 11.3.13 ships with JCMA 0.99.3, which only shows "Upgrade Migration Assistant" until you update it to 1.32.0 (released 16 November 2026). On our lab the update then failed with "Signature check failed!", because Jira 11 checks app signatures by default. On a real server, install Atlassian's Marketplace certificates in the Jira home's upmconfig folder, which has to belong to a different user from the one running Jira. I switched the check off. Fine for a throwaway lab. Not for a server you care about.

Duplicate fields after a Jira Cloud to Cloud migration (Copy product data)

Copy product data lives in Atlassian Administration under Data management, then Data transfer. It needs an organisation admin, on all Cloud plans. Our merge two Jira Cloud instances tutorial walks through the screens, so here I only cover the fields.

We built project MIGF on the source site with the same two fields and 3 work items, and created a "Customer ID" short text field by hand on the destination first. It was slow. The copy ran from 04:15 to 04:31 local time. That's 16 minutes against the review page's estimate of "< 1 minute". The finished plan also reported "Time taken 20,779 days", the same display bug we saw on 13 November.

"Customer ID" arrived as "Customer ID (migrated)" with all 3 values, CUST-1001 to CUST-1003. "Tier" arrived without a suffix, because the destination had no "Tier". Both got " (Migrated on 21 Nov 2026 02:24 UTC)" added to their descriptions.

Then I counted the destination's custom fields. It had about 721 before the copy and 1,375 after it. Only 2 of the new 654 belonged to MIGF. Of the other 652, 644 carried a "Migrated on 13 Nov 2026" stamp: our 13 November test had copied them from this site to the source site, and now they came back. The last 8 were the source site's own fields, like "Approvers", whose names also existed here. 7 of the new fields had a number, like "Actual start (migrated 2)", and 8 had the suffix twice, like "Approvers (migrated) (migrated)".

A cobalt-blue robot standing ankle-deep in an avalanche of identical paper sheets pouring out of a violet photocopier, holding one sheet up with tongs, while a tomato-red robot on a step ladder hands sheets down onto the pile.

MIGF used the default field configuration, where all global fields are available, and I think that is why they all rode along. That cause is my best guess.

If you copy data back and forth between sites, or from a sandbox to production, expect this. Atlassian's before you start page says that when you copy from a sandbox back to production "we create duplicate configurations". The fix Atlassian tested for this route, an early access program announced in November 2024, closed to new applicants on 5 December 2024. Its product manager wrote on 18 September 2025 that the capability "is not yet available", and our copy plan had no step for it.

Open questions from our runs

We ran one project per route. Each had a text field and a select field, so a few things stay open. I'll update this piece if a reader or Atlassian settles one.

  1. What REUSE and OVERRIDE do to the values on both sides. We left the rules blank and never uploaded the CSV.
  2. Whether a field in the trash still blocks its name in the next migration, which decides whether deleting an empty Cloud field first works.
  3. Whether the smart value in Step 4 works for select, multi-select and user fields. We merged a text field only.
  4. The KB's CSV route, which we didn't run.
  5. Whether a project on its own field configuration carries fewer global fields in Copy product data.

If it didn't work

The merge rule says SUCCESS but no values moved. The field you keep isn't on the space's screens. The rule editor showed our target as "customfield_13726 (deleted field?)" until we added it, and the failed run logged edit.issue.empty-issue-term-refresh for each work item.

INVALID_COMPONENT_CONFIGURATION in the rule's audit log. That came from our Copy from action built over the REST API. Set the value with the smart value {{issue.customfield_<id>}} instead.

Signature check failed! when updating JCMA on Jira 11. Install Atlassian's Marketplace certificates in <jira-home>/upmconfig/truststore, owned by a user other than the one running Jira. Our log said "UpmConfig Directory failed safety check!" when the owners matched.

JCMA shows only "Upgrade Migration Assistant". The bundled 0.99.3 won't start a migration. Update it from Manage apps.

The lookup in Step 1 returns 50 fields and stops. field/search caps a page at 50. Use the loop, which follows isLast.

What it cost us

The JCMA lab took about 30 minutes from download to the first migrated data, most of it the JCMA update and the signature problem. Each wave ran 5 to 9 minutes for 2 or 3 work items. The Copy product data run took 16 minutes, and the merge took 3 rule runs and about 12 minutes because of the two traps above. Cleaning up the 652 extra fields took a script of 655 REST calls. I'd rather spend that on a test site than on production, and I think you would too.

What you have now, and what I'd do

[[takeaways]]

  • What you set up. One field per name, holding the values the migration put in the copy, with your filters pointing at it and the copy in the trash for 60 days.
  • What to check on yours. The Deleted fields tab shows the copy with its date, and the JQL with your kept field's id and "is EMPTY" returns nothing.
  • What this doesn't cover. What REUSE and OVERRIDE do to values, select and user fields in the merge rule, and the KB's CSV route (the open questions above).

You have one field per name with its values, filters pointing at it, and the copy in the trash for 60 days. To check, open the Deleted fields tab: the copy should be there with its "Permanently deleting on" date. Then run project = MIGF AND cf[13726] is EMPTY with your kept field's id and your space key. It should return nothing, because every migrated work item now holds its value in the field you kept. Then run it with is not EMPTY. It should return the migrated work items (3 for us). If that also returns nothing, the id is wrong.

Before a JCMA wave I'd download the conflict CSV on a rehearsal site and decide REUSE or OVERRIDE for custom fields that already exist in Cloud. For Copy product data I'd compare the two sites' field names first, and I'd never copy back and forth between the same two sites (we did, and 644 of the 652 extra fields came from that round trip). If you've seen REUSE work on a same-name field with values on both sides, I'd like to hear how it went: send it to us through leanzero.net.


Originally published on leanzero.net. More Atlassian, Forge and local-AI write-ups at leanzero.net/blog, and if you're planning a migration or a Forge app, that's what we do: leanzero.net/services.

Top comments (0)