Build request object can be used to request new build or cancel running build.
h1. List build requests
h2. Syntax
Build requests of a particular configuration can be listed via below url:
{code}http://localhost:8810/rest/build_requests?configuration_id=<configuration id>&trigger_user_id=<trigger user id>{code}
Where:
* _<configuration id>_ should be replaced with identifier of a configuration. If this query parameter is missing, QB will return all build requests in the system.
* _<trigger user id>_ should be replaced with identifier of the user triggering the request. If this query param is missing, QB will return build requests triggered by all users in the system.
The response is of mime type _text/plain_ and the content is XML representation of list of build requests.
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access requested configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to list all build requests in configuration _root/test_ requested by user _robin_:
# Get configuration id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
Assume returned identifier of configuration _root/test_ is _2_,
# Get user id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?user_name=robin{code}
Assume returned identifier of user _robin_ is _100_,
# execute below command to get all build requests of _root/test_ triggered by _robin_:
{code}curl -u admin:admin "http://localhost:8810/rest/build_requests?configuration_id=2&trigger_user_id=100"{code}
{anchor:request new build}
h1. Request new build
h2. Syntax
New build can be requested by posting XML representation of the build request object to below url:
{code}http://localhost:8810/rest/build_requests{code}
A sample XML of build request object is like below:
{code}
<com.pmease.quickbuild.BuildRequest>
<!-- This element tells QuickBuild in what configuration to trigger build. -->
<configurationId>10</configurationId>
<!-- This element tells whether or not to respect build condition of the configuration.
If this is set to true, and if the build condition evaluates to false, build will
not be triggered. -->
<respectBuildCondition>false</respectBuildCondition>
<!-- This optional element specifies priority of the build request, with value ranging from 1 to 10. The
bigger this value is, the higher the priority is -->
<priority>10</priority>
<!-- This element is optional and is used to specify variables for build triggering. If
specified, it will override the variable with the same name defined in configuration
basic setting. -->
<variables>
<entry>
<string>var_name1</string>
<string>var_value1</string>
</entry>
<entry>
<string>var_name2</string>
<string>var_value2</string>
</entry>
</variables>
<!-- This element is optional and is used to tell QuickBuild to request a build promotion. -->
<promotionSource>
<!-- This element is optional and is used to tell QuickBuild that the source build resides on another
QuickBuild server. -->
<server>
<url>http://another-qb-server:8810</url>
<userName>admin</userName>
<password>admin</password>
</server>
<!-- Identifier of the source build to promote from -->
<buildId>697</buildId>
<!-- This element is optional and used to specify files to promote -->
<deliveries>
<com.pmease.quickbuild.FileDelivery>
<srcPath>artifacts/dir1</srcPath>
<filePatterns>**/*.jar</filePatterns>
</com.pmease.quickbuild.FileDelivery>
<com.pmease.quickbuild.FileDelivery>
<srcPath>artifacts/dir2</srcPath>
<filePatterns>**/*.war</filePatterns>
</com.pmease.quickbuild.FileDelivery>
</deliveries>
</promotionSource>
</com.pmease.quickbuild.BuildRequest>
{code}
The response is of mime type _text/plain_ and the content is XML representation of request result including the generated build request id. Http status code 204 (No Content) will be returned if the request is aggregated.
Since QuickBuild 6.0.14, one can also trigger new build via GET request by accessing below url:
{code}http://localhost:8810/rest/trigger?configuration_id=<configuration id>{code}
Where _<configuration id>_ should be replaced with identifier of a configuration. The response is of mime type _text/plain_ and the content is XML representation of newly created request result. Note that this approach does not accept variables or promotions information.
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _RUN_BUILD_ permission for the requested configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to request a build in configuration _root/test_:
# Get configuration id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
# Save the sample build request XML described above to file _tempfile.xml_, and modify configuration id to use value returned by the first step.
# Post content of _tempfile.xml_ to QuickBuild using below command:
{code}curl -X POST -u admin:admin -d@tempfile.xml http://localhost:8810/rest/build_requests{code}
{anchor:delete build request}
h1. Delete a Build Request
h2. Syntax
Existing build request can be deleted using http DELETE method through below url:
{code}http://localhost:8810/rest/build_requests/<build request id>{code}
{note}If the build associated with the build request is already running, it will be forcibly stopped.{note}
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _STOP_BUILD_ permission for the associated configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to delete build request _0136ed89-d47f-4307-8e69-c8535fae0e84_:
{code}curl -X DELETE -u admin:admin http://localhost:8810/rest/build_requests/0136ed89-d47f-4307-8e69-c8535fae0e84{code}
h1. List build requests
h2. Syntax
Build requests of a particular configuration can be listed via below url:
{code}http://localhost:8810/rest/build_requests?configuration_id=<configuration id>&trigger_user_id=<trigger user id>{code}
Where:
* _<configuration id>_ should be replaced with identifier of a configuration. If this query parameter is missing, QB will return all build requests in the system.
* _<trigger user id>_ should be replaced with identifier of the user triggering the request. If this query param is missing, QB will return build requests triggered by all users in the system.
The response is of mime type _text/plain_ and the content is XML representation of list of build requests.
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have permission to access requested configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to list all build requests in configuration _root/test_ requested by user _robin_:
# Get configuration id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
Assume returned identifier of configuration _root/test_ is _2_,
# Get user id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?user_name=robin{code}
Assume returned identifier of user _robin_ is _100_,
# execute below command to get all build requests of _root/test_ triggered by _robin_:
{code}curl -u admin:admin "http://localhost:8810/rest/build_requests?configuration_id=2&trigger_user_id=100"{code}
{anchor:request new build}
h1. Request new build
h2. Syntax
New build can be requested by posting XML representation of the build request object to below url:
{code}http://localhost:8810/rest/build_requests{code}
A sample XML of build request object is like below:
{code}
<com.pmease.quickbuild.BuildRequest>
<!-- This element tells QuickBuild in what configuration to trigger build. -->
<configurationId>10</configurationId>
<!-- This element tells whether or not to respect build condition of the configuration.
If this is set to true, and if the build condition evaluates to false, build will
not be triggered. -->
<respectBuildCondition>false</respectBuildCondition>
<!-- This optional element specifies priority of the build request, with value ranging from 1 to 10. The
bigger this value is, the higher the priority is -->
<priority>10</priority>
<!-- This element is optional and is used to specify variables for build triggering. If
specified, it will override the variable with the same name defined in configuration
basic setting. -->
<variables>
<entry>
<string>var_name1</string>
<string>var_value1</string>
</entry>
<entry>
<string>var_name2</string>
<string>var_value2</string>
</entry>
</variables>
<!-- This element is optional and is used to tell QuickBuild to request a build promotion. -->
<promotionSource>
<!-- This element is optional and is used to tell QuickBuild that the source build resides on another
QuickBuild server. -->
<server>
<url>http://another-qb-server:8810</url>
<userName>admin</userName>
<password>admin</password>
</server>
<!-- Identifier of the source build to promote from -->
<buildId>697</buildId>
<!-- This element is optional and used to specify files to promote -->
<deliveries>
<com.pmease.quickbuild.FileDelivery>
<srcPath>artifacts/dir1</srcPath>
<filePatterns>**/*.jar</filePatterns>
</com.pmease.quickbuild.FileDelivery>
<com.pmease.quickbuild.FileDelivery>
<srcPath>artifacts/dir2</srcPath>
<filePatterns>**/*.war</filePatterns>
</com.pmease.quickbuild.FileDelivery>
</deliveries>
</promotionSource>
</com.pmease.quickbuild.BuildRequest>
{code}
The response is of mime type _text/plain_ and the content is XML representation of request result including the generated build request id. Http status code 204 (No Content) will be returned if the request is aggregated.
Since QuickBuild 6.0.14, one can also trigger new build via GET request by accessing below url:
{code}http://localhost:8810/rest/trigger?configuration_id=<configuration id>{code}
Where _<configuration id>_ should be replaced with identifier of a configuration. The response is of mime type _text/plain_ and the content is XML representation of newly created request result. Note that this approach does not accept variables or promotions information.
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _RUN_BUILD_ permission for the requested configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to request a build in configuration _root/test_:
# Get configuration id using [id service|retrieve object identifier]:
{code}curl http://localhost:8810/rest/ids?configuration_path=root/test{code}
# Save the sample build request XML described above to file _tempfile.xml_, and modify configuration id to use value returned by the first step.
# Post content of _tempfile.xml_ to QuickBuild using below command:
{code}curl -X POST -u admin:admin -d@tempfile.xml http://localhost:8810/rest/build_requests{code}
{anchor:delete build request}
h1. Delete a Build Request
h2. Syntax
Existing build request can be deleted using http DELETE method through below url:
{code}http://localhost:8810/rest/build_requests/<build request id>{code}
{note}If the build associated with the build request is already running, it will be forcibly stopped.{note}
h2. Security
You will need to use http BASIC authentication to login as authorized QuickBuild user if the anonymous does not have _STOP_BUILD_ permission for the associated configuration.
h2. Demo
We use [curl|http://curl.haxx.se/] to demonstrate how to delete build request _0136ed89-d47f-4307-8e69-c8535fae0e84_:
{code}curl -X DELETE -u admin:admin http://localhost:8810/rest/build_requests/0136ed89-d47f-4307-8e69-c8535fae0e84{code}