Lesson 2: Creating a job and adding steps

A job is a series of steps that, taken together, complete some activity, such as building a project. The steps are run one at a time in the order you specify.

Before you begin this lesson, make sure that you complete the steps that are described in Configure the tutorial system.
In this lesson, you create a job and add several steps to it.

Creating a job

Most job steps are created from plug-ins. Plug-in steps can be thought of as distinct pieces of automation.

By combining steps from various plug-ins, you can create fully automated build processes. The number of steps that are provided by a particular plug-in can vary, and each step has a variable number of properties. Property values can be supplied when you define a step or at process run time.
Note: Several plug-ins are included in the product, and you can download other plug-ins as described earlier in the tutorial. Some steps, such as Assign Status and Create Stamp, are not derived from plug-ins, but you use them in the same way you use plug-in steps.

Create a job by completing the following steps:

  1. On the left navigational panel, click Templates > Jobs.
  2. On the Jobs page, click Create.
  3. In the Create a Job window, specify the name to be Demo Job.
  4. Click Save.
    The Main tab for the new job is displayed.
Use the Main tab to add steps to the job. Except for the first step, steps can be inserted before or after other steps. When you run the job, the steps are run in the order you specify.

Creating a stamp step

A stamp is a custom identifier that is applied to a build. Stamps are often used in addition to the automatically generated build life identifiers. A stamp step is part of most jobs.

  1. If the Main tab for the Demo Job is not displayed, then from the Build dashboard, click Templates > Jobs, and then click Demo Job.
  2. Click Create Step.
  3. Using the Steps dialog, click Build.
    The Build list expands to display the available build-type steps and plug-ins.
  4. Click Create Stamp step, and then click Select.
    The Stamp dialog is displayed. The dialog that is displayed after selecting a step contains properties for the selected step, and other properties common to all steps.
    Note: Each step dialog has more options available than is initially displayed. To see the other options, click Show Additional Options. The additional options are the same for all steps and are set to default values that are acceptable for most jobs. The default value for the Pre-Condition Script field is All Prior Success, which means the step runs only if the preceding steps are successful. The additional options are show in the following figure. For most of the steps in the tutorial job, the default values are fine.
    The Stamp dialog with additional options displayed
  5. In the Name field, type Create Stamp.
  6. In the Stamp field, enter a script to define the stamp: 1.0.0.${p:buildlife/id}.
    The simplest way to make a unique stamp is to associate it with the build-life number. This short script looks-up the current build-life ID and applies it to the stamp. This script references a property that is part of every build life. Another option might be to reference a property that you can create and define later. For the tutorial, the build life property is fine. For information about the available properties, see the Scripting API Reference server_url/tools/scripting/ibm-ucb-scripting/.
  7. Click Save.
The Create Stamp step is listed on the Main tab for the job, as shown in the following figure:
The Create Stamp step that is listed on the Main tab

After a job has a step, the Create Step button is no longer used and actions are used instead to insert steps.

Cleaning the workspace

To ensure that no files from a previous build get incorporated into the new one, add a step to clean the agent's workspace. This step is part of most build jobs.

  1. Click the Insert After action for the Create stamp step.
    After a job has its first step, steps are inserted before or after other steps. The Insert After action, as the name implies, inserts the new step after the selected step.
    The Insert After action
  2. On the Steps dialog, click Source and then click Clean Workspace.
  3. Click Select.
    The Clean Workspace step is selected.
  4. In the Name field, type Clean.
  5. Click Save.
The Clean step is added to the job after the Create Stamp step, as shown in the following figure:
The Clean step is added to the job after the Create Stamp step

Populating the workspace

This step places the checked-out code (defined later in the project's source configuration) in the agent's workspace.

  1. Use the Insert After action for the Clean step.
  2. On the Steps dialog, click Source and then click Populate Workspace.
  3. Click Select.
  4. In the Name field, type Populate.
  5. Click Save.
The Populate step is added to the job, as shown in the following figure
The Populate step added to the job

Creating a get changelog step

This step retrieves source changes since the last build. The prior build life is located by using status or stamp parameters.

  1. Click the Insert After action for the Populate step.
  2. On the Steps dialog, click Source and then click Get Source Changes.
  3. Click Select.
  4. In the Name field, type Get Changelog.
  5. Select Success on the Start Status list.
    The value that is selected determines which source items are retrieved. In this case, only items with a value of Success are retrieved.
  6. Ensure that Save Changes in Database is selected (it is by default diabled).
    This parameter can be used in build reports.
  7. Click Save.
The Get Changelog step is inserted into the job after the Populate step, as shown in the following figure:
The Get Changelog step is inserted into the job.

Creating the set version step

Create a version ID that Maven can use.

  1. Click the Insert After action for the Get Changelog step.
  2. On the Steps dialog, click Build > Build Tools > Maven, and then click Maven Build.
  3. In the Name field, type Set Version.
  4. Ensure that the default value pom.xml is set in the Maven POM File field.
    Maven uses the project object model file (POM) to control builds.
  5. In the Goals field, type versions:set.
    Goals are similar to Ant tasks and define the actions that Maven performs.
  6. Optional: If you did not put the Maven home variable on your system PATH variable, enter it in the Maven Home field.
  7. In the Properties field, type newVersion=${p:buildlife/latestStamp}.
  8. Click Save.
The Set Version step is inserted into the job after the Get Changelog step, as shown in the following figure:
The Set Version step inserted into the job

Creating the Maven build step

This step uses Maven to build the project.

  1. Click the Insert After action for the Set Version step.
  2. On the Steps dialog, click Build > Build Tools > Maven, and then click Maven Build.
    This step uses the same plug-in step as the previous step, Set Version.
  3. In the Name field, type Maven Build.
  4. Ensure that the default value pom.xml is set in the Maven POM File field.
  5. In the Goals field, type ${p:maven.goals}.
    Unlike the other properties you used in the job, this value references a new property. Later, you create the property and define the value.
  6. Optional: If you did not put the Maven home variable on your system PATH variable, enter it in the Maven Home field.
  7. Click Save.
The Maven Build step is inserted into the job after the Set Version step, as shown in the following figure:
The Maven Build step inserted into the job

Creating the publish unit tests step

JUnit is a testing framework for Java™. This step runs tests and reports the results. It is configured to always run.

Before you begin this lesson, make sure that you complete the steps that are described in Configure the tutorial system.
  1. Click the Insert After action for the Maven Build step.
  2. On the Steps dialog, click Quality > Unit Testing > JUnit, and then click JUnit Report.
  3. In the Name field, type Publish Unit Tests.
  4. In the Report Name field, type JUnit Report.
  5. In the Source Directory field, type target/surefire-reports.
  6. In the Include Patterns field, type TEST*.xml.
  7. Display the Pre-Condition Script list by clicking Show Additional Options, and then select Always.
    Unlike the other steps in this job, this step always runs even if the preceding step fails. Test reports are displayed on the Tests tab for a selected build life. Reports are also written to the location you specified with the Source Directory field. Test files that match the pattern that is specified in the Include Patterns field are written to the same directory.
  8. Click Save.
The Publish Unit Tests step is inserted into the job after the Maven Build step, as shown in the following figure:
The Publish Unit Tests step inserted into the job

Creating the upload artifacts step

Upload the build artifacts to the CodeStation repository.

  1. Click the Insert After action for the Publish Unit Tests step.
  2. On the Steps dialog, click Build Systems, and then click CodeStation.
  3. Click Upload Artifatcs, and then click Select.
  4. In the CodeStation-Upload Artifacts window, in the Name field, type Upload Artifacts.
  5. Click Save.
The Upload Artifacts step is inserted into the job after the Publish Unit Tests step, as shown in the following figure:
The Upload Artifacts step inserted into the job

Creating the assign success step

If all previous steps are successful, this step assigns a status of Success to the entire job. If the preceding steps are not successful, this step does not run and the next step runs instead.

  1. Click the Insert After action for the Upload Artifacts step.
  2. On the Steps dialog, click Build, and then click Assign Status.
  3. In the Name field, type Assign Success.
  4. In the Status list, select Success.
  5. Click Save.
    Because the Pre-Condition Script field is set to All Prior Success by default, you can accept the value.
The Assign Success step is inserted into the job after the Publish Unit Tests step, as shown in the following figure:
The Assign Success step inserted into the job

Creating the assign failure step

This step assigns a status of Failure to the job. The step runs if any of the preceding steps fail.

  1. Click the Insert After action for the Assign Success step.
  2. On the Steps dialog, click Build, and then click Assign Status.
  3. In the Name field, type Assign Failure.
  4. In the Status list, select Failure.
  5. Display the Pre-Condition Script list, and select Any Prior Failure.
  6. Click Save.
The Assign Failure step is inserted into the job after the Assign Success step.

Lesson checkpoint

In this lesson, you created job and added the steps required to build JUnit.

This job builds JUnit and assigns a status to the job. It also runs the JUnit plug-in step to create a report about the job. A job can use steps from any installed plug-in. Steps have preconditions that determine whether they run. Steps are configured individually as you insert them into a job.

The steps for the completed Demo Job are shown in the following figure:
The finished Demo Job job