Page tree
Skip to end of metadata
Go to start of metadata

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

Changed in versions 1.12-JX

The URL for export has changed in versions 1.12-JX of Project Configurator to:

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

See this page for examples for previous versions. If you are upgrading to version 1.12 of Project Configurator and you use automation scripts, remember to change the export URL in those scripts.

 

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:

ParametersPossible valuesNotes
filterUnusedCFtrueThis parameter is deprecated. It is kept for backward compatibility with versions 1.3.0 and earlier of the plugin. It is equivalent to setting "filterCFMode=filterUnusedCFStrict".
filterCFModeexportAllCFThe default, if no value is supplied for this parameter. Export all custom fields.
filterUnusedCFStrictFilter custom fields unused by the exported projects, as explained here 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 plugin versions older than 1.5.
filterUnusedCFExtendedFilter custom fields unused by the exported projects, as explained here.
userExportMode, groupExportModefullExportExport all (users or groups)
ignoreInvalidExport all but users or groups not found or not valid
doNotExportNo user or group will be exported.
jiraFilterExportModenoneNo filter will be exported (This is the default option, if nothing is specified)
globalExport only filters shared with all users
projectsExport only filters shared with projects being exported
global-or-projectsCombines two previous options: export filters that are shared globally or with exported projects.
sharedExport only filters that the owner has shared with somebody else
allAll filters (either private or shared) will be exported
jiraDashboardExportModenoneNo dashboard will be exported (This is the default option, if nothing is specified)
globalExport only dashboards shared with all users
projectsExport only dashboards shared with projects being exported
global-or-projectsCombines two previous options: export dashboards that are shared globally or with exported projects.
sharedExport only dashboards that the owner has shared with somebody else
allAll dashboards (either private or shared) will be exported
agileBoardsExportModenoneNo Scrum or Kanban board will be exported (This is the default option, if nothing is specified)
projectsExport only Scrum or Kanban boards associated to the projects being exported. Boards associated to a project appear under the project name at the project navigation panel (see an example image here).
allAll Scrum or Kanban boards will be exported

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:

Field nameValid valuesMandatoryDefaults to
projectConfigFileA file with a valid project configurationYes 
applyChangestrue, falseNofalse
createExtraProjectstrue, falseNofalse
smartCFContextstrue, falseNofalse
publishDrafts (new in v 1.13-JX)true, falseNofalse

continueOnDashboardFilterErrors

true, falseNofalse
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


NoEmpty. This means to load all object types

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.

export-error-check.bat
@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:

load-error-check.bat
@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

Some comments on previous .bat files

  • With the option -w "%%{response_code}" and the output redirection, curl writes the HTTP status code returned by the server to a temporary file. Its content is later fed into the variable STATUSCODE, whose value will be used to detect if the operation ended successfully or not.
  • The document returned by the server is always stored in the file specified by curl -o option.
  • In the case of an export, bear in mind that if successful the server returns a XML file with  the configuration. In case of error it returns a HTML page with information about the error. So, when an error is detected the script renames the file appending a .html suffix.
  • It would be possible to use curl -f option to detect if the server returned a HTTP status code with error (400 or higher), as was suggested in previous versions of this page. While that works, it has a big drawback: with -f curl  does not store the document returned by the server. As in the case of error the returned document is a HTML page with information about what went wrong, it would be quite difficult to find out what failed and how to fix it.

 

 

  • No labels

1 Comment

  1. Great, thanks José!