Context Transformations

On this page:

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.

Contexts allow you to set combinations of projects and issue types where a custom field will be available. Moreover, you can specify default values and options for these combinations. With that, you can have different default values and options when using the custom field in different projects and issue types. You can achieve that by creating multiple custom field contexts to set your preferences.

It’s important to note that there are two types of contexts:

• 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.

Cloud Migration Tool looks for matches between source and destination contexts during migration. The source context will be created as new on the Cloud site if no match is found. However, if there is a match, the source and destination contexts will be linked (mapped). We call this event default mapping. As a result, the source context, its values, and options will be merged into the destination context it’s mapped to. Learn more about the rules defining how this happens.

The default mapping also indicates whether the source context will be created as new on the destination. We know that the default mapping of your contexts offered by Cloud Migration Tool might only meet some of your configuration needs. We’ve created the Customize mapping feature to give you the flexibility to achieve your migration goals. It gives you control over how projects, configuration elements, and users, including contexts, will be migrated to the Cloud. Learn more about the Customize mapping feature.

In a nutshell, this feature allows you to list and apply transformations to contexts with the help of a JSON file. The transformations you can apply are:

• Creating a source context as a new destination context.

• Mapping a source context to a destination context of your choice.

• Remapping an already mapped context to a different destination context.

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 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.

Using transformations, you can map a source context to a selected destination one or create a mapped source context as a new one on the destination. Read more about the context transformations you can perform. This way, you can change existing context mappings, set a mapping for new contexts, or transform a mapped context to a new destination context. You can find information about the logic of what happens with the source and destination context configurations in the Use cases for context transformations section.

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:

• Mapping a source context to a selected destination context

• Creating a new destination context

Map contexts by ID

With this transformation, you can map a source context to an existing destination context. This includes remapping an already mapped source context or mapping new contexts to destination contexts. Simply provide the ID of an existing destination context in the following format:

"transformation": {
    "id": "100123"
}

Create a new context

With this transformation, you can transform the mapped source contexts into a new destination context. You need to add the following record for a given context to the JSON file to achieve the transformation:

"transformation": {
    "newObject": true
}

After that transformation, any existing mapping will be ignored.

Rename a context

With this transformation, you can change the name of a destination context. You need to add the following record for a given context to the JSON file to achieve the transformation:

"transformation": {
    "name": "new context name"
}

After that transformation, any existing mapping will be disregarded.

Editing 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:

Mapping a source context to a chosen destination context by ID

{
    "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": {
                        "id": "10102"
                    }
                }
            ]
        }
    ]
}

Creating a source context as new in the destination

{
    "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
                    }
                }
            ]
        }
    ]
}          

Constructing 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.

Mapping a source context to a chosen destination context by ID

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

Creating a source context as a new destination context

{
    "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.
   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 /wiki/spaces/DCMFJC/pages/143491194 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.
  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 /wiki/spaces/DCMFJC/pages/143491194 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.

By default, if no match is detected in the destination and there is no mapping, the source context gets created as a new one in the destination.

GLOBAL CONTEXTS Cloud Migration Tool doesn’t allow transforming a source global context to a new one in the destination. If you upload a JSON file with such a transformation, an error will appear, stopping you from applying the transformation.