This documentation relates to QuickBuild 13.0.x
Select here if you are using a different version

Interact with Configurations

Version 2 by Robin Shen
on Jan 06, 2023 03:14.

<< Changes from 1 to 2
compared with
Current by Robin Shen
on Jan 14, 2023 01:48.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 1 changes. View first change.

 h1. Get child configurations of specified configuration
  
 h2. Syntax
 A list of child configurations can be accessed by parent configuration id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations?parent_id=<parent configuration id>{code}
 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.
 {note}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|#get configuration by id] if necessary.{note}
  
 h2. Security
 Only configurations accessible by current user (specified in http BASIC authentication) will be returned.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get child configurations under the configuration with id of _1_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations?parent_id=1{code}
  
 h1. Get all descendent configurations of specified configuration
  
 h2. Syntax
 All descendent configurations can be accessed by parent configuration id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations?parent_id=<parent configuration id>&recursive=true{code}
 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.
 {note}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|#get configuration by id] if necessary.{note}
  
 h2. Security
 Only configurations accessible by current user (specified in http BASIC authentication) will be returned.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get descendent configurations under the configuration with id of _1_:
 {code}curl -u admin:admin "http://localhost:8810/rest/configurations?parent_id=1&recursive=true"{code}
  
 h1. Get all configurations in the system
  
 h2. Syntax
 All configurations in the system can be accessed using http GET method through below url:
 {code}http://localhost:8810/rest/configurations?recursive=true{code}
 The response is of mime type _application/xml_ and the content is brief xml representation of list of all configurations.
 {note}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|#get configuration by id] if necessary.{note}
  
 h2. Security
 Only configurations accessible by current user (specified in http BASIC authentication) will be returned.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get descendent configurations under the configuration with id of _1_:
 {code}curl -u admin:admin "http://localhost:8810/rest/configurations?recursive=true"{code}
  
  h1. Search configurations by path
  h1. Search configurations by path pattern
  
 h2. Syntax
 Configurations matching specified path pattern can be accessed using http GET method through below url:
 {code}http://localhost:8810/rest/configurations?search=some/path/pattern{code}
 The response is of mime type _application/xml_ and the content is brief xml representation of list of all matched configurations.
 {note}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|#get configuration by id] if necessary.{note}
  
 h2. Security
 Only configurations accessible by current user (specified in http BASIC authentication) will be returned.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get all release configurations:
 {code}curl -u admin:admin "http://localhost:8810/rest/configurations?search=**/release/**"{code}
  
 {anchor:get configuration by id}
 h1. Access configuration by id
  
 h2. Syntax
 Configuration can be accessed by id using http GET method through below url:
 {code}http://qb-server:8810/rest/configurations/<configuration id>{code}
 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.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get xml representation of configuration with identifier _1_ (the root configuration):
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/1{code}
  
 h1. Access configuration path by id
  
 h2. Syntax
 Configuration path can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/path{code}
 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.
  
 h2. Security
 Any user can access this service including anonymous.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get path name of configuration with id _2_:
 {code}curl http://localhost:8810/rest/configurations/2/path{code}
  
 h1. Access configuration name by id
  
 h2. Syntax
 Configuration name can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/name{code}
 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.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get name of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/name{code}
  
 h1. Access configuration description by id
  
 h2. Syntax
 Configuration description can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/description{code}
 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.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get description of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/description{code}
  
 h1. Access configuration error message by id
  
 h2. Syntax
 Configuration error message can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/error_message{code}
 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.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get error message of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/error_message{code}
  
 h1. Access configuration run mode by id
  
 h2. Syntax
 Configuration run mode can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/run_mode{code}
 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.
  
 h2. Security
 Any user can access this service including anonymous.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get run mode of configuration with id _2_:
 {code}curl http://localhost:8810/rest/configurations/2/run_mode{code}
  
 h1. Access configuration schedule by id
  
 h2. Syntax
 Configuration schedule can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/schedule{code}
 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.
  
 h2. Security
 Any user can access this service including anonymous.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get schedule of configuration with id _2_:
 {code}curl http://localhost:8810/rest/configurations/2/schedule{code}
  
 h1. Access configuration variables in hierarchy by id
  
 h2. Syntax
 Configuration variables in hierarchy can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/variablesInHierarchy{code}
 Here _<configuration id>_ stands for id of the configuration. The response is of mime type _application/xml_ and the content is xml representation of returned variables.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access settings of the requested configuration.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get hierarchy variables of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/variablesInHierarchy{code}
  
  
 h1. Access interpolated configuration variables in hierarchy by id
  
 h2. Syntax
 Interpolated configuration variables in hierarchy can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/interpolatedVariablesInHierarchy{code}
 Here _<configuration id>_ stands for id of the configuration. The response is of mime type _application/xml_ and the content is xml representation of interpolated variables.
  
 h2. Security
 You will need to use http BASIC authentication to login as an authorized QuickBuild user if the anonymous is not allowed to access settings of the requested configuration.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get interpolated hierarchy variables of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/interpolatedVariablesInHierarchy{code}
  
 h1. Access average build duration of configuration by id
  
 h2. Syntax
 Average build duration can be accessed by configuration id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/average_duration?from_date=<from date>&to_date=<to date>{code}
 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.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get average duration of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/average_duration{code}
  
  
 h1. Access build success rate of configuration by id
  
 h2. Syntax
 Build success rate can be accessed by configuration id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/success_rate?from_date=<from date>&to_date=<to date>{code}
 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%.
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get success rate of configuration with id _2_:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/2/success_rate{code}
  
 h1. Access parent configuration by id
  
 h2. Syntax
 Parent configuration can be accessed by id using http GET method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>/parent{code}
 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.
  
 h2. Security
 Any user can access this service including anonymous.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to get parent of configuration with id _2_:
 {code}curl http://localhost:8810/rest/configurations/2/parent{code}
  
 h1. Update configuration
  
 h2. Syntax
 Configuration can be updated by posting xml representation of the configuration to below url:
 {code}http://localhost:8810/rest/configurations{code}
 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.
 {note:title=NOTE}
 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.
 {note}
  
 h2. 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.
  
 h2. Demo
 We will use [curl|http://curl.haxx.se/] to demonstrate how to modify description of configuration _root/test_:
 # Retrieve id of configuration _root/test_ [using id service|retrieve object identifier]:
 {code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
 # Retrieve full xml representation of configuration _root/test_ into a temp file using below command:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/<configuration id> > tempfile.xml{code}
 Here _<configuration id>_ needs to be replaced with query result of first step.
 # Edit _tempfile.xml_ and change the _description_ property to desired value (or add description element if it does not exist).
 # Post back modified content using below command:
 {code}curl -X POST -u admin:admin --data-binary "@tempfile.xml" http://localhost:8810/rest/configurations{code}
  
 h1. Create configuration
  
 h2. Syntax
 Configuration can be created by posting xml representation of the configuration to below url:
 {code}http://localhost:8810/rest/configurations{code}
 Please note that:
 # The posted xml should NOT contain the _id_ element; otherwise, QuickBuild will treat the post as an update to the configuration with that id.
 # 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.
 # 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.
  
 h2. 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.
  
 h2. Demo
 We will use [curl|http://curl.haxx.se/] to demonstrate how to create a new configuration _root/test-copy_ by copying the configuration _root/test_.
 # Retrieve id of configuration _root/test_ [using id service|retrieve object identifier]:
 {code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
 # Retrieve full xml representation of configuration _root/test_ into a temp file using below command:
 {code}curl -u admin:admin http://localhost:8810/rest/configurations/<configuration id> > tempfile.xml{code}
 Here _<configuration id>_ needs to be replaced with query result of first step.
 # Edit _tempfile.xml_, remove the _id_ element, and change the _name_ element to be _test-copy_
 # Post back modified content using below command:
 {code}curl -X POST -u admin:admin --data-binary "@tempfile.xml" http://localhost:8810/rest/configurations{code}
  
 h1. Copy configuration (available since 4.0.72)
  
 h2. Syntax
 Configuration can be copied via GET method like below:
 {code}http://localhost:8810/rest/configurations/<configuration id>/copy?parent_id=<parent id>&name=<name>&recursive=[true|false]{code}
 Here:
 # The _<configuration id>_ has to be replaced by id of the configuration to be copied.
 # The _<parent id>_ has to be replaced by id of the parent to place newly copied configuration.
 # The _<name>_ has to be replaced by name of the newly copied configuration.
 # 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.
  
 h2. 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.
  
 h2. Demo
 We will use [curl|http://curl.haxx.se/] to demonstrate how to copy a configuration _root/project/test_ recursively as _root/project/test_copy_.
 # Retrieve id of configuration _root/project/test_ [using id service|retrieve object identifier]:
 {code}curl http://localhost:8810/rest/ids?configuration_path=root/project/test{code}
 Assume retrieved identifier is 100.
 # Retrieve id of configuration _root/project_ [using id service|retrieve object identifier]:
 {code}curl http://localhost:8810/rest/ids?configuration_path=root/project{code}
 Assume retrieved parent identifier is 2.
 # Run below command to copy the configuration:
 {code}curl -u admin:admin "http://localhost:8810/rest/configurations/100/copy?parent_id=2&name=test_copy&recursive=true"{code}
  
 h1. Delete configuration
  
 h2. Syntax
 Configuration can be deleted using http DELETE method through below url:
 {code}http://localhost:8810/rest/configurations/<configuration id>{code}
 Here _<configuration id>_ stands for id of the configuration to be deleted and can be queried with [id service|retrieve object identifier].
  
 h2. 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.
  
 h2. Demo
 Below [curl|http://curl.haxx.se/] command demonstrates how to delete the configuration with id _2_:
 {code}curl -X DELETE -u admin:admin http://localhost:8810/rest/configurations/2{code}