Smart custom field contexts

Custom field contexts (aka "custom field configuration schemes") are a wonderful way to configure a custom field differently for different projects in JIRA. Smart custom field contexts is a new feature in Project Configurator that offers a selective handling of these contexts when importing a configuration.

In a few words...

Its goal is that the configuration import will only affect those projects that are actually described in the XML configuration file. The custom fields configuration for other projects, that exist previously in the target instance, will remain untouched.


Before explaining how the smart custom field contexts feature works, it is worth a quick look at the "standard" way Project Configurator handles custom field contexts. In the standard way the plugin replicates the complete custom field configuration (as it is described in the XML file) into the destination instance. This means that the custom fields in the target instance will be configured exactly as they were in the XML file, for all their contexts. This may affect other projects that were not imported with the configuration but are using those custom fields that changed as a result of the configuration import.

How Smart custom field contexts work

When smart custom field contexts are enabled, the plugin will perform these steps for every custom field in the XML file:

  1. It will consider only those contexts which affect any of the projects being imported. The rest of contexts will be ignored, "as if" they were not in the configuration file. If there are contexts for several projects and some of them are being imported and others are not, the plugin will treat these contexts "as if" they applied only to the imported projects.
  2. For the contexts in the actual custom field, if any of them applies both to imported projects and other projects, it will be changed, so that it applies only to projects that are not being imported.
  3. The plugin will match contexts in the XML file to existing contexts in the actual custom field, based on the projects to which the contexts apply. The matched contexts will receive the configuration that was defined for them in the XML file.
  4. The global context, i.e. the one that applies to "the rest of projects not referenced in other contexts" has a special treatment, as any change to this context is likely to affect potentially many projects whose configuration is not being imported. If the configuration in the XML file implies that the global context is used by any of the imported projects and importing it would change the existing global context, the plugin instead will create a new context for the imported projects that require it, leaving the existing global context untouched.


An example

Imagine this case:

  1. The XML file contains a custom field with a context for projects P1 and P2 (suppose these are the project keys)
  2. The only project exported in the XML file is P1.
  3. The target instance has a context for that custom field that applies to projects P1, P2 and P3.
  4. The plugin detects that applying the configuration associated to that context, would require changes in the target instance (for example, the custom field is a select list and its options would be changed)

When "smart custom field contexts" is enabled, the plugin would detect that the change to those options would impact on projects P1, P2 and P3. P2 and P3 are not being imported, so the plugin will modify the contexts so that only P1 is affected by the changes. It would do this by:

  • Changing the existing context in the target to apply only to P2 and P3
  • Creating a new context that applies only to P1, that will have the new options

Highly recommended...

If you are going to import a configuration with "smart custom field contexts" it is a very good idea that the XML configuration file was created with the option to filter custom fields not used by the exported projects. If you do not do it this way, you risk getting some custom fields configured especially for the projects in the XML file, even if they do not have anything to do with those projects.