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.
Supposing the base URL to your instance of JIRA is http://my-server/jira the URLs for exporting a project are:
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:
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:
|filterUnusedCF||true||This 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".|
|filterCFMode||exportAllCF||The default, if no value is supplied for this parameter. Export all custom fields.|
|filterUnusedCFStrict||Filter 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.|
|filterUnusedCFExtended||Filter custom fields unused by the exported projects, as explained here.|
|userExportMode, groupExportMode||fullExport||Export all (users or groups)|
|ignoreInvalid||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 (This is the default option, if nothing is specified)|
|global||Export only filters shared with all users|
|projects||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 (This is the default option, if nothing is specified)|
|global||Export only dashboards shared with all users|
|projects||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 (This is the default option, if nothing is specified)|
|projects||Export 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).|
|all||All 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:
Exporting configuration for project with key PB, with all custom fields, saving the output to a file named my-project-config.xml:
Exporting the same project, without users or groups and including authentication info in the URL:
Exporting all projects, filtering unused custom fields (as explained in this page):
Exporting configuration for project with key PB, with all custom fields, and including shared dashboards and all filters in the export:
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 name||Valid values||Mandatory||Defaults to|
|projectConfigFile||A file with a valid project configuration||Yes|| |
|publishDrafts (new in v 1.13-JX)||true, false||No||false|
Any of the following strings:
Issue link types
Issue type scheme
Field configuration scheme
Issue type screen scheme
Issue security scheme
|No||Empty. 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:
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.
The first operation should be getting a session cookie and saving it to a file:
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:
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:
A simulated load (remember that applyChanges and createExtraProjects default to false):
A real load that will not stop if an error is found in a filter or dashboard:
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.
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.
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:
This is a similar .bat file that launches load of a configuration file and checks the result, echoing different messages on success or error:
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
It could be called this way: