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.
...
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.
...
In a nutshell, this feature allows you to list and apply transformations to contexts from with the help of a JSON file. The transformations you can apply are:
...
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:
Create a migration.
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.
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.
Click Customize mapping to upload the JSON file with the changes.
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.
In the Analyze changes page, the custom fields whose contexts have been transformed should have the
tag.Status colour Yellow title CUSTOMIZE
| Info | ||||||
|---|---|---|---|---|---|---|
After confirmation, the Cloud Migration Tool reanalyzes the configuration and applies the transformations from the file. Each custom field whose context has been changed by the JSON file will have the
|
Guidelines for creating JSON context transformations
As described in the Step-by-step guide above, you can download a file that contains all the information about the custom field contexts and how they’ll be migrated to the Cloud. Then, you can either make changes to that file to include your desired context transformations, or you can construct your own file and apply either of the files to the configuration.
The applied file must always be in a JSON format. Also, there are some requirements on how to list the intended transformations in it. Check the guide we’ve prepared to get you started on building your transformations quickly.
For contexts, the transformations you can apply are mapping source and destination contexts and creating new destination contextscustom 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 this document’s the Use cases for context transformationssection.The important thing to note is that source
| Info |
|---|
Provide source context’s ID in the JSON file Source and destination contexts are matched by their IDs. |
...
Make sure you include the source context's ID in the JSON file |
...
to create or update |
...
a mapping. |
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:
...
With this transformation, you can map a source context to an existing destination context. This includes remapping an already mapped source context and or mapping new contexts to destination contexts. Simply provide the ID of an existing destination context in the following format:
...
After that transformation, any existing mapping will be disregardedignored.
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:
...
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:
Mapping a source context to a chosen destination context by idID
| Code Block | ||
|---|---|---|
| ||
{
"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"
}
}
]
}
]
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"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.
Mapping a source context to a chosen destination context by idID
| Code Block | ||
|---|---|---|
| ||
{
"source": {
"id": "customfield_10000"
},
"children": [
{
"contexts": [
{
"source": {
"id": "10000"
},
"transformation": {
"id": "10102"
}
}
]
}
]
} |
...
| Code Block | ||
|---|---|---|
| ||
{
"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:
A source context can be mapped to only one destination context or created as a new context within a given custom field.
If a source context is mapped to a chosen destination context:
The destination context’s options that don’t match any source context options will be deleted.
The source and destination contexts’ options that match (by name/label) won’t be modified.
The source context’s options that don’t match any of the destination context’s options will be added as new to that context.
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.
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 this document for instructions on how to resolve the problem to be able to continue the migration.Status colour Yellow title contexts without projects 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.
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 this document for instructions on how to resolve the problem to be able to continue the migration.Status colour Yellow title Contexts without projects
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.
...