8. Testing your PCJ extensions

Test the migration

 Of course it is necessary to test that configuration objects are actually moved to a target instance of Jira. At the end of the day, that is what 99% of the users will want the extension to do for them.

The following steps may help you to test this in a relatively fast way:

Create the configuration objects you want to move in your development instance

Going back to the gadget extension example, you would create a dashboard that contains a gadget of the type Show Saved Filter with Columns and configure it with a valid filter.

Export a configuration containing those objects

Export these objects and check that the export completed without errors or warnings. If you look at the part of the XML file that corresponds to those objects, you should notice that instance-specific references (usually, all those that use IDs to refer to other objects) have been rewritten as instance-independent strings. Continuing with the gadget example, you would see a description like:

Exported file

Remember that before the extension existed, this was exported with a filter ID, which would have been useless when moved into a different instance. Now, that has been replaced by the filter owner and name, which will be used at the destination instance to rebuild the reference correctly.

Delete the configuration object and its dependencies and simulate the import of the exported file

To save the trouble of having two different Jira instances for testing, you could remove the created gadget and the filter it refers to from the development instance and then import the exported file into the same instance again. Run an import simulation first. You should see something like this (expanding the sections which are relevant to those objects):

Open

Note that there are two changes planned to create both the missing gadget and the missing filter. Note also that the details for the gadget refer to the filter by its owner and name, not by its ID.

Disable creation of the referred object and recalculate

We know that the operations to create the gadget and the filter are logically related: if the filter were missing then it would not be possible to create the gadget, as it requires that filter to be properly configured. You can test this in the import simulation. Disable the creation of the filter by clicking the green action icon. It will be greyed out. Click the Recalculate button. The results appear similar to the following:

Open

Note that after disabling the changes on filters (they are greyed out), the creation of the gadget has a red box (this means an error) that says a filter with the required owner and name cannot be found.

Enable operations and run the actual import

So far, nothing has changed in Jira. You are still working with a simulation; it is like a preview of the changes, but none of them have actually occurred.

In the next step, re-enable changes to the filters and click Apply Configuration. This will apply the changes to your source Jira instance. The tree with the actual changes will be displayed:

Verify that the changes displayed match what you expected. They should be the same as those previewed in the simulation. Finally, check the dashboard in Jira and verify that the new gadget has been created with the correct configuration. Make sure the gadget is configured for a new filter, also created by the import, called "Due this week (RR)" and owned by user "admin".

Use the object dependencies report

The Object Dependencies report is a feature of Project Configurator that analyses dependencies between configuration objects in any instance of Jira.

In the case of the workflow examples discussed in this guide, you will notice the following "used by" relationships exist:

• User "jsmith" is used by the "New service workflow" (as it is used in a post-function of the workflow)

• Custom field "Release cut-off date" is used by the "New service workflow" (as it is used in a condition of the workflow)

Integrations with other apps are designed to work seamlessly with this feature. So, if you run the Object Dependencies report, you will see these relationships shown in the report, for example:

Note this can be quite useful for testing references between objects. Verifying the Object Dependencies report is likely the quickest and easiest way to check references are working as expected.

Pro Tip: Create the extension in two stages

 Creating the extension in two stages simplifies both the implementation and the testing.

When creating a custom entity extension, you can exclude from the initial implementation the methods that actually create or delete objects or set any of its properties. These methods will only be used during a real import, so the following operations should work correctly for the related custom entities, even when those methods are not yet implemented:

• Export

• Object dependencies report

• Import conflict detection

• Simulated import

This lets you partially implement the support for some custom entity, test that partial implementation, and later, with the confidence that a substantial part of the extension is already correct, proceed to complete the "create / delete / update" methods.

Use the Jira log if necessary

 It is possible to extract a lot of useful information from the Jira log file. If this is required, then set the log level to DEBUG for the package com.awnaba.projectconfigurator. See Change Logging Levels in Jira Server to learn how to temporarily change the log level for specific packages in Jira. 

After setting the log level to DEBUG, run any operation with Project Configurator, and you will see the increased content in the log file. For example, in the case of export with the workflow extension discussed in this guide, you will see entries like these:

Example Log file

Note the following details:

• /secure/project-export!export.jspa is the relative URL where the export was launched from

• There are entries that mark when Project Configurator starts searching for extensions and a specific one for each extension

• There are also entries that show when the dynamic Spring context for each extension is started

• The other entry shows that this workflow extension defines two extension points (one for the condition and another for the post-function)

• For each extension point, it is reported when its processing begins and ends and the number and content of occurrences found for each workflow

Exploring the log files in this way can be useful when the extension appears not to work or even when it does not exist. This is often caused by a problem that prevents the starting of its dynamic Spring context. In these cases, Project Configurator will simply ignore the offending extension and continue with the rest of the operation.