On this page:
|
...
|
What custom field contexts
...
are
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 deployed
Managing contexts mid-deployment is vital to successfully deploying custom fields between Jira Cloud sites. For a seamlessly working destination site, it’s important to be able to fine-tune how the source custom fields’ contexts will be deployed.
...
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 deployment:
...
Info |
---|
After confirmation, the CMJ Cloud reanalyzes the configuration and applies the transformations from the file. |
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 for transformation listing requirements.
Using the JSON transformations, you can map a source context to a selected destination context one or create a mapped source context as a new one on the destination. This allows you to 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 transformationssection.
...
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 deployment wizard, you can apply two types of transformations to contexts:
...
After that transformation, any existing mapping will be ignored.
...
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.
...
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
CMJ Cloud 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. CMJ Cloud, 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 deployment 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 deployment.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 deployment. As a result, CMJ Cloud will try to delete it. However, the context won’t be deleted if there are issues with option values. Instead, an error stopping the deployment 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 deployment.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 deployment 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.
...