Edit Custom Field Contexts

This feature is available since Configuration Manager version 6.5.0

On this page:


When you create a custom field, Jira automatically generates a context for that custom field. Contexts allow you to set a default value for your custom field, as well as choose issues types and projects where the field will be visible. You can create many contexts for a single custom field. Read more about contexts in Atlassians’s Configuring a custom field document.

Managing contexts is a vital part of the custom field migration during your Jira configuration deployment. In many cases, in order to achieve smooth deployment and seamlessly working Jira system afterward, it might be necessary to change the contexts of existing custom fields during the configuration migration.

Depending on your needs or use cases, Configuration Manager for Jira offers different safe deployment options for custom field contexts as part of the Custom field context editing feature.

During configuration migrations, moving projects and test-staging-production, the default matching of contexts between source and target Jira system might not be satisfying and sufficient. Custom field context editing feature allows you to change the default deployment option (default matching between source and target Jira) for a custom field context.

When a modification in a custom field’s contexts (context added or existing context changed) is detected during configuration snapshot deployment, Configuration Manager offers you to choose between the following context editing options:

  • merge source context with different target context

  • deploy context as new on target

  • merge source context with its matching target context

When a context is changed or added for a specific custom field, there is a button in the deployment wizard that allows you to open a dialog to edit how the contexts will be deployed on the target Jira instance. Initially, in the dialog, Configuration Manager offers the default deployment options for each of the contexts from the snapshot:

  • If a context is added, it will be matched with the Create new context option.

  • If a context is changed, it is matched with a context on target.

Then, depending on your use cases, you can change the default options by choosing another option in the Current Jira Context field.

System Snapshots

Context editing is not available for system snapshots, and as a result, the edit field contexts button is not present.

How to Edit Contexts

  1. Log in as a user with the Jira System Administrators global permission.

  2. Navigate to the top right of the screen and choose Jira Settings > Configuration Manager.

  3. In the menu on the left, click Deploy.

  4. Start a deployment of a snapshot.

  5. On the Analyze phase of the snapshot deployment, click on the Fields tab.

  6. Choose a modified field and click the Edit field contexts button.

Button grayed out?

Editing custom field contexts is enabled only when the custom field is not locked and there are relevant matching contexts on target. Otherwise, the button will be grayed out and unclickable.

7. A dialog opens, allowing you to change the default context deployment option.

8. After you complete the context editing, a warning appears, reminding you that there are pending modified elements. To confirm the changes to a custom field’s contexts, click the Analyze button.

9. Continue and finish the deployment. After you click the Analyze button, Configuration Manager recalculates the diff of the configuration, and it presents all the changes you made to contexts.

Context Deployment Rules

You can match one source context to only one target context or create a new context.

When a target context is merged with a source context:

  • If some options on the target don't match with corresponding options in the source context, they will be disabled.

  • If some options match (by name/label), they will be untouched.

  • Context options from source that don't match options on target will be added.

  • Projects from the source context will be added to the target context. Each project added to a context is removed from any other context in case the project is used in another context (one project can be part of only one context).

The option for creating a new context is available for every custom field context, and it's offered by default if Configuration Manager finds no matching target context.

Project Context → Project Context

If you match a project context to a different context on target Jira:

  • The merged result will be with the target's context name.

  • For projects, the result will have both the projects from the source context and the ones from the target context.

  • Any other target context that has projects which are contained in the source context will have them removed, there might be context without any projects after this type of matching. And this will be reported in the diff UI and the audit log of the deployment

Project Context → Global Context

If you match a project context to a global context on the target Jira:

  • The merged result will be with the target's context name.

  • The merged result will remain Global context.
    All projects that are contained in the project context will be removed from other contexts for the Custom Field on target. This is so that the Result Context will be used for the same projects as on source.

Global Context → Project Context

If you match a global context to a project context on the target Jira:

  • The merged result will be with the target's context name.

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

  • The Global context will transition into project context. All the included projects in the snapshot will be assigned as projects for the source context. Assigning all source project to the context will ensure that the source context will remain relevant to the same projects as on source. So from now on the match is just like the use case: Project Context → Project Context.

Global Context → Global Context

If you match a global context to a global context on the target Jira:

  • The merged result will be with the target's context name.

  • The merged result will be a global context.

Any Context → Create New Context

An option for creating a new context is also available for each of the contexts. It is pre-selected if no default match is found on the target. If there was a default match and a new context is selected to be created, and the context is project-based, the projects will be removed from any other contexts that may have them, similar to the previous cases.

Audit Log

All changes you make to contexts during a configuration snapshot deployment are tracked in Audit Log.

Error Handling

When you deploy and match two contexts which will result in a context without projects on target, there is a warning message in the deployment wizard.

After you confirm the context changes using the Аnalyze button in the deployment wizard, the warning is displayed again to remind you about the change impact.