Summary

We have been working for a while on Domino Visual Editor, Form Builder, and NSFConverterPortalProject for a while, but there was some confusion in the last Moonshine meeting about how all these pieces will work together.

NOTE: This page is focused more for the design of this feature. For instructions on using it yourself, check this page.

Use Cases

There are two main use cases we want to support:

Converting an Existing Database

For this case, we want to take an existing Domino database and quickly make the data available through a Royale application. Once we have the basic application done, the user can make further applications.

1. Generate a Domino Visual Editor project for an existing Domino database using NSF Converter
2. Generate Java CRUD agents based on the project.*
3. Generate a Royale application based on the project. See this issue.
4. The user can tweak the database configuration and generate the projects again as desired
5. Once they are satisfied with the database, the user can start manually modifying Royale interface, agents, and database for their specialized needs (hidden fields, custom actions, etc). If they want to rerun the above steps, their modifications will not be preserved (but they could be manually copied). The generated projects will serve as examples when writing additional code.

Creating a New Database

For this case, we want to quickly mockup and create a new Domino application with a Royale interface. The database and application can then be customized.

1. Create a new Form Builder project. This could also be a Domino Visual Editor project, but I'll focus on the Form Builder project for now
2. Generate a Database based on the project. This database should contain the Forms and Views needed for basic management of the application
3. Generate Java CRUD agents based on the project
4. Generate a Royale application based on the project

The planned workflow will be something like this:

1. The user designs some forms with Form Builder
2. The user generates and tests and interface from From Builder. The individual components can be generated and tested separately if desired.
3. The user updates and regenerates the interface to add fields or forms they missed. They can repeat this process until they are satisfied with the basic database.
4. Once they are satisfied with the database, the user can start manually modifying Royale interface, agents, and database for their specialized needs (hidden fields, custom actions, etc). Form Builder is designed for one-way generation, so it will overwrite any changes by the user. We may allow limited options for additional generation in the future.

Components

Here is a diagram of how the different components work together. The components will be explained in more detail below.

NSF Converter

As the first step of the Converting an Existing Database use case, we need to convert an existing Domino database into a Domino Visual Editor project. We do this with NSFConverterPortalProject.

NSFConverter is designed to run inside a Vagrant instance. The user can access the web interface to convert a database. The expected inputs are:

• Selected NSF: The database to convert
• Selected XML: This was originally a configuration file from Structure4Notes to provide additional design information for the database. This is not currently used for NSFConverter.

The user is expected to create a local copy of their database to test. The recommended settings are:

• The database should be design-only copy (not required)
• The database must not locally encrypted
• The ACL must grant at least Designer access to the -Default- entry
• The database design must not be hidden.

NSFConverter will actually generate XML format that does not exactly match the Monshine format. When opening in Moonshine, these files will be automatically converted to the Moonshine format.

We also intend to add functionality to convert the database in Moonshine using Vagrant-REST-Interface.

Domino Visual Editor

The Domino Visual Editor project gives the user a visual interface to design and configure a Domino form. This is intended as an alternative to using HCL Domino, while still having similar functionality.

The form configuration is stored in "intermediate XML", which is intended to be a language-independent configuration that defines the structure and layout of the form.

In the future, we will add support for more Domino Design elements:

• Views - this will be needed to generate Java agents
• Subforms and shared columns - reusable components
• Actions and Shared Actions define additional logic for the database. The logic will be written in Formula language, so this will only be useful for Domino applications. For other exported applications, my short-term plan is to output the formula as a comment and leave the language-specific implementation for the developer

Form Builder

Form Builder is tool to generate Forms and Views based on a simplified list of properties and field definitions. This offers minimal control over the layout, so the generated applications will use generic templates.

Generated Database

Both Domino Visual Editor and Form Builder are based on NSFODP, which is create and maintain a Domino database based on a Maven project. The database can be generated with Project > Build with Apache Maven

The database can be generated from:

• The local machine. This requires a local HCL Notes installation, and it will occasionally crash and require a Notes restart.
• A Vagrant instance with Domino installed. See this issue. This will avoid the local Notes requirement, and it may be easier to auto-correct the crashes in this case.

We want to be able to generate and deploy the database to three locations:

• Local machine (current). This is useful for early testing.
• Vagrant VM with Domino. The database needs to be on a server for it to work with the Java Agents. The Vagrant VM offers a safe, disposable environment to test the database. (ISSUE PENDING)
• Remote Domino server. Eventually the database will need to be deployed to a remote server for use. This may also be used with a remote Vagrant instance for users who can't run Vagrant locally. For this case, the database will need to be signed by a valid user or server key so that it can run on the server. (ISSUE PENDING).

By default, the generated database will have a very permissive ACL (security) configuration to make it easy to use during initial development. The developer will need to update the ACL once this is used for production data (we don't have immediate plans to implement this in Moonshine).

Java Agents

The Java Agents will be based on the Moonshine-Domino-CRUD API. These agents will provide access read and update the database. The agents implement a general JSON interface that could be used by other applications as desired.

The agent project will be generated from a template provided in the Moonshine-Domino-CRUD project. The project may also include documentation and deployment scripts.

The agents should be customizable:

• Remove agents for actions that are not desired (for example, Create, Read, and Delete for read-only applications)
• Restrict visibility for certain sensitive fields
• Add additional actions

The agents can only run from a Domino database on a web server, so they will need to be deployed. The default would be to deploy them to the Generated Database, but they could also deployed to a separate database (to allow a more restrictive ACL configuration). Some options:

• DXL Importer. This tool will import the agent code into the target database as DXL. The local Notes user will need to have permissions to create, sign, and run agents on the target server. We could consider running this action from a Vagrant instance to avoid having a local dependency on the Notes client. See this issue. TODO: can I DXL Import to a local database instead to avoid remote deployment?
• Import into the NSFODP project. I suspect that there is a way to do this already but I'll need to do more research

Royale Application

The Royale Application should provide a minimal interface to access and update the database with CRUD applications.

We would like to support generating the Royale Application as a standalone project. In this case, the application would use an in-memory data model for the CRUD operations. This will allow the user to test how the application will work without having to build the database agent agents each time.

This application should be a good starting point that developers can customize for their individual requirements. Some example customizations:

• Make the interface read-only. This will be useful for existing databases that do not need to be updated directly by end-users
• Add server-specific authentication
• Define additional operations that are needed in the application.

The application can be run in one of the following ways:

• Opening the files directly. This will be sufficient for an in-memory test
• Running with a simple local web server. This will be needed to avoid CORS issues for a production (and Vagrant?) server. In some cases, this may also require a hosts file entry
• On a remote server. This will be used as the developer moves closer to production, and it may also be convenient in some cases to avoid CORS errors.