How to automate export and load of project configurations

This section explains how to drive Project Configurator from the command line, so that you can create scripts that export or load configurations. 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, as wget or curl. If you are not familiar with wget or curl, it is recommended you have a look first at the manual for these products.

Some examples are provided. They assume there is a system administrator in that JIRA instance with name "admin" and password "admin". Remember that the export and load operations require a user with system administrator permission.

These examples use curl and run on a MSDOS shell on a Windows 7 machine. You will have to introduce slight adaptations to run them on Linux, Unix or Mac OS X.

Exporting configurations

http://my-server/jira/secure/project-config-export.jspa?...

Supposing the base URL to your instance of JIRA is http://my-server/jira the URLs for exporting a project are:

http://my-server/jira/secure/project-config-export.jspa?project-key=XXX

where XXX is the key of the project you want to export.

If you want to export all projects in a single operation, leave the project key empty, as in:

http://my-server/jira/secure/project-config-export.jspa?project-key=

It is also possible to select some options regarding export of custom fields, users and groups, as explained in Advanced export options. This is achieved by adding additional parameters to the export URL:

Remember that fullExport is the default mode,  both for users and groups, if nothing is specified.

For example, if you want to prevent your export from failing due to invalid user names and do not want to export groups, you could launch this URL:

http://my-server/jira/secure/project-config-export.jspa?project-key=XXX&userExportMode=ignoreInvalid&groupExportMode=doNotExport

Examples

Exporting configuration for project with key PB, with all custom fields, saving the output to a file named my-project-config.xml:

C:\Users\OneUser>curl -o "my-project-config.xml" "http://my-server/jira/secure/project-config-export.jspa?project-key=PB&os_authType=basic" -u admin:admin

Exporting the same project, without users or groups and including authentication info in the URL:

C:\Users\OneUser>curl -o "my-project-config-filtered.xml" "http://my-server/jira/secure/project-config-export.jspa?project-key=PB&userExportMode=doNotExport&groupExportMode=doNotExport&os_username=admin&os_password=admin"

Exporting all projects, filtering unused custom fields (as explained in this page):

C:\Users\OneUser>curl -o "my-project-config-filtered.xml" "http://my-server/jira/secure/project-config-export.jspa?project-key=&filterCFMode=filterUnusedCFExtended" -u admin:admin

Exporting configuration for project with key PB, with all custom fields, and including shared dashboards and all filters in the export:

C:\Users\OneUser>curl -o "my-project-config.xml" "http://my-server/jira/secure/project-config-export.jspa?project-key=PB&os_authType=basic&jiraFilterExportMode=all&jiraDashboardExportMode=shared" -u admin:admin

Project configuration loading

Automating the load of project configurations is a bit more elaborate as you have to compose the fields in the load form.

These are the fields that make up the form:

If you want to ignore several object types, then you should specify several parameters doNotLoadObjects, each one with one of the names of the types to ignore.

The meaning of all the parameters in the upload form is explained in the page about How to import/load configuration files.

The URL for the load would be:

http://my-server/jira/secure/project-config-file-upload.jspa

This URL cannot be extended with authentication parameters (as we did when exporting), so the only option is to save previously a session cookie and reuse it for loading operations.

Examples

The first operation should be getting a session cookie and saving it to a file:

C:\Users\OneUser> curl  -u admin:admin --cookie-jar cookies.txt "http://my-server/jira/secure/Dashboard.jspa?os_authType=basic" --head

The file cookies.txt with the session cookie will be used in the next load examples. The first example loads a configuration with all its object types:

C:\Users\OneUser>curl -b cookies.txt "http://my-server/jira/secure/project-config-file-upload.jspa" -F "projectConfigFile=@D:\whatever-path\experimental-project-config-dump.xml" -F "applyChanges=true" -F "createExtraProjects=true"

Note the @ before the filename. This tells curl to incude its content as part of the form data.

A real load, that will create default projects as needed for custom field contexts, ignoring versions and components from the config file:

C:\Users\OneUser>curl -b cookies.txt "http://my-server/jira/secure/project-config-file-upload.jspa" -F "projectConfigFile=@D:\some-path\project-to-move-config.xml" -F "applyChanges=true" -F "createExtraProjects=true" -F "doNotLoadObjects=Versions" -F "doNotLoadObjects=Components"

A simulated load (remember that applyChanges and createExtraProjects default to false):

C:\Users\OneUser>curl -b cookies.txt "http://my-server/jira/secure/project-config-file-upload.jspa" -F "projectConfigFile=@D:\some-path\project-config-dump.xml"

A real load that will not stop if an error is found in a filter or dashboard:

C:\Users\OneUser>curl -b cookies.txt "http://my-server/jira/secure/project-config-file-upload.jspa" -F "projectConfigFile=@D:\some-path\project-to-move-config.xml" -F "applyChanges=true" -F "continueOnDashboardFilterErrors=true"

How to find out if the operation ran successfully

If you are automating several export or load operations, very likely you will need some means to find out from the script if each of the operations was performed correctly or there was an error. This section suggests a solution for this need, based on the HTML status codes returned by the server. In this page you can see the list of returned status codes.

Export

This is a .bat file that launches export of a project configuration and checks the returned HTML status code, taking different actions in case of successful export or error.

@echo off
set TEMPCOOKIESFILE=cookies-temp.txt
set LOGINURL="http://my-server/jira/secure/Dashboard.jspa?os_authType=basic"
curl  -u %3 --cookie-jar %TEMPCOOKIESFILE% %LOGINURL% --head > nul
curl -b %TEMPCOOKIESFILE% -s -o %1 -w "%%{response_code}" %2 > temp.txt
set /p STATUSCODE=<temp.txt
 
if %STATUSCODE% == 200 (echo "Export OK") else (
echo "Something went wrong"
ren %1 %1.html)

Its first parameter is the name of the file where the exported XML will be saved, the second the URL for export, and the third a string like username:password for authentication. So,it could be called like this:

C:\Users\OneUser>export-error-check output.xml "http://my-server/jira/secure/project-config-export.jspa?project-key=XXX" admin:admin

Loading

This is a similar .bat file that launches load of a configuration file and checks the result, echoing different messages on success or error:

@echo off
set TEMPCOOKIESFILE=cookies-temp.txt
set LOGINURL="http://my-server/jira/secure/Dashboard.jspa?os_authType=basic"
set LOADURL="http://my-server/jira/secure/project-config-file-upload.jspa"
 
curl  -u %2 --cookie-jar %TEMPCOOKIESFILE% %LOGINURL% --head > nul
curl -o "load-trace.html" -w "%%{response_code}" -b %TEMPCOOKIESFILE% -F "projectConfigFile=@%1" -F "applyChanges=true" -F "createExtraProjects=true" %LOADURL% > temp.txt
set /p STATUSCODE=<temp.txt
 
if %STATUSCODE% == 200 (echo "Load OK") else (echo "Something went wrong")

This script leaves the load trace in a file called load-trace.html. Its first parameter would be the configuration file to load, and the second one the authentication string with username:password.


It could be called this way:

C:\Users\OneUser>load-error-check new-project-config.xml admin:admin