Automating export and import of projects

Overview

This section explains how to drive Project Configurator from the command line so you can create scripts that export or import complete projects. The method is based on interacting with the Jira server by issuing HTTP requests to concrete URLs. You need a tool that lets you issue HTTP requests from the command line, such as wget or curl. If you are not familiar with wget or curl, it is recommended you first have a look at the manual for these products.

Some examples are provided below. Remember, export and import operations require permission from the system administrator.

These examples have been tested on Ubuntu Linux 16.04, and they use curl and xmllint. Both programs must be installed on the system where you are going to run the scripts; you can install them with the following commands:

In order to execute the scripts provided, copy them to a folder included in your machine’s path for executable files and make them executable.

Script versions 3.7.0 and newer

Download the following .zip file for our latest script versions for Project Configurator 3.7.0 or later:

The ZIP file contains the following scripts:

Auxiliary scripts

The auxiliary scripts are required by the Import and Export scripts:

• wait-task-script 

• status-checker-script 

• get-csrf-script

Export script

1. This is an example of an executable script that exports the complete project with key HER:

2. This is an example of an executable script that exports the project configuration of a project with key HER:

Import script

1. This is an example of an executable script that imports a complete project. For COMPLETE imports, the file must be placed before importing in "projectconfigurator" folder under directory $JIRA_HOME/import.

2. This is an example of an executable script that imports the project configuration of a project with key HER:

Script versions 3.6.2 and older

Download the following .zip file for our earlier script versions for Project Configurator 3.6.2 or older:

The ZIP file contains the following scripts:

Auxiliary scripts

The auxiliary scripts are required by the Import and Export scripts:

• wait-task-script 

• status-checker-script 

Export script

This is an executable script that exports complete projects. Run the export script using the following command: 

Import script

This is an executable script that imports complete projects.

Legacy import script versions earlier than 3.1.10 

Import script

Export options

• jira-host-url: Host part of the exporting instance base URL, including port if needed (for example, http://my-server:2990)

• jira-context-path: Context part of the exporting instance base URL (for example, "jira"). Note that jira-host-url + "/" + jira-context-path equals "Jira base URL" (for example, http://my-server:2990/jira)

• admin-user: Admin’s username

• admin-password: Admin’s password

• project-key [project-key2 …​]: Keys of the projects to export, at least one must be provided

• export-mode: COMPLETE for complete export or CONFIGURATION for exporting just configuration

• export-file-name: Name of the exported file; the file will be exported in "projectconfigurator" folder under directory $JIRA_HOME/export (for example 'exported-projects-10-04-2025-zip')

• export-options: Additional export options. Each export option must be specified as key=value, preferably enclosed in double quotes.

Import options

• jira-host-url: Host part of the importing instance base URL, including port if needed

• jira-context-path: Context part of the importing instance base URL

• admin-user: Admin’s username

• admin-password: Admin’s password

• import-file-name: Name of the file to be imported

  • For COMPLETE import - must be placed before importing in "projectconfigurator" folder under directory $JIRA_HOME/import;

  • For CONFIG-ONLY import - the XML file must be placed on the local machine where the scripts are executed. You could pass either the file name or the absolute file path.

• import-mode: COMPLETE for complete import or CONFIGURATION for importing just configuration

• import-options: Additional import options. Each import option must be specified as key=value, preferably enclosed in double quotes

Temporary files and error handling

Examples

Export example

We’re exporting the projects LOREM and IPSUM from the Jira Server located in 10.0.2.2:2990 into a file called scriptfile.zip, using the account admin:admin.

Import example

^{We’re importing the projects LOREM and IPSUM from a file called scriptfile.zip into the server located in 10.0.2.2:2990, using the account admin:admin.}

Error handling

Let’s look at a couple of examples of error traces and how to fix those errors.

Here, the trace ended with an http status: 500, and it states that we should check the response.html.

In the response.html, we see the following:

In this example, something in Project Configurator failed. After searching PCP’s wiki or contacting support, we find this error occurred because we tried to export a project with agile boards from a Jira instance with Jira Agile v6.7.6, and Project Configurator is only compatible with Jira Agile v6.7.7 or higher.

This trace ended with an HTTP status: 400. In response.html, we find the following:

An error occurred: File C:\Atlassian_tutorial\myPlugin\target\jira\home\import\projectconfigurator\wrongfile does not exist or Jira does not have permissions to open and read it.

This means the file name was wrong, it doesn’t exist, or it may be missing its extension.