Musings on technology.

Using Continous Integration in XPages Projects

Story short, many saw the recent developments for automating .NSF builds using “headless” Domino Designer:

This opens a totally new area for XPages projects. As we know, XPages is just something on top of JSF1.1, meaning you can and should leverage Java language to simplify the development of XPages applications. In fact, by moving most of stuff into Java code you can reduce the reliance on Domino Designer.

We all know, Domino development lacked all the goodies other technologies had: version control, build tools, unit tests, etc. With time, some of these started to appear in Domino Designer, when it became Eclipse-based. We got version control, perhaps not ideal, but at least in a working state. We could use JUnit to test Java code, though with additional effort. Nevertheless, we still lacked build tools, specifically ability to run it decoupled from Domino Designer, e.g. in an Ant job.

With Domino Designer 9.0.1, Domino Developers can do this as well. I will not go in details on how to enable & use it, since links at the start of this post contain suficient information. Instead, I will focus on how to make use of Continous Integration tools for automating XPages builds.

In short, I want to achieve following automated process:

  1. Checkout source of .NSF from remote GIT repository (any other supported by CI tools should work as well)
  2. Compute build number based on commit hash code
  3. Build .NSF file

This process should be triggered automatically on each commit. There are few requirements to get it working:

  1. A Windows VM (or dedicated computer) with Domino Designer 9.0.1 and Powershell installed.
  2. JetBrains Teamcity (other CI tools should works as well, as long as they support Powershell scripts), which is free for up to 20 build configurations:
    • When installing TeamCity, you will notice that it installs a server and a build agent. It’s important that build agent is not set to run as service. Instead, you should start it manually, otherwise Domino Designer automatic builds wont work.
  3. XPages project hosted in a remote repository.

After you install TeamCity and start the Build Agent, you will create a Project. I will not go in details on how to do it, but you can refer to official documentation for more information. After creating the project, you will create one or more build configurations. Below you can see screenshots of my test build configuration:

Actual build is performed based on build steps configuration. Below are screenshot of each of build steps I defined and associated Powershell scripts:

Script to compute build numberOriginal Source
$BuildNumber = "%build.number%"
$Hash = "%build.vcs.number%"
$ShortHash = $Hash.substring(0,7)
Write-Host "##teamcity[buildNumber '$BuildNumber.$ShortHash']"

Script to perform .NSF buildGist
$build_number = "%build.number%"
$checkout_location = ""

Clear-Content HEADLESS0.log

$args = '-RPARAMS -vmargs"true,true,discussion' + $build_number + '.nsf,importandbuild,' + $checkout_location + '\.project,discussion' + $build_number + '.nsf"'

Write-Host $args

$p = Start-Process designer -ArgumentList $args
$target = 'notes2'
$process = Get-Process | Where-Object {$_.ProcessName -eq $target}

do {
    Get-Content headless0.log -Wait | Select-String "closing designer" | %{ write-host Found $_; break}
} until($process.HasExited)

At this point, you can trigger Run and see the results of build. Newly created will be in Notes Data folder. You can further extend build configuration with JUnit tests, automatic deployment to Domino server, possibly using Domino COM API in powershell scripts, etc.