XPages to Web App Revisited: Part One

Many years ago I wrote a series of blog posts on the topic of XPages to web app. At the time my target technology was Vaadin running in an OSGi plugin on Domino HTTP server (initially) and then CrossWorlds - Daniele Vistalli’s innovative approach to use Domino data via OpenNTF Domino API on a Websphere Liberty server running as a sidecar to Domino. My experience of developing with Vaadin lagged behind the technology, because it quickly evolved not only to Java 8 (and undoubtedly beyond) but used annotations which required Servlet 3.0.

Technology

Today there are a variety of options for web application. Adjacent to Domino is Jesse Gallagher’s JakartaEE approach. Domino REST API can host applications as well. Frameworks like Angular and React have gained prominence. JSP is still seen in some places, but seems to have slipped from prominence. But after my session at Engage with Stephan Wissel, and particularly the rapid evolution of browser support over the last few years, my target is traditional web, hosted in Domino REST API’s server.

Let’s address the elephant in the room. Why not Volt MX Go? This is a small app, one user and I don’t have a hosted environment or want to set one up for something this small. I know Volt MX, and this is about growing my learning. I want to see what I can do with a vanilla web development approach.

But it is still very relevant for Domino developers looking to use Volt MX Go - or indeed any other technology. Domino REST API will be the mode of access, as it is for Volt MX Go. And the primary focus of this series will be about developing a web application, not taking a Notes or XPages user interface and reproducing it on another framework. Whether you’re using a JavaScript framework like fetch or Foundry operations is barely relevant, both could be used for any web development framework. The CSS techniques are relevant if developing for modern browsers. Even the web components can be used within Iris.

Requirements

As I said, the app is a small app - a handful of forms and views. There is no workflow for the data, it’s just data entry, retrieval for lookups and basic analysis. The original app is still expected to work in parallel. I could manually verify the data, or I could write integration tests - in LotusScript, using the unit testing framework developed for VoltScript - to target data provided by XPages and from the new app. The same tests should provide the same results. If they do - and if the tests have been written well - the new app will be proven to be working correctly with the database and providing valid data.

When the original application was developed, a traditional XPages approach was taken - bootstrap theme for responsiveness, navigator component in custom controls for main navigation and administration views, linking to Data View components.

The new app will not be doing any of this!

Why?

First up, this app has been in use for a few years now. If you’re modernising an app that’s been around any length of time, the first step should be working with the users to see how they use it, their most common actions, their pain points, the logical steps they take to do their job with the app. I’m not talking about technical steps (go to this view, click this button, fill in the fields etc). I’m talking about use case tasks.

In this case it’s:

create a ship spot. If the ship is not picked from previous entries, a ship is created as well as the spot.
look for a ship by name to edit it or see when it was spotted. There are a lot, typical approach is jump to page x, then page y until the relevant ship is found. This is not efficient, but it’s the typical view-driven approach.
names change occasionally, but there is a unique ID. There’s no easy way to find by that currently.
look for ships by line, which is a combo box. There are not many options.
create a port and/or country. These were originally under an “admin” area, but the role is not relevant. Currently the flow is:
- create a ship spot, realise the port doesn’t exist.
- ship spot needs saving.
- switch view.
- create port.
- if country doesn’t exist, create country.
- then go back to create port
- then edit spot and add port.
This should raise red flags to any developer. Modernisation of the app should improve this and there is significant scope to do so. How? That’s not sure yet, but improving this should be a must.
each trip, create a trip with start and end date. Previous trip needs changing to inactive.
retrospectively, look at what what created during the trip. Currently this is a table of data. Again, there’s an opportunity to improve this.
trips may no longer be required, so I’ll leave that functionality for now.
spots are not regularly reviewed directly, occasionally for spots a day or two previously.
countries, ports and ships are used for pickers in ship spots.

Analysis of Requirements

A few things should be apparent here:

scrolling through views is not done. So why make that the entry point to documents?
access to documents is targeted on a few use cases.
there are a few “create” actions that are key.
creating a port, ship or a country is only done when adding to a ship spot.
the original navigation and editing paradigms were based on the framework. This takes a great deal of self-awareness and an ability to challenge instinctive choices. But it’s key to modernisation and an optimal user experience.
when the original XPages application was developed, creating and viewing multiple related docs in a single UI was a shift from Notes Client. Data View gives innovative layouts. But the rest of the user experience was typical for a Notes or XPages app. And most significant of all, it doesn’t fit how the app is used.
the app is used on mobile and network connection can be patchy.

Challenging Instinctive Choices

Every developer should fully understand the decisions they instinctively make because of the platform and framework they are using. As stated, views are the standard entry point for Notes Client. And having lots of documents in a view is normal, especially when business owners fail to prioritise archiving of data.

But think of the most commonly-used web application: Google. Do you scroll through a view of documents categorised on a type or sorted? Of course not. You search. How often do you page through 100 matches? You don’t. If it’s not in the first couple of pages, you typically try a different search. Think of another web application: Wikipedia. The same is true. Web applications have a paradigm that has become standard - and become standard since many Domino developers built their first Notes database. But it’s become standard for a good reason: the approach of users for some years now is “find something quickly, do what you need to do with it, move on”. Modernising a Domino application should take into account how user expectations have changed - even if some of the users are more resistant to change. Similarly modernising a spreadsheet into a web application will not satisfy if it just reproduces the spreadsheet experience in a browser.

But that’s not the only aspect to bear in mind for Domino and Notes. The data is programmatically accessed locally. Move to a web application hosted elsewhere and you will typically need to pull data over the HTTP protocol. If you don’t appreciate the difference there, your application will probably fail and you must bear at least part of the blame. “But the customer said…” is no excuse - you are the expert, it is your job to educate.

User Experience

So the “navigation” will not link to views of documents of a specific type sorted in a particular way. It will focus on specific actions. The primary action is not to look at a specific view, so the home page will be tiles. There are only a small number, so it will work nicely on a home page. The home page will display the current active trip, clicking it will open the trip, with actions to “switch trip” or create a new one. It’s not likely to be a huge list, so a massively scrolling view makes no sense.

Comparison is not done, so again no point in using a view.

“Find ship” will allow searching by name (with wildcards) or unique reference. We’ll not commit to a specific layout of results yet. Let’s see what options we have. Results should be limited, so re-sorting makes no sense. The key purposes are checking it exists, editing the ship or viewing it.

If we can cache some data - trip, ports, countries, maybe even ship names - across the whole (front-end) app, we will get better performance. Only ships will be a reasonably significant data set, so we will not commit yet. None of the data has any sensitivity, so we don’t need to worry about that. Because there is only a single user, we don’t need to worry about webhooks to update the list or background web workers to check for updates. We won’t provide a way to clear the cache, we’ll keep it clean and add it if required. We’ll fetch the data after login (async), providing a get-out. And the XPages app is not going anywhere (yet), so worst case scenario the old app can be used instead. This gives us zero downtime.

Technologies Involved

Let’s talk technologies here. We’ll use FlexBox (just html and css) for layout. We’ll use web components for many of the piece-parts of the application (login form, “view entry”, “doc”). We’ll use event subscribers to interact with JavaScript function. We may use some other external web components, maybe not.

We’ll use CSS. But CSS has evolved massively since the 2000s, helped by the fact that most end users have modern browsers. No longer do we have to develop for Internet Explorer 6 - indeed developers are probably not developing for Internet Explorer at all. Businesses and all consumers should be on Edge, if they’re not on another browser.

And we’ll use fetch to talk to Domino REST API to perform CRUD operations. An early step will be create DRAPI modes and get the swagger spec. We will also use mock data at times for local coding and testing.

This is about learning, and quite a few aspects will be new to many Domino developers, maybe some web developers, and certainly to me. It will certainly not answer all the questions you will have as you develop web applications. For example, I don’t have to worry about 100% up-time or supporting massive numbers of users.

But I hope others in the Domino community will pick up that baton and share their expertise. A community is smarter because many share. When people stop sharing, the smart look for new challenges, the rest stagnate and the community will never recover.

XPages to Web App Revisited: Part One - Introduction

Table of Contents