Using Project Configurator with the Java API

On this page:

1 Overview
2 API Javadocs
3 Using Project Configurator from a Groovy script in ScriptRunner for Jira
4 Using Project Configurator from Java
5 Add dependency in the pom.xml
6 Access API components from your Java code
- 6.1 Declare the imported components in atlassian-plugin.xml
- 6.2 Using Atlassian Spring Scanner

Overview

Starting with version 2.3.7 of Project Configurator, it is possible to use the app services from a Groovy script in Script Runner for Jira (SR4J) or from any Java program (another app, for example) running within the Jira instance.

Project Configurator must be installed and licensed in your instance.

Once your code has been compiled, if you want to test it, it is necessary to have Project Configurator—version 2.3.7 or higher—installed and licensed in your development instance. Project Configurator jar files can be downloaded from the Marketplace.

For development purposes, it is possible to license Project Configurator with some of the timebomb licenses for app developers.

API Javadocs

Whether you are driving Project Configurator from a Groovy script or a Java class, you will need Javadoc to understand what classes, methods, etc., are available. The Javadoc jar files for each version of the API are published in our External Maven repository.

From Project Configurator version 3.3.1, the method getExportedFile from the interface ExportResult is deprecated. The method getExportedReturnFile should be used instead. This new method returns the export configuration file directly, so it is no longer necessary to write the XML string to a file. See our Java and Groovy examples.

Using Project Configurator from a Groovy script in ScriptRunner for Jira

To use Project Configurator’s services, you need to get an instance of the interface that provides the required operation:

ProjectConfigExporter, ProjectConfigImporter, ProjectCompleteImporter or ProjectCompleteExporter

In the examples below, those instances have been retrieved using a call to ComponentAccessor.getOSGiComponentInstanceOfType(…)

Project Configurator is able to run most operations in two modes: asynchronous and synchronous.

Methods that run in synchronous mode are explicitly marked in their name (like exportSynchronous(…) ).
On the other hand, methods that run asynchronously do not have any special name (like export(…) ).

Using Project Configurator from Java

Using Project Configurator from Java code (i.e., another app) has some extra requirements relative to usage from a Groovy script in SR4J. These specific requirements are described below.

It is also useful to look at the previous section with Groovy script examples, as those examples have been created with a coding style that is highly compatible with Java.

Add dependency in the pom.xml

First of all, you need to declare in your pom.xml file that your code depends on this API. This only requires adding this dependency to the XML:

pom.xml

<dependency>
<groupId>com.awnaba.projectconfigurator</groupId>
<artifactId>operations-api</artifactId>
<version>3.0.13</version>
<scope>provided</scope>
</dependency>

Do not use versions of the API older than 1.3.0. Those earlier versions were intended only for internal use and will not work with the examples on this page.

The jar artifact for the API is available from the same Maven repository as the Javadocs. If you want to access that Maven repository, add these lines to your pom.xml:

pom.xml

<repository>
<id>adaptavist-external</id>
<url>https://nexus.adaptavist.com/content/repositories/external</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
<releases>
<enabled>true</enabled>
<checksumPolicy>fail</checksumPolicy>
</releases>
</repository>

Access API components from your Java code

As mentioned, for the Groovy scripts, you will need to get the component objects that implement the API. This can be done in a variety of ways.

Declare the imported components in atlassian-plugin.xml

If your app is not using the Atlassian Spring Scanner, you must declare in its atlassian-plugin.xml file that it will import the components you need to run exports, imports, or other operations. For example, if you want to export configurations or obtain the graph of dependencies for configuration objects, you would need to add this line:

atlassian-plugin.xml

Using Atlassian Spring Scanner

In this case, you can inject the required dependencies to the API objects without the need to add an explicit component import declaration in atlassian-plugin.xml. Using the correct annotations will be enough:

YourClass.java