...
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, and
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.
...
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 The web site bindings must contain a port 80 binding entry for either localhost or *.
...
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
...
...
2. Configure the application pool
...
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.
...
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.
...
Log in with the newly created user and verify that you receive the first-time user message and access reflects the roles assigned.
...
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:
...
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.
...
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.
...
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.
Setting | Definition |
app.name | Name of the system (e.g.: ePermitting, nFORM, etc.) |
app.title | Title of the Application |
app.headerImageLocation | Path to the header image used by the system |
app.home.url | URL target for the home button |
app.termsOfUseLink | Allows you to specify a page to serve as your terms and conditions and privacy policy |
app.footerClientAddressHtml | Physical address shown on the footer |
app.organization | Organization or Agency name |
app.organization.offical | Full name of the organization |
app.organization.site.url | URL target for the Home button |
app.organization.site.name | Name for the Home button |
app.date.format | Format to use for date displays |
app.timeZone | The time zone basis if different than the default server time zone. Options include: Hawaiian Standard Time Pacific Standard Time Mountain Standard Time Central Standard Time Eastern Standard Time Arizona and Indiana have different time zones. Time-zones are generic and will use localization to determine exact time. The full list of valid values can be generated by TimeZoneInfo.GetSystemTimeZones(). |
app.allowedNetworks | Limiting Access to certain networks can be set here by entering the IP address of the allowed networks. |
app.excludeRobots | Enable search engine robot exclusion |
app.secondaryPayment.addressLabel | The label for a secondary payment address (e.g., “Overnight Mail”), if a secondary payment address is desired. If all app.secondaryPayment properties are empty, no secondary address will be displayed. |
app.secondaryPayment.address | The mailing address for a secondary payment address, if a secondary payment address is desired. If all app.secondaryPayment properties are empty, no secondary address will be displayed. |
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.
Setting | Definition |
app.connectionstringkey | Reference to the name of the connection string to utilize, from the connectionStrings.config file where all available connection strings are found. |
app.blankStringsToNulls | Determines whether the application will convert all blank strings to null prior to committing the data in the database. |
Email and Message Settings
...
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.
Setting | Definition |
email.isSendEnabled | Master switch" for email - turn it on or off by toggling this value. |
email.support.address | Support Email Address – listed as the email contact on the site. This can be an individual or email group. |
email.admin.address | All security and system emails will be sent to this address. |
email.fromAddress | Address used to send notifications to users |
email.fromAddressDisplayName | Display name |
that shows on emails to users |
email.templateBasePath | Path to the base template files |
email.templateOverridePath | Path to the active set of email templates |
email.smtpServerHost | IP address or DNS of the SMTP server |
email.smtpServerPort | Port used by SMPT mail. Default is 25 |
email.useSsl | Determines whether SSL is used to encrypt emails |
= Your SMTP server must support this feature. | |
email.smtpServerUsername | Username for sending email if required |
- leave blank if it is not going to be used. | |
email.smtpServerPassword | Password for sending email if required |
- leave blank if it is not going to be used. | |
email.genericName | Generic Name for addressing emails if user name is not available |
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.
...
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 a 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”.
...
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.
Setting | Definition |
location.latitude | Default Latitude for the starting point for the location control |
location.longitude | Default Longitude for the starting point for the location control |
contact.state | State can be pre-populated for the contact control |
-leave blank if you do not want to utilize this feature. | |
contact.country | Country can be pre-populated for the contact control |
- leave blank if you do not want to utilize this feature. | |
attachments.allowConfidential | Determines if you want to allow confidential attachments |
attachments.largeFileMessage | A message displayed with the attachment control, intended to represent the recommended maximum file size allowed. |
Inline Help, Error Messages, Confirmation Messages
...
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.
Setting | Definition |
jobs.isEnabled | Global switch to enable/disable all jobs |
jobs.approachingTargetDate.schedule | Schedule of when to notify submission owners that their submission is APPROACHING the target completion date |
jobs.pastTargetDate.schedule | Schedule of when to notify submission owners that their submission is PAST the target completion date |
jobs.pendingDelete.schedule | Schedule of when to notify submission owners that their unchanged submission will soon be deleted |
jobs.deleteOldDrafts.schedule | Schedule of when to delete abandoned/unchanged draft submissions |
jobs.rebuildSearchIndex.schedule | Schedule of when to rebuild index of data that is used to populate new data templates |
jobs.exportControlValuesService.schedule | Schedule of when to export any new/updated submission control data to the export table |
jobs.buildCompanyLookup.shedule | Schedule of when to collect company information from the database to populate the autocomplete company name on registration |
Payment Processing
nFORM supports the use of 3rd Party Payment Processors to collect payments for form submissions, if desired.
Detailed Payment Processor setup is out of scope for this document, as they will be specific to the Agency’s needs. Please see the Integration Guide for further details.
Setting | Definition |
app.secondaryPayment.addressLabel | The label, if provided, for the secondary payment address |
app.secondaryPayment.address | The address, if provided, for the secondary payment address |
app.paymentInstruction.message | Displayed on the payment screen for both online and offline payments |
app.paymentVoucherInstruction.message | Payment instructions on the mail in voucher (offline only) |
Document Management
The system can archive files on a Document Management server (e.g., S3 for cloud applications, File System of SQL FileStream for on premises and nVIRO document management systems for nVIRO solutions) that is accessible by the system itself. When Document Management Integration is active, files will be published at the time of submission to the Document Management server, and an email will be sent to the system administrator email address if there was problem publishing. This also allows the user to publish an existing form by enabling a button on the submission details screen.
...
nFORM provides the ability to collect an a unique identifier.
If you need to collect information about the submission for integration purposes with an existing system, you can define a field that is collected during the processing information step of the wizard that allows you to define the label of a simple text field that is 100 characters in length.
Setting | Definition |
app.submission.alternateidentifier.show | Determine whether an alternative identifier value is enabled |
app.submission.alternateidentifier.label | The label/name displayed with the alternative identifier field |
Notes
Notes are used by the internal users and the system to convey information to other internal users or submitters about a submission. Notes used to communicate with the application are considered external notes, while notes from the system or internal user generated notes are only viewable by users with internal access.
Note configuration properties allow you to define the label that appears on notes as well as the colors that define internal, external and completed notes.
Setting | Definition |
note.label.internal | Label for internal notes that the submitter cannot see |
note.label.external | Label for external notes that will be viewed by the submitter |
note.color.internal | Background color for internal notes |
note.color.external | Background color for external notes |
note.color.complete | The color of a note marked complete |
| Anchor | ||||
|---|---|---|---|---|
|
...
Internal Data is metadata about the submission that is stored outside of the complexity of the submission structure itself , and is used to provide easy access details about individual submissions properties. Internal data can be used to facilitate data integrations or document routing using data collected from or about the submission.
...
Important system events are also stored in the database in audit tables. For example, signature collection, security modifications, etc. are logged in both a file-based audit log as well as in the database.
In addition to these error logs, nFORM also offers the ability to display a web-based error logging details utilizing a system known as ELMAH. ELMAH error details are displayed when viewing the application from the server via localhost on the production site and are always enabled on the test server. The archive of logs can be accessed by going to the root URL of the web application and adding the following to the URL address, “/Elmah.axd”.
Search Indexes
The system uses a text-based search indexing tool named Lucene to manage the Application Finder tool and provide the search capabilities to import submission data. The system also uses text files to collect system data in the form of application log files. Administrators should become familiar with these files as they may need to be cleaned when moving a system , or reviewed in the event of problems with the application.
...
Users of the system can be considered an Administrative user. These Administrative users have access to perform any task for any organization in the system. A user can also be assigned to other roles, but administrator status will override all other roles. Only existing Administrative users can promote another user to be an Administrator. To add a new Administrator, select the user you want to promote from the user list, and click the administrator checkbox to add the new user.
...
The system provides page level help to support the user experience and provides steps to perform most actions in the system. The help is composed of two sets of help information; : administrative help and public help. Administrative help is designed for the users with internal roles for administering information such as organization content, form content, or processing form submissions. Public help is designed for external users who use the system to submit and monitor their own form submissions. Within the system each web page is considered “Public”, or “Administration” based on the functions that the page performs, and the roles of the user logged in. Each help page can consist of several related topics. A hard copy of the help is available as the Public or Administrative Guides.
...
| Anchor | ||||
|---|---|---|---|---|
|
How do we migrate this system or recreate it on another server?
Please refer to the Implementation Steps section of this document for the steps for creating a new environment.
Where are the system files located?
The files can be found in the root directory of the application and can be located from within IIS by clicking on the application and selecting explore.
What is the minimum Window Server Roles and features needing to be installed for this system?
The default IIS User account can be used for the web portion of the application. Write access to [Root Directory]/App_Data is required; however, this is standard in ASP.NET environments. For more information on App_Data, see: http://msdn.microsoft.com/en-us/library/06t2w7da%28v=vs.80%29.aspx.
What are the key settings in the vars file?
Please refer to the "System Configuration" section of this document.
Where is the connection string?
This is stored in the file connectionstrings.xml file located in the [Root Directory]/conf/Web/ directory.
Are there other software applications that need to be installed to support this application?
No, the nFORM application is a standalone system which includes all necessary libraries and files.
If this application exchanges data with other systems, how can this be accomplished?
External interfaces include PayPal, Sharepoint and data export/import services. Additional communication occurs with the application database. The configuration is described in the System Configuration area is additional detail.
...
Data can also be imported and exported from other auxiliary systems. Please refer the Data Integration Document for further details on this process.
Does the system store data outside of the database, if so where and how?
Data Stored Outside of nFORM:
Integrated System:
3rd Party Payment Processor Information: Online payments may be facilitated via a 3rd Party Payment Processor (e.g., PayPal, Authorize.Net, etc.).
Document Management System Documents and Metadata: Submitted forms may be published to a 3rd Party Document Management system (e.g., Sharepoint).
Systems receiving nFORM data: Other agency system may receive data submitted on a form via custom integration process.
RoundHouse database configuration information: Database versioning information will be stored in RoundHouse to facilitate the deployment process.
Application/Server Log Files: Log files are generated and stored in APP_DATA/Logs. Full text search indexes are stored in several folders inside [Root Directory]/App_Data, but these indexes can be deleted, and the application will recreate the data on the next start.
Unstructured documents: If FileStreaming is enabled, unstructured documents will be stored on the Database Server file system.
Static Documents: Internal users may store documents in a static resource directory, for use as a reference on Forms. Please refer to Form Document Repository section for additional details.
All other data is stored into the system database.
How/where is table control spreadsheet template location – static file - managed?
The template location is defined as a hyperlink within the table control. Any valid URL can be linked to retrieve the template. To use the static file location please refer to Form Document Repository section of this document.
Where/how to change the email address for electronic signatory requests?
The email that receives any electronic signatory requests is defined with the "smtp.system.email" configuration key.
What changes require the application to be refreshed/restarted?
Any changes to the configuration or the database will require the application pool to be reset.
How can I add additional lookup lists or maintain existing lookup lists for use in the form lookup controls?
These values are maintained in the LOOKUP table using name value pairs in a JSON format. Note: any Any changes to this table will require the application pool to be refreshed to take effect.
...
Right click on the application pool and click the Advanced Settings option.
This will bring up the Advanced Settings dialog, scroll to the bottom to the section labeled “Recycling”. Locate the entry named Specific Times and click the “+” button to extend the Specific Times properties.
...
Click the More (“…”) icon next to the Specific Times value to open the Time-Span[] Collection Editor dialog.
...
Click the “Add” button, and then type in the specific time value (i.e., in military time format) representing when you want the application pool to recycle. For example, “21:00:00”.
Click the “OK” button to close the dialog.
Scroll up to the Process Model heading in the Advanced Settings dialog.
Set the setting Idle Time-out (minutes) value to “0”.
...
Close the settings dialog.
Close the Management Console.
1 Windsor is not responsible for a client’s configuration files once deployed. Modifications to configuration files by client staff may result in application instability.