Build request object can be used to request new build or cancel running build.

List build requests

Syntax

Build requests of a particular configuration can be listed via below url:

http://localhost:8810/rest/build_requests?configuration_id=<configuration id>&trigger_user_id=<trigger user id>

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.

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.

Demo

We use curl to demonstrate how to list all build requests in configuration root/test requested by user robin:

1. Get configuration id using id service:

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

   Assume returned identifier of configuration root/test is 2,

2. Get user id using id service:

   curl http://localhost:8810/rest/ids?user_name=robin

   Assume returned identifier of user robin is 100,

3. execute below command to get all build requests of root/test triggered by robin:

   curl -u admin:admin "http://localhost:8810/rest/build_requests?configuration_id=2&trigger_user_id=100"

Request new build

Syntax

New build can be requested by posting XML representation of the build request object to below url:

http://localhost:8810/rest/build_requests

A sample XML of build request object is like below (the sample build request can be retrieved via url "http://localhost:8810/rest/build_requests/sample"):

<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 specify content of file to be uploaded. 
       In below example, file content will be attached to variable "var_name1", and 
       value of this variable specified in variables section will be the file name. 
       One can access full path to the file at QuickBuild side via vars.getValue("var_name1") -->
  <fileContents>
    <entry>
      <string>var_name1</string>
      <string>base64 encoding of file content</string>
    </entry>
  </fileContents>

  <!-- 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>

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:

http://localhost:8810/rest/trigger?configuration_id=<configuration id>

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.

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.

Demo

We use curl to demonstrate how to request a build in configuration root/test:

1. Get configuration id using id service:

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

2. Save the sample build request XML described above to file tempfile.xml, and modify configuration id to use value returned by the first step.
3. Post content of tempfile.xml to QuickBuild using below command:

   curl -X POST -u admin:admin -d@tempfile.xml http://localhost:8810/rest/build_requests

Delete a Build Request

Syntax

Existing build request can be deleted using http DELETE method through below url:

http://localhost:8810/rest/build_requests/<build request id>

If the build associated with the build request is already running, it will be forcibly stopped.

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.

Demo

We use curl to demonstrate how to delete build request 0136ed89-d47f-4307-8e69-c8535fae0e84:

curl -X DELETE -u admin:admin http://localhost:8810/rest/build_requests/0136ed89-d47f-4307-8e69-c8535fae0e84