Merge one field into another

Merge fields copies the value of one custom field into another custom field of the same type, on every work item that has a value in the first and none in the second, and then lets you move the emptied field to Jira's trash. It is for a site that holds two fields for one thing, as often happens after a move to Jira Cloud. It is for Jira admins, it changes your work items as you, and it can be undone for 30 days.

Where to find it

What it changes in Jira and what it never changes

A merge writes to one field only: the field to keep, on each work item it copies to. It writes only where the field to keep is empty, and it never changes the field to empty or any other field of a work item. Each edit shows in the work item's history under your name and sends no email. Flows that start when a work item changes will run on these edits.

Under Look, TuneCraft can also prepare the field to keep. A preparation changes how Jira is set up (options, the spaces of a context, the screens that show the field) and never a work item. Each one asks you to confirm, and each can be undone.

Before you start

• You are a Jira admin, and the site has a licence or a trial. A merge counts as one of the trial's 10 changes for the tool. It is given back when nothing was written. A preparation is part of its merge and is not counted again, and an undo is never counted.
• Both fields are custom fields that Jira lists now. They are two different fields, neither is in Jira's trash, neither is locked by Jira, and neither is managed by an app.
• Both fields have the same type, and it is one of the types in the table below.
• Jira can search by both fields. A field without a search template cannot be used: the page says so, and you set a search template on the field in Jira.
• No other merge is unfinished on either field. TuneCraft runs one slice at a time on a site: while a slice of another merge is running, yours waits a moment.

When one of these does not hold, Pick says which, and nothing is changed.

Note: A value whose shape is not what its type needs, such as a date that is not a date, is never written. The work item is counted as refused for another reason.

Merge two fields

Step 1: Pick the two fields

Search Field to empty and Field to keep. Both are searchable lists of Jira's custom fields: you cannot type a name that Jira does not list. The first field's values are copied, and it can go to Jira's trash afterwards. The second receives the values, and only fields of the same type are offered. TuneCraft reads Jira's list 50 fields at a time, up to 8 pages, until it has found 25 fields of that type, so type part of a name to search. Select Look at this merge.

Step 2: Look

Look reads Jira and changes nothing. It shows, as Jira's approximate counts (measured) of the work items you can see:

• how many work items have a value in the field to empty;
• of these, how many have nothing in the field to keep: they are copied;
• of these, how many already have a value in the field to keep: they are left exactly as they are, with See them in Jira.

Work items you cannot see are neither counted nor changed. After the counts it shows:

• For fields with options, the options of the field to empty that the field to keep has in none of its contexts (the first 20 are named), and how many work items hold one of them and have nothing in the field to keep. Jira will refuse these.
• Screens: the screens that show the field to empty and not the field to keep, with a link to each in Jira (the first 20, from at most 500 screens read).
• Contexts: whether the field to keep applies to every space, or to some only. If some work items to copy are in a space where it does not apply, Jira will refuse them, and the page counts them. TuneCraft does not read the work types a context applies to, so Jira can still refuse a work item of another work type.
• The flows of the last scan that may start when a work item changes, with the automation steps they may use (estimated), and what the copy costs in Jira points and minutes (estimated): see What it costs in Jira points and how long it takes, below.
• How many changes your trial has left in this tool, during a trial.

TuneCraft does not read a board's card layout, a dashboard gadget, a workflow validator or another app: any of them may name the field to empty too. It does not copy or count archived work items, or work items in an archived space: Jira shows them only in its own list of archived work items.

The screens sentence is Jira's own behaviour: Jira can refuse to write the field to keep on a work item whose edit screen does not show it, but it does not always. So the field to keep is best on those screens before the copy. The page cannot tell which screen a work item uses, so it gives no count of work items refused for a screen, and a work item whose screen shows neither field may be refused too.

Look again reads again, and Change the fields goes back to Pick. When no work item has a value in the first field and none in the second, the page says there is nothing to copy.

Step 3: Copy

Select Copy the values…. The confirmation names the two fields with their ids, gives the three counts and says four things: each change shows in the work item's history under your name, no email is sent, flows that start when a work item changes will run, and you can undo it for 30 days. Select Start the copy.

TuneCraft counts again before it starts. It does not start when there are clearly more work items to copy than the Look said (more than 10, or 2%, whichever is more), or none: look again.

The copy runs from this page, 25 work items at a time. Before every slice TuneCraft checks both fields again. Then it reads the next work items, asks Jira for exactly those work items again, and writes the field to keep only on those that still have a value in the field to empty and nothing in the field to keep. A work item it does not find that way is skipped and counted, never written. The page shows how many work items are copied, left as they were, refused and not known.

Important: Jira has no conditional edit. A value someone types into the field to keep in the few seconds between TuneCraft's last look at a work item and its edit is replaced. The slice is small for that reason.

Step 4: Read the Result

The Result says how many work items were copied and how many were left exactly as they were: the field to keep had a value when TuneCraft looked again, or the field to empty had none. It then gives the work items Jira refused, by reason, and the edits that got no clear answer: see When Jira refuses a work item, below. It offers Undo this merge…, Open Changes, Merge other fields and, when the gate allows it, Move the emptied field to Jira's trash.

A result where every work item was refused or not known is shown as a warning. A second merge of the same two fields picks up what the first left: it copies only where the field to keep is still empty.

Prepare the field to keep

Under Look, Prepare the field to keep offers up to three preparations, each only when the Look found something for it. Each button opens a confirmation that names the two fields with their ids, says what will change in Jira and how it is undone. Nothing is prepared without your confirmation. After one, the Look reads again.

Each preparation changes Jira's configuration and never a work item. TuneCraft reads Jira again just before it writes, and leaves what changed since the Look. It never changes an option that exists, the order of options, a default value or any other field of a screen. It never creates a context or a tab, and never takes a space out of a context or a field off a screen except to undo its own change. It never deletes an option. Each is recorded in Changes with ids only.

Add the missing options

Add the missing options is for fields with options. It creates, in each context of the field to keep that you tick, the options of the field to empty that the field to keep has in none of its contexts.

• A text the field to keep has only as a disabled option is not created again: enable it in Jira, on the field's Options page.
• An option disabled in the field to empty is added only when a work item to copy holds it, and it is created enabled, because Jira takes no value for a disabled option.
• An option text longer than 255 characters is left. At most 500 options are added in one preparation, 100 a request: look again for the rest.
• It is not offered when the field to keep has more than 10 contexts, has none, or Jira cannot be read whole. The page says to add the options in Jira.

Undo disables the options TuneCraft created, and only those that are still enabled, whose text is unchanged and that no work item holds. Jira keeps a disabled option on the work items that have it. TuneCraft does not delete options. An option a work item holds, or that was renamed, stays enabled, and the change reads as partly undone.

Put the field on the screens

Add the field to the screens adds the field to keep to the tab of each screen that shows the field to empty and not the field to keep, right after the field to empty where Jira allows it. If Jira will not place it there, it is last on its tab, and the result says so. A screen that already shows the field is left alone. It removes no field, moves no other field and creates no tab.

It works 10 screens at a time, carries on by itself and waits when Jira asks. The Look's sentence on screens applies here as well: Jira can refuse to write the field on a work item whose edit screen does not show it, but it does not always, so the field is best on those screens before the copy, not only for people to see it.

Undo takes the field off exactly the screens TuneCraft added it to, and only where it is still there. It is refused while the merge stands: without the field on a screen, Jira can refuse edits of it there, so undo the merge first.

Add spaces to the field's context

Add the spaces to a context is for work items to copy that sit in a space where the field to keep does not apply, and that Jira would refuse. It adds those spaces (50 at most) to one context of the field to keep that is limited to spaces. If the field has several such contexts, you pick one.

• If the context is limited to some work types too, the spaces are added, and work items of other work types are still refused. The dialog says so.
• It never takes a space out of the context, changes a default value or creates a context, and never touches the contexts of the field to empty.
• When the field to keep applies to every space, through a global context, there is nothing to add and TuneCraft offers nothing here. Jira's own field context page now says that global contexts exist for all fields and can no longer be restricted to spaces; on a site where that is so, this preparation is not offered.

Undo takes exactly the spaces this change added out of the context, only where they are still there. It is offered after the merge is undone, or when no merge was made, because taking a space out of a context hides the values of the field to keep there; Jira keeps them. It also leaves the spaces in place when a work item there still holds a value in the field to keep. It never leaves the context with no space.

Pause, carry on and stop

The copy needs this page open: the page sends each slice. Pause stops after the slice that is running, and Carry on continues from where it got to. Stop here ends the copy there: TuneCraft reads the edits that got no clear answer once, closes the merge as stopped and leaves what was copied undoable.

If you close the tab, the page sends no more slices, so the copy stops where it got to. Open Merge fields again: the page offers your unfinished merge, to carry on or stop. Changes has Carry on, Undo and Open result on its row.

• Only the person who started a copy or an undo can carry it on. Any Jira admin can stop one, which writes nothing to Jira.
• An unfinished merge holds both fields: no other merge of either can start until it is carried on, stopped, or closed. TuneCraft closes a merge that nobody carried on for 30 days.
• When the hour's Jira points are spent, or Jira asks TuneCraft to wait, the page says until when and carries on by itself with the tab open.

A copy also stops by itself, and says why, when Jira refused more than 200 work items, more than 10 edits got no clear answer, many more work items now hold a value than the Look counted, a field changed or Jira refused a request for good. TuneCraft never sends an edit again after an unclear answer. Read the reasons, fix them in Jira, then merge the same two fields again.

When Jira refuses a work item

A refused work item is not changed: nothing else on it changed either. The Result gives one line for each reason.

Undo a merge

Undo is open for 30 days from the start of the merge. Any Jira admin can start it, and it is never counted in a trial.

Step 1: Choose Undo this merge

On the Result, or in Changes, select Undo this merge…. The confirmation reads what it will do and changes nothing yet, with the work items the merge copied to, and the estimated Jira points. If the emptied field is in Jira's trash, TuneCraft restores it first and says so. If it was deleted for good, there is nothing to compare the values with and the merge cannot be undone. If the field to keep is gone, there is nothing to clear.

Step 2: Confirm the undo

Select Undo the merge. For each work item the merge copied to, or that got no clear answer, TuneCraft reads both fields now. Where the field to keep still holds the same value as the emptied field, it clears the field to keep. Where it differs, the work item is left alone and counted as changed since: that is a person's own edit. No value is stored: the comparison with the emptied field is the proof.

• The emptied field stays restored after the undo. Flows that start when a work item changes will start again on these edits.
• Jira can take a few minutes to show the values of a field that was just restored. TuneCraft clears nothing until it can read them: it waits a minute at a time, at most 10 times, then stops and says so. The merge is not marked as undone, and Undo stays available: run it again later.
• A work item TuneCraft cannot see, or Jira refused or did not answer for, is counted and left, and the undo can be run again.
• The merge reads as undone when at least one work item was cleared and none is left that Jira refused, did not show or did not answer.

You can also undo the preparations from the same dialog, in this order: the screens, then the spaces, then the options.

Move the emptied field to Jira's trash

The emptied field has screens, contexts and values, so the rule of Fields for an unused field cannot pass. A merge has its own gate. Move the emptied field to Jira's trash is offered on the Result only when all of these hold:

• a merge of this field into the other is closed as done or partly done, and not undone;
• a search just now, as you, finds no work item with a value only in the emptied field;
• no flow of a full scan from the last 7 days uses the emptied field, and no filter of a Filters reading from the last 7 days names it.

When the gate refuses, the Result says which condition, with the count and a link: the work items left (Jira's search), the flows (Jira's automation) or the filters (Filters). Jira's search can take a few minutes to show a change, so a gate that refuses right after a copy may allow a moment later: select Check again.

Important: Archived work items, and work items in an archived space, and work items you cannot see, are not counted. Restore archived work items in Jira and merge again before you move the emptied field, or their values in it are lost when Jira deletes the field.

The confirmation says how many work items hold a value in both fields: the value in the emptied field goes with it, and Jira keeps it for 60 days. The move itself is Fields' own, with its record and its Undo: see Fields. If the emptied field is already in Jira's trash, the Result says so, and Restore is on the Trash page and in Changes. Delete for good stays as Fields describes it.

What it costs in Jira points and how long it takes

At about 4 points a work item, the hour's 2,400 points for work a person starts (see Limits and troubleshooting) copy about 600 work items an hour (estimated). A merge of 6,000 work items takes about 24,000 points, about 10 hours with the tab open. The Look says the minutes before you start. When the hour's points are spent, the copy waits for the next hour. It is the largest job TuneCraft starts: start it with the time it needs in mind.

What it cannot do

• It does not copy cascading select, group, version and space pickers, or any field of Jira Software or of an app. The page names the type and says it is not supported yet.
• It writes no option that does not exist in the field to keep. It does not map one option to another.
• It does not copy or count archived work items or work items in an archived space.
• It does not repair the filters that name the emptied field, and it does not read a board's card layout, a dashboard gadget, a workflow validator or another app. Check them before you move the emptied field.
• It does not use Jira's bulk edit, which sets one value on many work items, not each work item's own.
• It does not read the work types a context applies to, so it cannot predict a refusal for a work type.
• It does not delete options, and it does not change the type of a field.

What it changes in Jira and how to undo it

What it keeps

Logs carry counts only.

Related pages

• Fields: the fields, their copies and contexts, and Jira's trash.
• Privacy and data: what TuneCraft keeps, and for how long.
• Limits and troubleshooting: the budgets and limits, and what to do when a copy is refused.
• Licence and trial: the trial's limits.

Questions about the app? Write to info@plugincraft.ca.