RunningABuild

Perhaps the most powerful use of the jenkins-rest is when the REST API calls are combined to submit a job, track its progress and report on the build status.

At a high level, the steps to submit a job and track it to its completion are:

1. Call the JobsApi build method. This returns an IntegerResponse instance with the queue id number of the submitted job
2. Poll the QueueApi queueItem method using the queue id number from the Integer Response. Polling returns a QueueItem instance which contains the state of the build in the queue. The state could be a:
   1. build cancellation before the build even starts (abort the polling, the build will never run)
   2. build pending (continue to wait or time out)
   3. build executing with a build number (stop polling the queue)
3. Poll the JobsApi buildInfo method using the QueueItem build number. This returns a BuildInfo instance. When the result method no longer returns null, the build is done and the result method returns a string representing the build status (passed, failed, etc).

A complete example is available in RunningABuild.groovy. To run the example, you will need to place the job.xml file in the same folder as the RunningABuild.groovy script.

With a live instance of Jenkins running, the example can be executed like so:

export JENKINS_REST_CREDENTIALS=user:password
export JENKINS_REST_ENDPOINT=http://localhost:8080/
groovy RunningABuild.groovy