Overview

This document is intended for IT administrative staff of the nFORM system, as a reference and guide when administering the system from a technical perspective (e.g., making configuration changes or while planning a move to a new hosting environment). Each installation of the nFORM system will have its own specific configuration files and templates that will be utilized to customize the application. Changes applied to one environment must also be made in all other environments for that client in order for them to take effect.

Architecture

Please see the nFORM Technical Architecture document for details on the nFORM technical architecture.

nFORM Build and Deploy Process

To facilitate the downloading, compiling, and deployment of the source code, Windsor uses the Jenkins Continuous Integration Server.

Open

Figure 1: Build and Deploy Process Diagram

GitLab Source Code

The test and production systems subscribe to Windsor GitLab server to retrieve deployed builds from Windsor’s code repository. The test server is subscribed to the beta branch of code which will contain new features to nFORM that have been made available for beta testing. The stable branch is the latest production version of nFORM.

Jenkins Continuous Integration Server

nFORM subscribers who choose to use the continuous integration capabilities for publishing code to their test and production environments. Jenkins functions as a gateway for downloading and compiling code from the beta and stable code branches, compiling the code, and deploying the code to the test and production environments. Although Jenkins can be scheduled to build and deploy automatically when changes are detected, Windsor recommends that the build and deploy process only be started by manually initiating it through the Jenkins interface when you are ready to upgrade. There are separate jobs for both the test and production environments in a properly configured Jenkins setup and each can have their own set of parameters to pass into the batch processes for correctly configuring your application.

Note: Windsor maintains a set of configuration files that have been set to match your configuration for internal testing. By default, this file is deployed with the application by Jenkins, and you will need to send your modified and tested configuration files to Windsor. It is highly recommended to maintain backup¹ sets of configuration files.

Batch Processes

Windsor has developed a batch file that will be triggered when Jenkins is deploying to either environment. In addition to cleaning out the files that are not required for the operation of the system, parameters can be set that will.

• determine the publishing location

• determine any configuration files to override

• decrypt any sensitive information

Account used by Jenkins

A local IIS User account is required to allow Jenkins to publish code to the different environments. This account is used by Jenkins to deploy files to the web directory used by the system. If an existing account is moved, then the new directory will require deployment configuration to be established using IIS.

When establishing this deployment account within IIS, the minimum permissions necessary to publish to the Website in IIS and restart the application pool must be created and assigned. Jenkins uses a batch file to obtain the secure credentials necessary for executing the deployment process. The bat file is used to gather credentials stored in the file: "c:/ci/credentials/[servername].txt". This will allow web deploy the access need to set up the ACL’s.

Implementation Steps

The nFORM system is designed to run in a wide variety of Microsoft-based environments and the implementation is relatively simple once the prerequisites are met. The following steps will be used to bring nFORM online with a new Windows Server:

1. Establish Prerequisites

2. Server Configuration and Verification

3. Deploy the Database

4. Configure the System

5. Copy the Source Files

6. Test the System

The sections below will describe each of these steps in detail.

Establish Prerequisites

nFORM is designed for any system meeting the minimum requirements described in the nFORM System Requirements document.

Configuration and Verification

IIS Configuration

Required IIS Components

The following components will need to be activated/installed with the IIS service:

Dynamic Compression

Application Pool Settings

It is recommended that a new application pool specifically be allocated for the nFORM application. This application pool must be configured with the following properties:

• .Net Framework 4.8.2

• Integrated mode

• Idle-Timeout value must be set to 0

• Recycling Specific Times value must be set to the specific time the application will be reset on a daily basis, typically in the middle of the night (e.g., 04:30:00). See Application Pool Recycle Scheduling in the appendix for further details.

• See Autostart Configuration section below for additional details on establishing process to maintain Application Pool readiness.

Virtual Directory Creation

The following will need to be established to prior to application publishing:

• Create a target folder on the Web Server where the application files will reside.

• Create a virtual directory in IIS, mapped to the file system folder containing the application files.

• Map the virtual directory to the established Application Pool.

Autostart Configuration (Optional)

For optimal application performance, the nFORM application should be autostarted daily to prevent the first user who uses the system from having to wait for the application to wake up and perform any pre-caching that is needed to run the application. The section below provides details for configuring Autostart for the differing versions of IIS.

IIS 7.0 and prior

IIS 7.0 does not provide built in capabilities to “autostart” an application so a process will need to be established to maintain Application Pool readiness. ARDEQ built a custom utility to perform this wake-up process which can be leveraged for older versions of IIS.

IIS 7.5 - Windows Server 2008 R2

IIS7.5 provides preload functionality through a special provider module. When configured this module calls a custom preload function in the template. The preload function simply calls the website using the localhost address (ie, http://localhost/nform). The provider must be registered at the server level before it can be used on individual sites.

All references to applicationhost.config refer to C:\Windows\System32\inetsrv\config\applicationhost.config.

1. Configure the application in IIS

• Ensure nFORM has a dedicated pool set to Start Automatically=True

• Include the manually specified pool recycle time as well, taking into account the server time zone offset.

• The root website must be configured to resolve as localhost. As such only one root level website per machine can use the auto start feature under IIS 7.5. The web site bindings must contain a port 80 binding entry for either localhost or *.

2. Configure the Windsor Preload service provider

• The Windsor.Commons.AspNet.dll included in the /lib directory of nFORM provides a function used to warm the cache in the event of an application pool recycle.

• If this is the first nFORM install on a server, add the definition of the WindsorPreload service into the config file. This is only necessary ONCE.

• Insert the following code inside the applicationhost.config <system.applicationHost> section:

3. Configure the application pool for auto start

• Open applicationhost.config and search for your application pool in the <applicationPools> section

• Modify the pool to include autoStart=”true” and startMode=”AlwaysRunning”:

4. Modify the IIS application to use the WindsorPreload service

• Open applicationhost.config and find the application in the <sites> section

• Modify the application to reference the WindsorPreloader library with serviceAutoStartEnabled="true" and serviceAutoStartProvider="WindsorPreloader"

• Alternatively, you can enter this value directly in IIS. Select the root web site and click the Configuration icon from the main panel. In the drop down at the top, expand system.applicationHost and

IIS8 - Windows Server 2012

IIS8 is very easy to configure for preload using the new Application Initialization module. When enabled, this module will hit the site when the pool is started, ensuring any initialization functions are run BEFORE a user hits the site. No special code is necessary.

1. Install required IIS components

The default Server 2012 install includes .Net 4 but no Web Server. You must ensure the required roles and features are installed on the server prior to application deployment.

• Run the Server Manager application

• Select Local Server from the left menu

• Scroll to the bottom to the Roles and Features section

• Verify the Web Server Role is selected

• Under the Web Server Role Features, in addition to default selections ensure the following are also selected

  • Performance

    • Dynamic Content Compression

  • Application Development

    • .NET Extensibility 3.5

    • .NET Extensibility 4.5

    • Application Initialization

    • ASP.NET 3.5

    • ASP.NET 4.5

    • ISAPI Extensions

    • ISAPI Filters

Open

Open

2. Configure the application pool

• Ensure nFORM has a dedicated pool set to .Net 4.0 Integrated mode.

• In the pool Advanced Settings set Start Automatically=True and Start Mode = AlwaysRunning

• Include the manually specified pool recycle time as well, taking into account the server time zone offset.

3. Modify the IIS application for Preloading

• Select the nFORM virtual application and click Advanced Settings

• Set Preload Enabled = True

Document Template Hosting (Optional)

In nFORM, designers have the ability to establish document templates (Excel, Word, PDF, etc.) which can be referenced in their forms and downloaded by submitters. As an option, a virtual directory can be established to store and host these ancillary documents. If this is needed, a publically accessible file hosting location needs to be established and made available to the public via a URL. Documents will be published to this location as needed.

Deploy the Database

The database can be established either by utilizing a database script followed by seeding the database with any necessary initial data, or a baseline database can be restored to the environment providing the necessary database structure and seeded data. The following section describes the processes for deploying the system in either scenario.

Scripted Database

If establishing the client database for the first time and a backup is not available for use, then the nFORM SQL Database creation scripts can be run on a new database by an administrator. This will create the necessary objects and seed data. A database login will need to be established with datareader and datawriter. And the custom privileges db_executor which enables the execution of stored procedures, for this database.

If the database already exists and is being updated, a custom database upgrade script will be established to facilitate the upgrade process. Windsor utilizes the Flyway tool to manage database versioning and scripting. Flyway will be run on the database to compare the deployed version of the database to the desired version to be deployed and will establish the appropriate script to upgrade the database.

Restored Baseline Database

If available, the easiest way to deploy the database is to restore the Windsor-provided database. A database can typically be provided based on the clients test version which has the additional benefit of allowing established forms to be included. Test data would typically be removed. The restore can be performed directly onto the production server. After restoring the database, a database login will need to be created or reconnected to the database user using the sp_change_users_login system stored procedure. Note: The database user used by the application must have db_executor, datareader and datawriter privileges.

FileStreaming

If FileStreaming is activated for the first time, a database script will need to be run to migrate files from the core database and to the file system. If interested in performing this process, please contact Windsor for the appropriate script.

Configure the System

All configurations for the system are within files managed in a central directory, [Root Directory]\conf\. It is imperative that these files are configured appropriately. Key parameters such as database connection information are necessary for successful operation of the system. Incorrectly configured key parameters will prevent the application from running at all until they are corrected for the environment. Integration configuration properties (e.g., queue names and security credentials, etc.) are necessary to support integration points. Please refer to the Configuration specific section of this Administration Guide for additional details.

Copy the Source Files

There are two alternatives for copying the source files for the application in support of the deployment process: direct file copy and continuous integration. The sections below describe each of these methods.

Direct File Copy Approach

A direct file copy deployment approach is useful when continuous integration is not an option or where clients are not comfortable with an automated deployment process.

To perform the direct file copy method, copy all source files from the deployment package into the destination directory on the web server. After the project is built with the “[Root Directory]\build\Deploy.bat /p” BAT file from a machine with .NET 4 installed, the appropriate files (stripped by the process of unnecessary source code) will be located in [Root Directory]\src\obj\Release\Package\PackageTmp\ folder.

Alternatively, the files in [Root Directory]\src\ folder can be copied directly from the application directory of another web server that runs the application.

Continuous Integration

Continuous integration is a great option for automating parts of the deployment process. This approach allows for automation and consistency in the process as well as performance of unit tests, as appropriate. It also allows for control of identifying particular versions of the application to deploy.

In a continuous integration environment, the deployment staff will simply need to initiate the deployment process on the continuous integration server and verify the deployment was performed correctly (no errors were encountered).

Test the System

The application can now be tested prior to official launch. Key tests to run include the following:

Register a user and assign roles to them.

Log in with the newly created user and verify that you receive the first-time user message and access reflects the roles assigned.

1. Create a submission:

   1. Verify that screens come up and the finder works successfully (if not, the application likely does not have database connectivity, or the jobs configuration may not be turned on)

   2. Create and submit a form and verify that you received an email to the email account of the user that submitted the form.

2. Download the pdf of the submission.

3. Make a payment (if applicable).
   
   

Configuration Options

The nFORM system is composed of the code files that reside in the IIS application directory and the nFORM database. IIS application settings and the configuration files must be deployed and configured correctly with the database setup and the SQL logins configured before the system will run correctly.

All code files needed by the application are located in the root directory of the application. Most files are used by the system and should never be modified. Some files may need to be modified if you wish to change your configuration options or implement new features or modify the colors or style sheet properties. The following aspects of the nFORM system can be customized for your needs:

• Site Branding

• Email and Message Templates

• Application Configuration

• Other Configuration Options

Instructions on how to modify the configurable options will be detailed in the Configuration section below.

Site Branding

The colors and some styles used by the application can be modified by a system administrator. Any system administrator performing this task should be comfortable using CSS. Windsor utilizes .less files to inject styles into the system. The .less files consist of CSS code and variables that can be set to override the base color scheme. The following directories and files those used for customizing the site styles.

• [Root Directory]/Content/CustomSite.less: Any organization specific style customizations can be defined in this file.

• [Root Directory]/Content/Colors.less: Base colors are controlled in this file.

• [Root Directory]/Content/Custom/: Any organization specific header graphics are stored in this directory.

Lookups

Lookups are lists that can be stored in the database tables LOOKUP and LOOKUP_VALUE. The LOOKUP table contains the metadata that describes the lookup, while the LOOKUP_VALUE table uses the Name column to populate a list of items. This is ideal for lists that are commonly used, or long lists in which typing in the name makes finding the one you want much easier. Lookups can be used in a short text control with the autocomplete feature turned on, or in the single select or multi select controls. The name column will be both the value and the selected index of the dropdown array.

Email and Message Templates

The system delivers system messages, including emails and pop-up, using templates that are configurable per installation. The templates can be modified to accommodate the structure and content a client wishes to display, in html format. This section describes how to modify the messaging templates.

See the nFORM Email Template Guide for additional details.

Configure System to Support Anonymous/Guest Submissions

It is possible to configure a form for external users to fill out and submit a form without creating an account or logging in to the system, a common use case for complaint forms.

To enable a form designer to make a form available for anonymous/guest user support, the security.guestAccountCanLogin setting in the varsOverrides.config must be set to true.

System Configuration

The system configuration is used to designate templates, configure communications with other servers, or turn on / off features or system options. XML formatted configuration files are used to set the majority of options in the nFORM system. These files include a number of name value pairs which define the desired configuration. Files are easily modified by changing the value portion of the configuration setting; however some values will be limited to a specific range of permitted values or may be limited due a client specific infrastructure. Certain values are simply true or false value while others are text.

Note: all configuration files can be found in the [Root Directory]/conf/ folder of the system.

Open

Figure 4: Configuration Hierarchy

Relevant files

Below is an overview of configuration files and how they can be modified by system administrators to customize the nFORM application to meet their needs.

• [Root Directory]/Conf/vars.config: All default system configuration variables are located in this file. This file sets the default configuration used by nFORM and it should NOT be modified but can be utilized as a reference for identifying (and copying) configuration properties to add to your organization specific override files explained further below. This file contains the default configuration for the application and contains every configuration value available.

• [Root Directory]/Conf/VarsOverrides.config: This file allows an organization to set specific configuration settings. Any configuration values included in this file will modify (or override) the default configuration identified in the vars.config file.

• [Root Directory]/Conf/VarsEnvironmentOverrides.config: This file provides a means for an organization to identify environment specific configuration settings. Any configuration values included in this file will modify (or override) the organization specific configuration identified in the VarsOverrides.config.

• [Root Directory]/Conf/ varsOverridesSensitive.config: Analogous to the corresponding varsOverrides.config, but is provided for documenting sensitive settings (e.g. encryption passwords) which need to be further secured. For agencies subscribing to Windsor’s Build and Deploy process, sensitive information can be encrypted by the agency and provided to Windsor. The build and deploy process (at the agency) will have access to the decryption key for deployment, but Windsor will not have access to this configuration data.

• [Root Directory]/Conf/ varsEnvironmentalOverridesSensitive.config: Analogous to the corresponding VarsEnvironmentOverrides.config, but is provided for documenting sensitive settings (e.g., encryption passwords) which need to be further secured. For agencies subscribing to Windsor’s Build and Deploy process, sensitive information can be encrypted by the agency and provided to Windsor. The build and deploy process (at the agency) will have access to the decryption key for deployment, but Windsor will not have access to this configuration data.

• [Root Directory]/Conf/Web/connectionStrings.config: The connection strings utilized by the system environment are defined in this file.

• [Root Directory]/Conf/Web/authentication.config: The authentication method and settings for the system environment are defined in this file.

Please note that any changes to the configuration will require that the application pool is reset for the changes to fully take effect.

Configuration Values

Collections of like configuration items have been organized into like categories. A high-level synopsis of the application configuration category and its related items are provided below. In addition, a definition of each configuration value is provided.

Organization Information

Configuration relevant to a specific organization is possible. This includes configuration options such as support/administrative email addresses or groups email accounts, mailing address, homepage links, the application title for search engines as well as the official and shortened name of the organization.

Database Settings

The Database settings stored in the configuration files are essential to operation of the system and must be properly configured for the system to run. The two components are the connection string and the configuration value that designates the correct connection string to utilize.

Email and Message Settings

The nFORM system sends the majority of its messages via a SMTP mail server. In this configuration section the mail server address, any required values to send and receive emails, and the recipients of the internal emails can be specified.

By default, the base email templates will be utilized. If the intention is to create custom email content, the location of the organization specific email templates will need to be specified in the email.templateOverridePath variable. All system emails are set to use the same designated email address and sender name for the system. This server will need to be made accessible and configured for access prior to operation of the system, and the designated recipients of the internal emails will need to be established.

In addition to specifying the settings used for identifying and authenticating sending messages with the email server, any emails sent out from by the system can be configured to have a custom email subject by overriding the default value.

Configuring Workflow Actions

Workflow configuration can now include sending documents, changing status of a submission, or completion of a step, in addition to sending out email for milestones. Each step can be set up to perform these actions based on an event. Events include the completion of a step, the activation of a step (it becomes the next step in order to be completed), if its past its target date, or approaching the target date. There is also an event of “Payment Completed” which will activate if a payment is moved from “Due” to “Paid” or “Waived”.

Application Defaults & Control Features

The system allows defaulting of some values in the system when forms are to be distributed to the regulated community in a specific location and it would be exceptional for it to be changed. Defaulted values are system wide and can be overwritten by the person submitting the form when they are in the data entry step.

The values that can be defaulted include the state and country code for the contact control and the default latitude or longitude of the location control.

Inline Help, Error Messages, Confirmation Messages

Inline help, error messages and confirmation message text is available on the pages of the application and can be modified by application administrators. This text is generally brief in nature and intended to instruct the user on the functionality of the area and interpreting a successful or failed action. These messages can also be customized by overriding the base values with values placed in the override files specific for the agency. These messages can be refined by adjusting the configuration values which are prefixed with “message.” or “error.”.

Challenge Questions

As part of the electronic submission ability, users are required to provide answers to 5 security questions of their choice. The challenge questions are used to ensure identity at the time of submission for an electronic signatory certification required form.

The questions that are presented for the electronic signatory verification can be modified through the configuration values set for this group of questions. Additional questions can also be added by adding addition entries with the same naming convention, or they can be removed. These challenge questions can be refined and augmented by adjusting the configuration values which are prefixed with “message.user.questionNN.text”, where NN is the number of the question.

The challenge question system has been expanded to obtain questions from external systems. Use of an external system requires a base integration with the client security system. Once established, the viability of using said system for challenge questions can be investigated.

Scheduled Jobs

nFORM has a series of administrative tasks that must be run. The following jobs will need to be scheduled for your system.

• Pending deletion of a draft submission notification

• Deletion of a draft submission

• Processing step approaching target date notifications

• Processing step past due notifications

• Rebuilding the search index for importing form data

• Population of staging data for exporting form data

• Autocomplete company list building

The system uses the CRON scheduler to manage all job schedules. Standard CRON scheduling syntax can be used to adjust these schedules.

The CRON format “SE MI HR DY MN DW”, where SE is the seconds (0-59), MI is the minutes (0-59), HR is the hour (0-23), DY is day (1-31), MN is the month (1-12), DW is the day of week (0-6). A star can be used to represent any possible value and a question mark can be used to represent any day of the week.

Please note that after tasks that are used to index the site have been run, the application will need to be reset. Windsor recommends that you schedule the application pool to reset 15 – 30 minutes after the last scheduled job.