BuildXPages

The Project contains a library of tasks that can be organised and executed by Apache ANT.

See the Documentation of the BuildXPages ANT Library that is provided later is this user guide for more information.

Apache ANT is a build tool which helps you write instructions on how to automate tasks. If you haven’t used Ant before, don’t be scared! It is pretty simple once you get the hang of it. Yes there are other options, but Ant is well documented which makes it easier to understand. I have also provided some tutorials which should give you a feel for how it all works.

Ant has access to many commonly used steps such as manipluation of files in the filesystem (copy, move, delete, unzip etc.) and more complex tasks such as compiling java, running programs.

This project also includes a Plugin for Domino Designer which is used by the ANT task for building an NSF.

See the Documentation of the Headless Designer Plugin that is provided later is this user guide for more information.

The Plugin is basically an extension of the existing 'Headless Designer' system that was provided by IBM. The IBM Headless Designer system was a great start but could have used a little bit more love. There were a few annoyances, it was hard to tell when the build was finished, it was hard to tell that the build even started properly. There were some minor annoyances regarding project names and locations. The mechanism also involved writing a text 'command file', which was fed in when starting designer. This means each build would always have to start designer, build and then shut it down. If designer did not shut down, then you couldn’t start it up again and weird things like that.

So I decided to extend it and turn the functionality into a 'headless server'. This allow designer to remain open the whole time and listen for instructions from my ant tasks. If I need designer to restart and can tell it to shut down, and then start designer again and the 'headless server' starts again to wait for more instructions.

Installing Ant is a matter of downloading and extracting Ant to your desired location

Go to http://ant.apache.org/bindownload.cgi and download the appropriate archive. For Example, I am on a windows machine so I will download the zip archive.

When ANT runs, there are 2 locations in which it will check for additional libraries. You should put BuildXPages jar and JNA in one of these locations.

If you don’t want to install to the global library locations, you can just make it available for your single project.

Create a directory in your project called lib Put the BuildXPagesAntLib and JNA jar in that location

when running ant, you will need to specify the library location with -lib command

The following Environment Variables are only useful if you are intending to build plugins and features headless eclipse.

The ID file that you have been issued by an administrated must be created with settings that allow the password to be removed.

Alternatively, you can ensure that IBM Notes is running and logged in. In this case the automated tasks will hopefully not be prompted for a password if you tick the Don’t Prompt for a password from other Notes-based programs (reduces security) in your Notes Login and Password Settings

Copies an NSF from one place to another using the Notes C API’s 'NSFDbCreateAndCopy' function.

Deletes an NSF using the Notes C API’s NSFDbDelete method.

Updates the Template Inheritance settings of an NSF. You can set an NSF To be a master template, or you can set an NSF to Inherit from another Template, or Both! You can also clear the 'inherit from' or 'master template' settings.

Sets the Single Copy XPage Design settings of an NSF. You can set both the relevant properties of the SCXD path, and the Flag which determines whether to use the SCXD template or not.

Refreshes an NSF’s design from a server using the Notes C API DesignRefresh method.

The console output shows all the design elements that are modified which is great to verify what has changed.

This task uses existing template settings of the NSF so if you need to change them you should use the settemplatenames task before using this task.

This task will build all the Plugins listed in a feature, using the headless eclipse PDE build system.

Before using this task, you will need to have prepared the build directory with the source code of the plugins that are to be built, and the the feature that is to be built.

Imports plugins/features from an update site on the filesystem into an Open Eclipse NSF Update Site

This task is used during preparation for a headless eclipse plugin build. It is used to copy the source code of of a plugin or feature, into the build directory which is a special working directory used to build the plugins and features. The build directory contains 2 subfolders plugins and features and the plugin or feature will automatically be copied into the correct folder. The task will exclude contents of the bin folder when copying. The idea is to copy source files only.

Usually you update Domino Designer with new plugins by going through the normal installation process. But there is another way in which you can build plugins into a particular folder, and Domino Designer always picks up new versions.

When deploying plugins this way, some plugins need to be 'unpacked' which means they don’t exist as a jar file, but the contents are unpacked into a folder.

This task will unpack a plugin to a folder with the same name as the plugin. You only need to specify the plugin name, and it will find the version information automatically

After building your plugins headlessly with eclipse PDE, you will then have a directory of plugins and features, but before importing plugins into an Open Eclipse NSF Update Site you will also need a site.xml file.

Newer versions of eclipse use a p2 repository format which does not require a site.xml, but with Notes/Domino running on a much older version of eclipse, it still uses an older format which uses the site.xml file.

The build process does not generate one for us so we do it ourselvels with this task, which scans the features directory and builds the necessary xml.

After building plugins, sometimes you want to put them in an update site on the filesystem. You may want to make sure the update site is empty before you put your plugins there, so this task can clear out an existing update site.

After building plugins, sometimes you want to put them in an update site on the filesystem. This task will copy the plugins to your target update site, and also generate the site xml.

Before building an NSF with the Headless Designer Plugin, you need to make sure designer is running. You can use the checkDesignerRunning task to check, and if it is not running you can use this startDesigner task.

The buildnsf task is used to build an ODP into an NSF. To do this it connects to the Designer Headless Server, and instructs it to build. If the NSF that is specified does not yet exist, it will be created. You

This task connects to the Headless Designer Plugin and instructs it to shutdown.

This task connects to the Headless Designer Plugin, and requests a report of all the problem markers (e.g. Error, Info, Warning etc.) for a particular NSF.

If you like , you can cause the build to fail if there are errors present on the NSF, to prevent further tasks like deployment.

This task checks if the nlnotes.exe process is running, if so it sets a property designer.running. You can then use this property to decide whether to take some other action.

This task is used to set up an update site that will always be loaded when Designer Is started up. This is only used when you are deploying plugins to Domino Designer using the sneaky 'permanent update site' method.

This task is used to set up an update site that will always be loaded when Designer Is started up. This is only used when you are deploying plugins to Domino Designer using the sneaky 'permanent update site' method.

This task is just like the updateDesignerLink task, however it will create the update site folder structure within the framework directory of the Notes Installation.

You can then copy plugins to this update site, and they will be loaded by designer (if you have configured platform.xml using the checkplatformxml task)

This checks that the IBM Notes Installation’s platform.xml file is configured to automatically load plugins from the filesystem. The task will fail if the file is not configured properly.

This task configures IBM Notes' platform.xml file so that IBM Notes will load plugins from the filesystem without the need to 'approve' them via the User Interface.

Usually you need to go through the whole provisioning process for plugin updates, but this task will put IBM Notes into a configuration that bypasses this.

The controlhttp task is used to control a Domino Server’s http tasks. It ultimately just issues a console command to the domino console.

The maintenance warning task issues a console command to the Domino OSGi console which tells current users that there will be a maintenance outage in a certain amount of time

Issues a 'load design' console command for a server

Ant is a command line program, which you run by using the command ant and then supplying some command line arguments.

Let’s run our first ant build, our sample build will just print a hello message to the console.

You should see the following output

So we told Ant to run, but how did Ant know what we wanted to do?

The build file is an xml file that contains all the instructions of what you want to automate.

By default Ant will look for a build file named build.xml. You are able to call it something else if you want, but you will need to specify it as a command line argument.

Lets have a look at our build file for this project

We can see the root element of the build file is 'project'. We have a name for this project and a default target 'hello'.

There is a longer description of the build project, then some property definitions, and finally some targets each with one task within it.

Targets are used to create a sequence of tasks that you want to perform, and refer to that sequence by a name.

In this build file we have 2 targets hello and goodbye.

You can see in the root project element, hello is specified as the default target, and therefore this is the target that was executed when we told ant to run

Tasks are the building blocks of what you can automate. In this sample we are keeping it very simple and only using the 'echo' task to print messages to the console. But there are a whole bunch of default tasks available.

The Apache Ant project site is very well documented and I recommend having a look through the Overview of Apache Ant Tasks

Properties are useful to allow you to use the same build file, but customise it for different projects and environments.

Properties can be provided using a properties file, and they can also be provided directly in the build file.

In this build file, our echo tasks use a property called firstname

This firstname property is specified at the top of the build file.

Once a property is set, it cannot be changed, so the property value will remain whatever it was first set as.

A task can be set to depend on another task, in our example, the goodbye target is set to depend on the hello target (using the depends attribute). This means before we say goodbye we must say hello!.

Let’s try it out. This time because we are not running the default target we must specify it. Issue the following command

So this was a very short, very simple introduction to the concepts of Ant. We learned about the concepts of The Build File, Targets, Tasks, Properties and Task Dependencies.

These concepts will hopefully give you a good start to comprehend the rest of the tutorials in BuildXPages, in which we will use much more complicated targets and tasks to achieve some tasks for building and deploying XPages applications.

There is also a target called build. This will build the NSF. This target is also listed as the default target in the root element of the build.xml file.

This target makes use of the bxp:buildnsf task which will connect to the Headless Designer Plugin, and instruct it to build the nsf as specified by the task attributes.

You can see that the build target depends on init. init depends on clean, so when we execute this build target what will really happen is the following order of execution:

In this demonstration tutorial we have shown how the buildnsf task from the BuildXPages Ant Library works together with the headless designer plugin. We have demonstrated how to successfully build an NSF and also what it looks like when an NSF does not successfully build.

This tutorial assumes that you have successfully completed the 'Building An NSF' tutorial. After completing the 'Building an NSF' tutorial you should have an NSF in your local workspace. We will use this NSF as the basis for some of the deployment examples.

Then open your command prompt and navigate to the demo/deploynsf directory. Now you should be ready to start the demo!

This demonstration has some properties supplied via a build.properties file. You will see some of these properties referenced later on in the demonstration.

At the most basic Level, you may have built your NSF directly to a local Notes workspace, and just want to copy the .nsf file to another location. In this case you would just use a simple Apache Ant copy task. I will leave that up to you to research as it is very simple.

Instead of doing basic file-based copying, we can actually use IBM Notes to copy an NSF from our local workspace to a server, or from one server to another server etc.

To do this we use BuildXPages' copynsf task.

We are going to create 2 copies of the NSF that we built in the 'Building an NSF' demonstration, so that we can use these 2 copies in our next few deployment demonstrations.

We are going to create one copy to act as a template, and then another copy that will act as our 'production' nsf.

Here is the copydatabase target that we are going to run, you can see we are specifying the source and destination filepaths using the properties from the build.properties file. The copynsf task also has available attributes for source and destination server, but since we have not included them, it will just use the local notes workspace as the source and destination server.

To execute this target issue the console command ant copynsf

You should see some output like:

You should now have 2 new databases in your workspace:

Now that we have our Production and Master templates, we will configure one to inherit Design from the other. BuildXPages has a settemplatenames task which is useful for configuring template inheritance dynamically.

We will execute the following target which first sets the ntf’s master template name, and then it sets the production nsf to inherit from that template

To execute this target, issue the command ant linktemplates

You should see some output like:

You should also be able to inspect the database application properties in IBM Notes and verify that the templates have been set properly.

When you are ready to refresh the design of a database, you can simple use the refreshdbdesign task. The task allows us to choose the database we want to refresh, which can be local or on another server, and then also choose which server to refresh from which can also be local or another server.

What is handy about this is that you can refresh the design of a target nsf using an NSF from your local workspace. So, if you have built an NSF in your local workspace you can refresh an NSF on a server using the design on your local workspace.

In this demonstration we will just refresh a the local production database from the local template. This inheritance should already be set up in the previous set templates example, so we just need to specify the database that we want to refresh

To execute the target, issue the command ant refreshtemplate

You should see some output like this:

Since both the template and the production database were copied from the same nsf, there is nothing to refresh so you don’t see any design elements listed in the output, but if you were to make a change in the template and then run it again you will see the updated design element in the output

In this last step of our demonstration we will clean up after ourselves and delete the 'Production' NSF and the 'template' that we just created. To do this we can use the deletensf task.

To execute this task issue the command ant clean

The output of the deletensf task is not very useful, you should see some ouput like this:

If the database did not exist (so could not be deleted) you will get a build failed warning

In this demonstration we have shown how to copy databases around servers and local workspaces, setup design inheritance, refresh database designs and to delete databases. Hopefully these tools will come in handy when designing your own deployment process.

The demo/buildfeature directory contains the source code of a plugin, and also a feature.

We are going to execute the build target, lets have a look at it

The eclipse headless build performs all it’s operations in a 'build directory' which is basically like a working area, so before running a build, we have to prepare this build directory and make sure it has plugins and features we need to build.

We do this using buildxpages copytobuilddir task which copies a plugin or a feature to the build directory. The copytobuilddir expects there to be a buildDir set which specifieds the build directory location.

We then use buildxpages buildfeature task to trigger the build, and we specify the feature that we are building.

You should then see some output like so:

And then a lot more of that kind of stuff and finally, hopefully you see the BUILD SUCCESSFULL message

After the build is finished you should see (among other things) a zip file in the demo/buildfeature/buildDirectory/BuildXPagesDemo directory. This zip file contains the plugins and features that were built!

So this was a short demo of building a plugin using headless eclipse. The next demonstration tutorial shows how we can take these plugins and deploy them somewhere

At the end of the headless feature build process, you will have a .zip file of your plugins and features. The contents of your zip file will be something like:

Unfortunately although this format looks a bit like an Update Site, it isn’t quite there yet. We are missing is the site.xml file, which is a list of the features that can be found in the update site. So what we are going to do is to extract the contents of the zip and then generate our site.xml We will then have an update site! We will also create a .zip version of this update site.

The steps necessary for this are contained within the prepareupdatesite target in our tutorial’s build.xml file.

There are 3 tasks in this target

Lets have a look at the properties that this task depends on. We see we have defined whereabouts to find the built plugins zip, and we define the name of our update site that we are creating.

Also note our target depends on the clean target, so lets have a look at that target. This target simply deletes the output of any previous run of this task.

Lets give this a go by issuing the command

You should see some output similar to this:

And if you look in the tutorial folder, you should see 2 new entries:

We now have an Update Site! Even better, we have 2 to choose from, we can use it in archive format (.zip) or as the directory format.

The main 2 options you have for Deploying plugins to a server are:

My preferred method of deploying plugins to a server is to use an Update Site NSF. The advantage is that this NSF Update site can replicate to other servers, and that means you only have to deploy to your primary server. Another advantage is that you can delete older versions of plugins whilst the server is still running.

Otherwise if you are deploying to the filesystem of every server you may have a tricky time accessing each server remotely, also you cannot delete plugins that are in use when the server is running. It can be an option though if you are deploying to a local testing server.

If you are building NSFs headlessly then you may need to be able to automatically install the plugins to Domino Designer. Another reason may be that you want to automate this process for your developer machine, because it can get quite annoying to have to frequently update your own Designer Client with latest versions of the plugins that you are working on.

In any case here are some techinques to deploy plugnis to Designer.

Hopefully this tutorial has demonstrated some of the tasks that you can use to get your plugins where you need them to be! Let me know if you have any questions or suggested improvements to this tutorial.