Skip to main content

Build XPages app from Git with Jenkins

Since introduction of Headless designer tech-preview in Domino Designer 9.0.1 many people started to think about build automation. Now is time to try it with Jenkins - popular free build automation server.

I've used Gradle as a build tool, which uses Groovy language. So some G-stuff which all the cool kids use in their projects (I always wonder why so many project names start with G even when they are not in direct relation to Google).

*disclaimer*
Most of these tools I haven't used in production, so I might break some best practices and take other shortcuts.
Also all code is written just as a proof of concept, nothing more.
*end of disclaimer*

Required tools:

  • Windows machine
  • Java JDK
  • GIT
  • Domino Designer 9.0.1
  • Jenkins
  • Git repository - bitbucket in my case

Jenkins setup

I did use Jenkins installation with GIT and Gradle plugin. If you are new to Jenkins, there are many tutorials online how to setup Jenkins. Recent tutorials for Android app builds use Gradle too, so you might want to check them.

If you just want to get it up and running, following steps did it for me:
  1. Install Jenkins
  2. In windows configure Jenkins service, so it can interact with desktop

    This might not be necessary, but egmar had some problems when running as a service in his TeamCity integration and I had problem when my ID file was stored on VMware shared folder mapped as local drive, which couldn't be accessed by services, and without this I didn't know why the build was stuck.
  3.  In Manage Jenkins set-up security (it should ask you to do it using small banner on top). I just used settings that allowed all logged-in users do anything.
    This is probably necessary only if you want to access private Git repositores.
  4. Install plugins - in Manage Jenkins / Manage Plugins / Available plugins just check Gradle and Git plugin and let Jenkins install them
  5. If your GIT and Java installation are not in system PATH, you might need to add whose in Manage Jenkins / Configure System
 Now your  Jenkins should be ready.

Create job to fetch project

I hope you have all your projects in GIT (or any other SCM) repositories, so you can pick any to try. I recommend small ones first, since for example IBM Teamroom template took about 8 minutes to build in my test VM. And this is not good for experiments.

If you just want to follow this article, repository I used is public, so you can get it from Bitbucket too.

  1. Click on New Item and create your first job
  2. Give it a name (ideally without spaces to avoid troubles later with my GradleNotesPlugin)
  3. Select a free-style build and click OK
  4. Configure Source Code Management to fetch you repository

    I used my repository bitbucket.org/pradnik/testing.git and develop branch. It contains one NSF project and one Java project for tests that I want to integrate later.
  5. Optionaly configure build triggers.
    My Jenkins is not publicly available, which is why I couldn't trigger the build from Bitbucket, which is recommended way, so I used just Poll SCM option.
Now you should be ready to start your build and fetch the repository to local file system.

Save it and click Build Now. When done, you should find your repository locally under Jenkins/jobs/ProjectName/workspace/


Build the Notes app with Gradle

You might notice that my project contains files like settings.gradle, build.gradle and gradlew.bat. These are used for Gradle build.

Gradlew.bat together with gradle directory is just a wrapper arround gradle. It allows anyone to run Gradle build on machines even when they don't have Gradle installed, because it takes care of everything.

This is good for our testing, as we can try to launch the build from our on-disk-project without using Jenkins and then get back to Jenkins with configuration that works.

Gradle Notes Build plugin

To keep our builds flexible I decided to create plugin that hides all the calls to Domino Designer. You may as well write it in build.gradle file, but this is better for reuse.
Originally I wanted to write the plugin in Java, but I had problems with task parameters, so I had to switch to Groovy (this is first piece of code I have ever written in Groovy, so don't blame me for any mess, please).

Again, plugin can be build with Gradle. But if you don't want to do it, just download it here as a jar.

Repository
Project for this plugin is publicly available on Bitbucket  https://bitbucket.org/pradnik/gradlenotesplugin

I won't cover details how to build a Gradle plugin here as many tutorials exist. I just want to show main code of task that we will use



All it does is same routine as in batch file form my previous posts. It has 3 parameters
  • filePath - path to NSFproject (actually .project file)
  • fileName - name of NSF file created
  • notesDir - path to Notes directory
 It creates command in syntax from Headless designer wiki runs it and then waits in loop for notes to finish.

You can see that there is currently no error handling and also the time limit can be low (I probably almost hit it with Teamroom). But this will be improved in future releases :-) . Also when you run the build, it doesn't show output from designer, which might be usefull.

If you want to modify it and build it yourself just run gradle uploadArchives and it will save jar in locally created maven repository.

Build structure

In my repository I have currently 2 projects, so I need to structure my build in some way. This is quite common in Gradle world and Gradle can do magic with it. For now we can forget TestingTestTests directory as it is not used.

Our root project Gradle file just tells gradle to build what needed and setting.gradle tells what subproject is should check.

build.gradle
apply plugin: 'java'




dependencies {
    compile gradleApi()
    compile localGroovy()
}

settings.gradle
include ':testingTest'

Main work is done in build.gradle in testingTest directory (which is my NSF project)

build.grade
buildscript {
     dependencies {
        classpath files(gradleNotesPlugin)
    }
}
apply plugin: 'notes-plugin'

import com.pradny.gradle.NotesBuildTask

task createNSF(type: NotesBuildTask) {
    filePath=file('.project')
    fileName=nsfName
  
} 

All lines are important in this case. Gradle, unlike Maven and Ant, doesn't require huge ammount of lines just to get basic stuff done.

  1. buildscript block - tells us where to find our plugin. We will set this as a command line parameter.
  2. apply-plugin - tells Gradle to use our plugin
  3. import - imports class of our Task (might not be necessary if you use full name on next line)
  4. task - runs our task with parameters (filePath is taken from current project location and fileName is passed as a command line parameter)
In real-world scenario you will configure those parameters in more sophisticated manner, but this also shows that Gradle can do simple things in very simple way.

And this is all.
Now just run:

gradlew createNSF -PgradleNotesPlugin=c:/gradleNotesPlugin.jar -PnsfName=blogTest.nsf

note: parametres are passed using -Pname=value syntax

When done, you should have blogTest.nsf in your Notes data directory.

Calling Gradle build from Jenkins

Last piece in our puzzle is hooking Gradle into Jenkins build. So return to Jenkins web page and open configuration of your job.

  1. At bottom click Add build step button and select Invoke Gradle script
  2. Select Use Gradle Wrapper
  3. Add parameters that we used during test launch
  4. As Task use createNSF
  5. Save it
Run your build and enjoy power of automation.

You can experiment with  build triggers and other Jenkins options, but from Notes - Jenkins integration it is all for today. In future I want to and task to move created nsf to server (for now you can use batch file method from my previous posts, run test including Selenium, etc.

------------------------------------------------------------------------------------------------------------------------

Troubleshooting note - sometimes Designer didn't want to start. Currently I don't know if it was caused by calling it from local service and as a user during experiments, or was it something else. After reboot it was fine again.

Comments

Popular posts from this blog

Microsoft Word black box in numbering issue

This is awkward post, primarily to save the solution for future me. I have seen many people mentioning this problem over years and as I've struggled with it several times, I needed to find final and permanent solution.


All editions of Microsoft Word from time to time suffer from bug in numbering. Instead of a number, black box is displayed. Sometimes it happens right after document is opened, sometimes during editing. Probably some internal structure of document gets corrupted, so based on level of corruption, different fixes could help. Many of them are listed at https://answers.microsoft.com/en-us/office/forum/office_2010-word/ms-word-header-styles-are-showing-black-boxes/c427b21c-dcda-46ce-a506-b9a16c9f2f3f


I took different approach. Since docx is just standard zip package with xml files, I decided to try if I can fix it manually. And it worked.

When I extracted the docx, there was file called numbering.xml in word folder. When I examined that file, I found strange section in h…

Using JAX-RS inside NSF

Last week Christian G├╝demann published new release of SmartNSF on OpenNTF that contains cool new feature that Christian tweeted before. With new CUSTOM strategy it allows direct execution
of Java code from REST API defined in router configuration. It's even better than it sounds as it initializes facesContext and XPages application if needed, so even access to beans works.

I needed to start to build new REST APIs for few databases, so I decided to test new SmartNSF option and also other available options for REST APIs on Domino (there are several, check references at the end for more info). Since CUSTOM strategy requires dependency on SmatNSF in NSF project and also implementation of CustomRestHandler interface, it'd force me to do more changes in my code that I wanted to. If I need to change my code, why not adjust it for JAX-RS spec anyway.

Existing Domino JAX-RS options had to packaged as plugins, which make it hard to call code that is currently in NSF. I could make it wor…

WSL, HCL Volt and some Docker

My list of new technologies to try was growing fast in past months, but now I finally can try to catch up with all the cool improvements that can be used to enhance my/your dev experience.
Microsoft has enhanced the Windows Subsystem for Linux this year and Docker completely changed the way Docker Desktop for Windows is integrated into the operating system. The most important change for me was that I can finally run Docker Desktop and VMWare Workstation on my machine in parallel. When I was looking for some good use cases to try how it works, HCL Domino was a logical choice. HCL started to even publish official Docker images for every release and some pre-releases are only available as Docker images. I have many test Domino machines running in VMs, but I had no HCL Volt. If you don't know that HCL Volt is - it's a new low-code platform that brings HCL Form Builder experience, now know as HCL Leap, to HCL Domino, which then serves as a data store and application server. When I…