3. PCJ extension types
On this page: |
Workflows
A Jira workflow may have conditions, validators, or post-functions that refer to other Jira objects, such as:
Offer this transition only to members of group X (condition);
Fail this transition if the user has not supplied a value for field Y (validator);
After the transition, update field Z with value V in issues that are linked to this one by link type L (post function).
These workflow features create two challenges when moving the workflow to a different instance:
Often, the workflow refers (internally) to fields Y, Z, or link type L by their IDs. This means these references must be translated to the equivalent IDs that are valid for the corresponding objects at the destination instance.
Any of these objects becomes a required part of the new configuration. It must be ensured that their description is extracted from the source instance and that they will be created or updated at the destination.
PCJ already supports and handles conditions, validators, and post-functions defined in Jira "out of the box" plus the most popular workflow apps at the Atlassian Marketplace, as explained in Specific information for some object types (see Conditions, Validators, and Post-functions).
If it is necessary to support other workflow apps, then it's time to create a PCJ extension for workflows. This is quite simple; you only have to specify where the references occur and what their content is (perhaps the ID of a field or the name of a group), and PCJ will take care of the rest.
See section 5 for a detailed explanation of how to create a workflow extension for PCJ.
Dashboard gadgets
When users configure dashboards in Jira, they will add gadgets to it. Each of these gadgets provides some functionality to the dashboard, for example, displaying all issues returned by a filter or statistics for a given category of projects.
The implication is that gadgets also contain references to other objects in Jira (filters, fields, issue types, categories, projects, etc.), and, as outlined in Workflows, these references must be handled appropriately during export and import. These references are created when the user configures the gadget. For each gadget type, the users create a set of user preferences where they specify, for example, from which project or filter the issues should be taken to create a graph or by which fields to group a given statistic.
PCJ supports gadgets defined by Jira "out of the box". If you want to migrate gadgets defined in a third-party app to other Jira instances, then you should use a PCJ extension for gadgets. The approach used to create these extensions is similar to the one used for workflow extensions. You only have to specify where the references occur (which type of gadget and in which user preference) and their content.
Section 6 provides an in-depth explanation, with examples, of how to create PCJ extensions for gadgets.
New custom entities
Apps often define new types of entities that do not already exist in Jira, for example, ScriptRunner for Jira offers many convenient features including behaviours. Behaviours let you customize the behaviour of fields in the user interface. A ScriptRunner Behaviour is not a custom field, screen, or workflow; it is a completely new type of object that does not exist in Jira out-of-the-box and only appears if ScriptRunner for Jira is installed in your instance.
In the same way, a test management app might introduce new types of objects like test cases, test plans, or test runs. For administrators that manage different instances of Jira, the objects belonging to new types are part of the content they would like to migrate when they are moving configuration or data between instances. Administrators will want to migrate the configuration of behaviours or their test management data to another instance and, if at all possible, without lots of manual work or having to develop ad-hoc scripts. Migrating these objects can become more challenging for different reasons:
The structure of objects can be complex. In most cases, these objects have a number of relationships between them. For example, a test case may be part of a test plan which, in turn, is used in a test run. A behaviour may reference a script and have some specific field configurations or mappings to projects.
This complexity extends beyond the boundaries of the app because there will be also relationships to/from objects defined by Jira itself. For example, each field configuration of a behaviour applies to a field in Jira, a project uses some behaviours, or test cases derived from specific Jira issues.
In cases like these, it is possible to leverage the power of PCJ to solve this complex problem if using a custom entity extension. These extensions make custom entities, like those described in the examples above, available to PCJ.
With the right extension, PCJ is able to export and import those items, managing all their links with other objects in the app or in Jira. The design of the SPI shields you from most of this complexity. As an SPI developer, you only need to implement the interfaces that describe the structure of the entities they want to handle in terms of how they are identified and their properties (including references to other objects). With this information, PCJ can handle all the dependencies and perform all export/import operations required for a successful migration.
Section 7 explains how to write a custom entity extension for PCJ, walking through all the relevant aspects of the SPI.