Page Comparison

What are custom field contexts

...

When you create a custom field, Jira automatically generates context within the field. Contexts are configuration elements that only live within the custom field’s configuration. Learn more about contexts in Atlassians’ Configure custom field context document.

...

• Global contexts - a custom field with such context will appear in all projects on the Jira Cloud site.

• Project-specific contexts - the custom field will be available only in the projects configured in the context.

Apply transformations to change how contexts will be migrated

Managing contexts mid-migration is vital to successfully migrating custom fields to the Cloud. For a seamlessly working Jira Cloud site, it’s important to be able to fine-tune how the Server/Data Center custom fields’ contexts will be migrated.

...

Learn more about the different context transformation use cases.

Step-by-step guide to transforming custom field contexts

To transform a custom field context during migration:

1. Create a migration.

2. On the Analyze changes phase, click the Download mapping button on the top right.
   You will get a JSON file with the default mapping for all projects, configuration elements (including contexts), and users in the migration scope.

   

3. Modify the JSON file to contain transformations of contexts. Check the guidelines about customizing contexts in the next section. Also, check the general syntax and rules for customizing mapping.

4. Click Customize mapping to upload the JSON file with the changes.

5. Review the number of changed elements in the dialog. If no elements with problems are reported, click Confirm to apply the transformations from the file.

6. In the Analyze changes page, the custom fields whose contexts have been transformed should have the

   Status
   colour Yellow title CUSTOMIZE

   tag.
   CMT-customize-mapping.mp4

Guidelines for creating JSON context transformations

As described in the Step-by-step guide above, you can download a file that contains all custom field context details for a deployment. Customize this file or create your own, and make sure it's in JSON format. Refer to our guide about how to use a JSON file for transformations.

...

The specific thing for contexts is that the transformation is always defined within a custom field record in the JSON file.

Required JSON records to transform contexts

With the Customize mapping option in the migration wizard, you can apply two types of transformations to contexts:

...

After that transformation, any existing mapping will be disregarded.

...

Edit a context in a downloaded JSON file

You can apply the transformations above by downloading the current mapping file and editing it. This is the case when you only add a transformation record without changing the default source and destination context records in the downloaded file. For more details about editing or constructing a mapping file, check this guide. To apply transformations to map or create new contexts using a downloaded JSON file, you need to insert a transformation record by following the syntax below:

...

{
    "source": {
        "id": "customfield_10000",
        "name": "Custom Field",
        "type": "com.demo.text"
    },
    "children": [
        {
            "contexts": [
                {
                    "source": {
                        "id": "10000",
                        "name": "Name",
                        "projectKeys": [
                            "Demo",
                            "Doc"
                        ],
                        "global": true
                    },
                    "destination": {
                        "id": "10100"
                    },
                    "transformation": {
                        "newObject": true
                    }
                }
            ]
        }
    ]
}          

...

Construct a JSON file with context transformations

You can also apply context transformations by constructing your own JSON file. In this case, you again need to have a transformation record, but you don’t need a destination record. The source record for the custom field and its content can contain only the IDs of these elements. That’s the minimum source configuration required for a transformation. For more details about editing or constructing a mapping file, check this guide.

To build a JSON file with a context transformation, you need to have a minimum set of data in the file. You still need to have a transformation record, but many of the records in a downloaded JSON file are not mandatory. The examples below list the minimum JSON records needed when mapping or creating new contexts in the destination.

...

{
    "source": {
        "id": "customfield_10000"
    },
    "children": [
        {
            "contexts": [
                {
                    "source": {
                        "id": "10000"
                    },
                    "transformation": {
                        "newObject": true
                    }
                }
            ]
        }
    ]
}

Rules for context transformations

Cloud Migration Tool applies the following rules for context transformations:

1. A source context can be mapped to only one destination context or created as a new context within a given custom field.

2. If a source context is mapped to a chosen destination context:

   1. The destination context’s options that don’t match any source context options will be deleted.

   2. The source and destination contexts’ options that match (by name/label) won’t be modified.

   3. The source context’s options that don’t match any of the destination context’s options will be added as new to that context.

3. The source context’s projects will be assigned to the destination context. The added projects will, at the same time, be unassigned from any other contexts of the custom field.
   

   Status
   colour Yellow title contexts without projects

   As a result of this logic, some contexts in the destination might lose all of their projects. Cloud Migration Tool, in this case, will remove such destination contexts. However, the context won’t be deleted if there are issues with option values. Instead, an error stopping the migration will appear after the configuration analysis finishes. In this case, you’ll be advised to visit this document for instructions on how to resolve the problem to be able to continue the migration.

4. A project can be present in only one of the contexts of a custom field.

Use cases for context transformations

Project-specific context → Project-specific context

If you map a source project-specific context to a destination project-specific context of your choice:

• The merge result will have the destination context’s name.

• The projects from the source and destination context will be set in the merge result.

• The source context’s projects will be removed from other destination contexts for the same custom field.
  

  Status
  colour Yellow title Contexts without projects

  A destination context might end up without any projects set during the migration. As a result, Cloud Migration Tool will try to delete it. However, the context won’t be deleted if there are issues with option values. Instead, an error stopping the migration will appear after the configuration analysis finishes. In this case, you’ll be advised to visit this document for instructions on how to resolve the problem to be able to continue the migration.

Project-specific context → Global context

If you map a source project-specific context to a destination global context:

• The merge result will have the destination context’s name.

• The merge result will still be a global context.

• The source context’s projects will be removed from other destination contexts of the same custom field.

Global context → Project-specific context

If you map a source global context to a destination project-specific context:

• The merge result will have the destination context’s name.

• The merged result will be a project-specific context (not global).

• The global context will first be converted to a project-specific source context. All projects in the migration scope will be set in this transformed context.

• After the merge, the projects in the transformed source and destination context will be set in the merge result.

• The source context’s projects will also be removed from other destination contexts for the given custom field.

• As a result of such mapping, some destination contexts might end up without any projects. This situation will be reported in the Analyze changes page.

Global context → Global context

If you map a source global context to a destination global context:

• The merge result will have the destination context’s name.

• The merge result will still be a global context.

Project-specific context → Create a new context

With Customize mapping, you can convert any mapped source project-specific context to a new destination context. Just keep in mind that the context’s projects will be removed from the other destination contexts of the same custom field.

...