Interact with Configurations

Get child configurations of specified configuration

Syntax

A list of child configurations can be accessed by parent configuration id using http GET method through below url:

http://localhost:8810/rest/configurations?parent_id=<parent configuration id>

Here <parent configuration id> represents id of the parent configuration. The response is of mime type application/xml and the content is brief xml representation of list of all child configurations.

warning

For performance reason, only brief information of the configuration will be returned here, including id, name, description, schedule, runMode, errorMessage, and parent id. You may get the full xml representation using id if necessary.

Security

Only configurations accessible by current user (specified in http BASIC authentication) will be returned.

Demo

Below curl command demonstrates how to get child configurations under the configuration with id of 1:

curl -u admin:admin http://localhost:8810/rest/configurations?parent_id=1

Get all descendent configurations of specified configuration

Syntax

All descendent configurations can be accessed by parent configuration id using http GET method through below url:

http://localhost:8810/rest/configurations?parent_id=<parent configuration id>&recursive=true

Here <parent configuration id> represents id of the parent configuration. The response is of mime type application/xml and the content is brief xml representation of list of all descendent configurations.

warning

For performance reason, only brief information of the configuration will be returned here, including id, name, description, schedule, runMode, errorMessage, and parent id. You may get the full xml representation using id if necessary.

Security

Only configurations accessible by current user (specified in http BASIC authentication) will be returned.

Demo

Below curl command demonstrates how to get descendent configurations under the configuration with id of 1:

curl -u admin:admin "http://localhost:8810/rest/configurations?parent_id=1&recursive=true"

Get all configurations in the system

Syntax

All configurations in the system can be accessed using http GET method through below url:

http://localhost:8810/rest/configurations?recursive=true

The response is of mime type application/xml and the content is brief xml representation of list of all configurations.

warning

For performance reason, only brief information of the configuration will be returned here, including id, name, description, schedule, runMode, errorMessage, and parent id. You may get the full xml representation using id if necessary.

Security

Only configurations accessible by current user (specified in http BASIC authentication) will be returned.

Demo

Below curl command demonstrates how to get descendent configurations under the configuration with id of 1:

curl -u admin:admin "http://localhost:8810/rest/configurations?recursive=true"

{Interact+with+Configurations}

Access configuration by id

Syntax

Configuration can be accessed by id using http GET method through below url:

http://qb-server:8810/rest/configurations/<configuration id>

Here <configuration id> stands for id of the configuration. The response is of mime type application/xml and the content is xml representation of the configuration.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous does not have the ACCESS_SETTINGS permission of the requested configuration.

Demo

Below curl command demonstrates how to get xml representation of configuration with identifier 1 (the root configuration):

curl -u admin:admin http://localhost:8810/rest/configurations/1

Access configuration path by id

Syntax

Configuration path can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/path

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of the configuration path name.

Security

Any user can access this service including anonymous.

Demo

Below curl command demonstrates how to get path name of configuration with id 2:

curl http://localhost:8810/rest/configurations/2/path

Access configuration name by id

Syntax

Configuration name can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/name

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of the configuration name.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access the requested configuration.

Demo

Below curl command demonstrates how to get name of configuration with id 2:

curl -u admin:admin http://localhost:8810/rest/configurations/2/name

Access configuration description by id

Syntax

Configuration description can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/description

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of the configuration description. Status code 204 (No Content) will be returned if the configuration does not have description.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access the requested configuration.

Demo

Below curl command demonstrates how to get description of configuration with id 2:

curl -u admin:admin http://localhost:8810/rest/configurations/2/description

Access configuration error message by id

Syntax

Configuration error message can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/error_message

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of the configuration error message. Status code 204 (No Content) will be returned if the configuration is not in error.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access the requested configuration.

Demo

Below curl command demonstrates how to get error message of configuration with id 2:

curl -u admin:admin http://localhost:8810/rest/configurations/2/error_message

Access configuration run mode by id

Syntax

Configuration run mode can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/run_mode

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of configuration run mode. Status code 204 (No Content) will be returned if run mode is inherited from parent configuration.

Security

Any user can access this service including anonymous.

Demo

Below curl command demonstrates how to get run mode of configuration with id 2:

curl http://localhost:8810/rest/configurations/2/run_mode

Access configuration schedule by id

Syntax

Configuration schedule can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/schedule

Here <configuration id> stands for id of the configuration. The response is of mime type application/xml and the content is XML representation of configuration schedule. Status code 204 (No Content) will be returned if schedule is inherited from parent configuration.

Security

Any user can access this service including anonymous.

Demo

Below curl command demonstrates how to get schedule of configuration with id 2:

curl http://localhost:8810/rest/configurations/2/schedule

Access average build duration of configuration by id

Syntax

Average build duration can be accessed by configuration id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/average_duration?from_date=<from date>&to_date=<to date>

Here <configuration id> stands for id of the configuration, and one can optionally limit scope of build for calculation via query parameter from_date and to_date . Date is of format yyyy-MM-dd, for example: 2009-11-12. The response is of mime type plain/text and the content is milli-seconds of average build duration.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access the requested configuration.

Demo

Below curl command demonstrates how to get average duration of configuration with id 2:

curl -u admin:admin http://localhost:8810/rest/configurations/2/average_duration

Access build success rate of configuration by id

Syntax

Build success rate can be accessed by configuration id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/success_rate?from_date=<from date>&to_date=<to date>

Here <configuration id> stands for id of the configuration, and one can optionally limit scope of build for calculation via query parameter from_date and to_date . Date is of format yyyy-MM-dd, for example: 2009-11-12. The response is of mime type plain/text and the content is an integer in the range of 0~100, with 0 stands for 0%, and 100 stands for 100%.

Security

You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access the requested configuration.

Demo

Below curl command demonstrates how to get success rate of configuration with id 2:

curl -u admin:admin http://localhost:8810/rest/configurations/2/success_rate

Access parent configuration by id

Syntax

Parent configuration can be accessed by id using http GET method through below url:

http://localhost:8810/rest/configurations/<configuration id>/parent

Here <configuration id> stands for id of the configuration. The response is of mime type plain/text and the content is string representation of id of parent configuration. Status code 204 (No Content) will be returned if the configuration is root configuration and does not have parent.

Security

Any user can access this service including anonymous.

Demo

Below curl command demonstrates how to get parent of configuration with id 2:

curl http://localhost:8810/rest/configurations/2/parent

Update configuration

Syntax

Configuration can be updated by posting xml representation of the configuration to below url:

http://localhost:8810/rest/configurations

Please note that the parent element denotes id of the parent configuration.

Normally you do not need to create the xml from scratch: you may retrieve full xml representation of the configuration using configuration id, modify certain parts of the xml and post back to above url.

The response is of mime type text/plain and the content is string representation of the configuration id being updated.

warning

If you want to change value of secret elements (elements with attribute "secret=encrypt", including repository passwords, secret variable values, etc.), please make sure to remove the "secret" attribute and then supply a plain text password; otherwise, QuickBuild will think that the supplied password has already been encrypted.

Security

You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have EDIT_SETTINGS permission on the requested configuration.

Demo

We will use curl to demonstrate how to modify description of configuration root/test:

1. Retrieve id of configuration root/test using id service:

   curl http://localhost:8810/rest/ids?configuration_path=root/test

2. Retrieve full xml representation of configuration root/test into a temp file using below command:

   curl -u admin:admin http://localhost:8810/rest/configurations/<configuration id> > tempfile.xml

   Here <configuration id> needs to be replaced with query result of first step.

3. Edit tempfile.xml and change the description property to desired value (or add description element if it does not exist).

4. Post back modified content using below command:

   curl -X POST -u admin:admin --data-binary "@tempfile.xml" http://localhost:8810/rest/configurations

Create configuration

Syntax

Configuration can be created by posting xml representation of the configuration to below url:

http://localhost:8810/rest/configurations

Please note that:

1. The posted xml should NOT contain the id element; otherwise, QuickBuild will treat the post as an update to the configuration with that id.
2. The parent element denotes id of the parent configuration.
   Normally you do not need to create the xml from scratch: you may retrieve xml representation of a templating configuration using various configuration access methods, remove the id element, modify certain parts and post back to above url.
   The response is of mime type text/plain and the content is string representation of id of the newly created configuration.
3. Secret elements (Elements with attribute "secret=encrypt" in XML representation of an existing configuration, typically they are repository passwords, secret variable values, etc.) should not contain the "secret" attribute; otherwise QuickBuild will think that the password has already been encrypted. However if you creating configuration by copying existing one and want to remain the passwords, the "secret" attribute should then be preserved.

Security

You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have ADD_CHILDREN permission on the parent configuration.

Demo

We will use curl to demonstrate how to create a new configuration root/test-copy by copying the configuration root/test.

1. Retrieve id of configuration root/test using id service:

   curl http://localhost:8810/rest/ids?configuration_path=root/test

2. Retrieve full xml representation of configuration root/test into a temp file using below command:

   curl -u admin:admin http://localhost:8810/rest/configurations/<configuration id> > tempfile.xml

   Here <configuration id> needs to be replaced with query result of first step.

3. Edit tempfile.xml , remove the id element, and change the name element to be test-copy

4. Post back modified content using below command:

   curl -X POST -u admin:admin --data-binary "@tempfile.xml" http://localhost:8810/rest/configurations

Copy configuration (available since 4.0.72)

Syntax

Configuration can be copied via GET method like below:

http://localhost:8810/rest/configurations/<configuration id>/copy?parent_id=<parent id>&name=<name>&recursive=[true|false]

Here:

1. The <configuration id> has to be replaced by id of the configuration to be copied.
2. The <parent id> has to be replaced by id of the parent to place newly copied configuration.
3. The <name> has to be replaced by name of the newly copied configuration.
4. Specify parameter recursive=true to copy specified configuration and all its descendant configurations recursively; otherwise, only the configuration itself will be copied.

The response is of mime type text/plain and the content is string representation of id of the newly copied configuration.

Security

You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have ACCESS_SETTINGS permission on the configuration to be copied and have ADD_CHILDREN permission on the parent configuration.

Demo

We will use curl to demonstrate how to copy a configuration root/project/test recursively as root/project/test_copy.

1. Retrieve id of configuration root/project/test using id service:

   curl http://localhost:8810/rest/ids?configuration_path=root/project/test

   Assume retrieved identifier is 100.

2. Retrieve id of configuration root/project using id service:

   curl http://localhost:8810/rest/ids?configuration_path=root/project

   Assume retrieved parent identifier is 2.

3. Run below command to copy the configuration:

   curl -u admin:admin "http://localhost:8810/rest/configurations/100/copy?parent_id=2&name=test_copy&recursive=true"

Delete configuration

Syntax

Configuration can be deleted using http DELETE method through below url:

http://localhost:8810/rest/configurations/<configuration id>

Here <configuration id> stands for id of the configuration to be deleted and can be queried with id service.

Security

You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have DELETE_CHILDREN on the parent configuration.

Demo

Below curl command demonstrates how to delete the configuration with id 2:

curl -X DELETE -u admin:admin http://localhost:8810/rest/configurations/2