Getting Started with the NSF ODP Tooling
Wed Aug 26 10:57:53 EDT 2020
- Getting Started with the NSF ODP Tooling
- NSF ODP Tooling: Setting Up Jenkins Builds
I've mentioned the NSF ODP Tooling project quite a bit here, and a lot of that is just a reflection of how much use I've gotten out of it and how much time it's been saving me in my regular work.
Part of it is also, though, that I think that it should see wider use. I realized that the project can seem off-putting, or reserved only for the sort of lost-in-the-weeds sort of work I do. Generally, when I mention it, it's in the context of a massive project with a bunch of OSGi plugins, or describing the intricate work that went in to implementing it.
So I figured this was as good a time as any to describe the simplest-case scenario to get use out of the project: wrapping a normal ODP, without plugins, and then building it into an NSF outside of Designer.
Environment Setup
Domino Installation
To get started, you'll first need either a local Notes/Domino installation or a remote Domino server. Since it involves slightly-less local configuration, we'll go with the remote Domino path for now. Download the latest distribution ZIP [from the project on OpenNTF](https://openntf.org/main.nsf/project.xsp?r=project/NSF ODP Tooling/releases) and install the update site from the "Domino" directory on your server in the same way you would the OpenNTF Domino API or other XPages library, and restart HTTP.
Maven and Java
The second thing you'll need is a Maven installation locally. If you're running on macOS or Linux, the easiest way to install this is with a package manager, such as Homebrew or apt. On any platform, you can also follow the download and installation instructions from the official Maven site. You'll also need Java installed - nowadays, I use AdoptOpenJDK.
You'll also need a Maven "settings.xml" file to point to your server. If you don't have such a file already, create an ".m2" directory (with the leading dot) in your home directory. This is the same process as in my original Maven setup guide, but with different contents. Configure the contents to look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | <?xml version="1.0"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>nsfodp</id> <properties> <!-- the server name can be anything as long as it matches below --> <nsfodp.compiler.server>some-server-name</nsfodp.compiler.server> <!-- specify the HTTP/HTTPS URL for your Domino server --> <nsfodp.compiler.serverUrl>https://some.server/</nsfodp.compiler.serverUrl> <!-- set to true if you use a self-signed SSL certificate --> <nsfodp.compiler.serverTrustSelfSignedSsl>true</nsfodp.compiler.serverTrustSelfSignedSsl> </properties> </profile> </profiles> <activeProfiles> <activeProfile>nsfodp</activeProfile> </activeProfiles> <servers> <server> <id>some-server-name</id> <!-- Use a Domino HTTP username and password --> <username>builduser</username> <password>buildpassword</password> </server> </servers> </settings> |
NSF Project Setup
The core On-Disk Project you create for your NSF is done using the normal Designer source-control. This process hasn't changed over the years; if you're unfamiliar with creating ODPs and working with source control, resources like the NotesIn9 episode remain very useful (though using Mercurial is an odd choice nowadays).
For this example, I just created a new NSF, but you can start with any simple-to-moderate NSF. For now, avoid anything that uses external XPages libraries or platform-specific things like ODBC in LotusScript. Right-click the NSF and go to "Team Development" ? "Set Up Source Control for this Application":
In the following wizard, give it a name (your choice) and uncheck "Use default location". Pick a destination for your created project, but make sure to put it within an "odp" subfolder of your main project folder - that'll be important later.
I also uncheck "Go to Navigator view after project is created" because I use Package Explorer for this. It wouldn't hurt to use the Navigator view, tough - it's basically the same idea.
At this point, you can close out of Designer if you want - it won't be needed for the rest of this.
Maven Project Setup
Create a new text file called "pom.xml" and put it in the project folder, next to the "odp" directory.
Set its contents to this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | <?xml version="1.0"?> <project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>nsfodp-example</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>domino-nsf</packaging> <pluginRepositories> <pluginRepository> <id>artifactory.openntf.org</id> <name>artifactory.openntf.org</name> <url>https://artifactory.openntf.org/openntf</url> </pluginRepository> </pluginRepositories> <build> <plugins> <plugin> <groupId>org.openntf.maven</groupId> <artifactId>nsfodp-maven-plugin</artifactId> <version>3.1.0</version> <extensions>true</extensions> </plugin> </plugins> </build> </project> |
In a terminal window, go to the project directory (the one containing this "pom.xml") and run mvn install. After a bit of churning, you should see some output ending like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | [INFO] --- nsfodp-maven-plugin:3.1.0:compile (default-compile) @ nsfodp-example --- [INFO] Compiling ODP [INFO] Installing bundles [INFO] - Installed no bundles [INFO] Creating destination NSF [INFO] Importing DB properties [INFO] Importing basic design elements [INFO] Importing file resources [INFO] Importing LotusScript libraries [INFO] Uninstalling bundles [INFO] org.openntf.nsfodp.compiler.equinox.CompilerApplication#end [INFO] Generated NSF: /Users/jesse/Projects/nsfodp-example/target/nsfodp-example-1.0.0-SNAPSHOT.nsf [INFO] [INFO] --- maven-install-plugin:3.0.0-M1:install (default-install) @ nsfodp-example --- [INFO] Installing /Users/jesse/Projects/nsfodp-example/target/nsfodp-example-1.0.0-SNAPSHOT.nsf to /Users/jesse/.m2/repository/com/example/nsfodp-example/1.0.0-SNAPSHOT/nsfodp-example-1.0.0-SNAPSHOT.nsf [INFO] Installing /Users/jesse/Projects/nsfodp-example/pom.xml to /Users/jesse/.m2/repository/com/example/nsfodp-example/1.0.0-SNAPSHOT/nsfodp-example-1.0.0-SNAPSHOT.pom [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 9.346 s [INFO] Finished at: 2020-08-26T10:29:10-04:00 [INFO] ------------------------------------------------------------------------ |
The specifics will change a bit based on your system, but the main things are to see those "Compiling" and "Importing" lines followed by the "BUILD SUCCESS" banner at the end. If you look in your project directory, you'll see some generated support files and, within the "target" directory, the built NSF:
Conclusion
And that's it! Probably, at least. You can use this with most classic Notes apps and with XPages apps that just use the built-in components and JARs inside the NSF. Things can get more complex from there, and the repository contains an example of an XPages application that uses an OSGi-based library.
I plan to go into some of those details in future posts. In addition, I will demonstrate how to do this compilation in Jenkins, which allows you to have the NSF built automatically whenever you or someone else on your team commits a change to source control.