Automating export and import of projects

Owned by Rosen Marinkov
Last updated: May 21, 2024 by Stanley Neychev
35 min read

On this page:

Overview

You’ll need version 3.0.0 or higher of Project Configurator. 

3.7.0 Update: Security vulnerabilities fixed in accordance with our bug bounty program. These vulnerabilities affect all prior versions of Project Configurator up to and including 3.6.2. We strongly advise that you upgrade to version 3.7.0 or later. See the 3.7.0 release notes for more information.

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:

apt get update apt get install curl apt get install libxml2-utils

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

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

sh export.sh jira-host-url jira-context-path admin-user admin-password export-file-name export-mode project-key1 project-key2 ... -O export-options

Import script

This is an executable script that imports complete projects.

This 3.7.0 script version requires that you update the command used to invoke the import/export scripts. If you are upgrading, refer to the usage command at the top of the related scripts. It is also provided as a snippet below.

 

sh import.sh jira-host-url jira-context-path admin-user admin-password import-file-name import-mode [-O import-options ...]

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

 

Command 

It is launched with the following command:

 

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: Only for COMPLETE export. Name of the exported file; remember it will be left in "projectconfigurator" folder under directory $JIRA_HOME/export (for example 'exported-projects-10-04-2017-zip')

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

Parameters

Possible Values

Notes

Parameters

Possible Values

Notes

attachmentMode

automatic

Attachments will be included in the exported ZIP file (This is the default option)

manual

You’ll need to copy the source Attachments to the target before launching a complete import.

filterUnusedCF

true

This parameter is deprecated. It is kept for backward compatibility with versions 1.3.0 and earlier of the app. It is equivalent to setting "filterCFMode=filterUnusedCFStrict".

filterCFMode

exportAllCF

Export all custom fields.

filterUnusedCFStrict

Filter custom fields unused by the exported projects, as explained Filtering Unused Custom Fields, but without taking into account whether there are issues in the project with values for that custom field. This option is deprecated, it is kept only for backwards compatibility with app versions older than 1.5.

filterUnusedCFExtended

The default. Filter custom fields unused by the exported projects, as explained in Filtering Unused Custom Fields.

userExportMode, groupExportMode

fullExport

Export all (users or groups)

ignoreInvalid

The default. Export all but users or groups not found or not valid

doNotExport

No user or group will be exported.

jiraFilterExportMode

none

No filter will be exported

global

Export only filters shared with all users

projects

The default. Export only filters shared with projects being exported

global-or-projects

Combines two previous options: export filters that are shared globally or with exported projects.

shared

Export only filters that the owner has shared with somebody else

all

All filters (either private or shared) will be exported

jiraDashboardExportMode

none

No dashboard will be exported

global

Export only dashboards shared with all users

projects

The default. Export only dashboards shared with projects being exported

global-or-projects

Combines two previous options: export dashboards that are shared globally or with exported projects.

shared

Export only dashboards that the owner has shared with somebody else

all

All dashboards (either private or shared) will be exported

agileBoardsExportMode

none

No Scrum or Kanban board will be exported

projects

The default. Export only Scrum or Kanban boards associated with the projects being exported. Boards associated with a project appear under the project name in the project navigation panel (see an example image).

all

All Scrum or Kanban boards will be exported

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; remember it must be placed before importing in "projectconfigurator" folder under directory $JIRA_HOME/import

  • 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

Field Name

Valid Values

Mandatory

Defaults to

Field Name

Valid Values

Mandatory

Defaults to

attachmentsPath

A directory path with project attachments

If you selected to move Attachments manually, introduce the Attachments path where you copied them

Yes (for complete imports)



projectConfigFile

A file with a valid project configuration

Yes



allowDifferentJiraVersionData

true, false

No

false

applyChanges

true, false

No

false

continueOnDashboardFilterErrors

true, false

No

false

createExtraProjects

true, false

No

false

doNotLoadObjects

Any of the following strings:

  • Versions

  • Components

  • Role members

  • Users

  • Groups

  • Project roles

  • Priorities

  • Resolutions

  • Issue link types

  • Statuses

  • Event types

  • Category

  • Issue types

  • Issue type scheme

  • Custom fields

  • Field configurations

  • Field configuration scheme

  • Screens

  • Screen schemes

  • Issue type screen scheme

  • Workflows

  • Workflow scheme

  • Permission scheme

  • Notification scheme

  • Issue security scheme

  • Filters

  • Dashboards

No Empty. This means loading all object types

publishDrafts (new in v 1.13-JX)

true, false

No

false

smartCFContexts

Temporary files and error handling

These scripts create two temporary files in the same directory where they have been invoked. These files are cookies.txt (it holds the authentication cookie for the session in Jira) and response.html (it keeps the last HTML response received from Jira).

Scripts include a basic level of error handling. If any of the interactions with the server return an error HTML status, the script will stop and display the error status with its intended meaning. The last HTML response (that came with the error HTML status) will be left in the response.html file.

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.