Overview

In order to provide the ability to generate highly formatted documents, Windsor has implemented a feature that allows Form Designers to:

1. Design custom template(s) in Microsoft (MS) Word

2. Assign a template to a workflow task in the system

3. Access submission data for inclusion within the template

Templates are formatted/designed in MS Word, using Aspose.Words for .NET and the LINQ coding syntax to access Submission data.

These templates are utilized, and a document is produced when called as an action associated with a workflow step, initiated by a submission processor.

If desired, Windsor can configure an example “InstaPermit” form in your environment that can be used as a configuration reference for this document generation feature.

Document generation supports a highly configurable, dynamic, feature set and as such, requires advanced skills and detailed testing/verification. Customers who elect to define advanced configurations in document templates should consult with Windsor to ensure appropriate conventions and techniques are utilized to ensure a successful implementation.

Introduction

nFORM supports the ability to define a Document Template (template) for staff to generate in support of form processing. A template can be designed for the system as a whole as well as for specific forms. The content in the template can be static or dynamically driven based on data provided in the submission. This capability allows agencies and form designers to provide a highly formatted document generation capability to its staff.

This functionality is sometimes referred to as InstaPermit, because a primary usage of this capability is to generate a permit after an application has been approved. However, this feature can be used for other official documents such as certificates, licenses, ID cards, etc. This document provides technical guidance on how to design and implement a document generation template.

Template Design

Document Formatting/Layout

Documents are formatted and designed using MS Word (version 2007 or higher). The MS Word document can be highly formatted and include advanced features such as headers, footers, paging, tables, etc.

Be sure to test out the layout and functionality of the template against a draft or copy of your intended production form to ensure document creation is occurring as expected.

You are in charge of the naming convention but include no blank spaces or special characters and make sure the file is a docx.

Anatomy of a Template

The anatomy of a template is very straightforward and simply contains standard or dynamic data attributes, along with static text.

You are in charge of where and how to utilize these template elements. The remainder of this document helps educate on how best to establish a template.

Building your template

Add Static Text First

The best approach to building your template is to design the template utilizing Static Text. You may use all elements of regular document creation including tables, section breaks, headers and footers etc.

Identify Submission Data

Identify the positions in your template where you wish to populate with data from a submission. Label them clearly, so that you make sure you address them all during attribute definition. If it is easier for you to complete this at the same time as you add the static text, then please do so. The recommended syntax for identifying submission data is as follows *the data you want*. The reason for this is that * and * do not conflict with the true beginning and ending tags and help you to make sure all elements have been addressed. Getting your layout established before you start adding attribute definitions will help you get an outcome that looks as expected.

Add Attribute Definition

For each of your identified data elements to be populated from the submission, you must define them to match the syntax expected by the nFORM document generator.

See details on Referencing Submission Data for including Standard Data Attributes and Dynamic Data Attributes below.

Assign Template to Form

Follow the guidelines provided below to associate your template to your form. You will complete this in the form designer. You will have to associate the template to the form and then establish a workflow task that performs an action of generating a document using the established template.

Test, test, test

As mentioned earlier, please be sure to test out the layout and functionality of the template against a draft or copy of your intended production form to ensure document creation is occurring as expected. You can test the document creation via the preview option within the form designer, without having to publish your form – this reduces the number of old versions of your form and is cleaner, so test before you publish.

Referencing Submission Data

The template has the ability to access data from the submission for reference on the form. In order to access this data, the system uses Aspose.Words and an Aspose-specific variation of the LINQ coding syntax. Here are some helpful resources on the template syntax:

• https://docs.aspose.com/display/wordsnet/Template+Syntax

• https://docs.aspose.com/display/wordsnet/Typical+Templates

Standard Data Attributes

When accessing standard submission data (e.g., Submission Date, Parent Organization, Submission Number, etc.), the Submission attributes can be accessed directly.

See the available static references available in the Appendix under the topic, Standard Submission Attribute References.

Basic insertion of a standard data attribute

The following example returns a formatted Submission # and is an example of the syntax for a basic standard data attribute.

Formatting a date

The following example returns the date of the submission, formatted as a date as specified.

You can manipulate the format using the following format codes.

Some examples

Amount Due Example

The following example returns the amount currently due, formatted as a currency.

Dynamic Data Attributes

When accessing dynamic data in the submission (e.g., custom data points defined in form sections by a form designer), there are a few steps that should be followed, such as:

1. Define variables at the top of the template for the data to be accessed. These are an important aspect for dynamic data as a pre-check for data existence helps prevent a template failure during document generation.

2. Perform any needed concatenation and appropriate error handling at the top of the template.

3. Reference the data point using the defined variable within the core of the template.

Following these steps will allow the template to minimize code within the core of the template and help preserve the integrity of the template.

Speaking to bullets #1 and #2 above, the designer should define the variables to be referenced and perform any needed concatenation and error handling at the top of the document. Here are some examples of how to perform this task.

Creating a Variable

Variables allow us to avoid having null values that could crash the template. Here is some guidance on how to create a variable in different circumstances.

1. Declare that we are defining a variable - var

2. Give the variable a name - [NameOfVariable

3. Identify what control to map the variable to by pointing to the control tag - =SectionControls.FirstOrDefault(sc=>sc.tag ==”SITE_NAME”)

4. Specify which attribute within the control you are populating the variable with -.values.controlValue]

5. Close the Variable

6. Your variable declaration should look something like the following - var [siteName = SectionControls.FirstOrDefault(sc=>sc.tag ==”SITE_NAME”).values.controlValue]

Here are some examples:

Short Text/Paragraph Example

In this example, the template is attempting to access text from a Short Text or Paragraph Control, the “Site Name”, that the user entered in the submission. The Short Text or Paragraph (e.g., Site Name) Control in the submission has a Tag value of “SITE_NAME”. The first step is to define the siteName variable. Assuming Site Name control will always be available on the Submissions, use the following syntax to define the siteName control:

Once defined, siteName can be referenced from anywhere in the template using the following syntax:

Address Example

In this example, the template is attempting to access text from an Address Control, the “Site Address”, that the user entered in the submission. The “Address” (e.g., “Site Address”) Control in the submission has a Tag value of “ADDRS”. The code below performs the following tasks:

• Defines the siteAddressCtrl variable to simplify the many references to this control.

• Performs error handling to handle the situation where the site address is null.

• The siteAddress variable is established by concatenating all the constituent parts of the address control (e.g., street address, secondary address, city, state, zip, etc.) and to improve formatting. HTML break tags are added where needed.

See example below:

Syntax "\r" provides a return; so does "\r\n".  The use of "\r\t", results in a return carriage and a tab. Practice to determine a result that meets your needs.

One defined, the siteAddress can be referenced from anywhere in the template using the following syntax:

Contact Control Example

In this example, the template is attempting to access a Contact Control, the “Submitter” information that the user entered in the submission. The Contact (e.g., Submitter) Control in the submission has a Tag value of “CNTCT”. The code below performs the following tasks:

• Defines the submitterCtrl variable so simplify the many references to this control.

• Performs error handling to handle the situation where the company name is null.

• The submitterInfo variable is established by concatenating some of the constituent parts of the submitter control (e.g., name, street address, secondary address, city, state, zip, etc.) and to improve formatting, HTML break tags are added where needed.

See example below:

Once defined, the submitterInfo can be referenced, in uppercase, from anywhere in the template using the following syntax:

Other Considerations

Below are some additional considerations when presenting dynamic data attributes:

• When defining the variables for the data to be accessed:

  • Perform this work at the top of the page (prior to the data attribute being referenced).

  • Do NOT add carriage returns in or between these definitions as the template will include these carriage returns in the presented document.

• If a referenced control in the template does not contain data within the submission, we must trap that to avoid a template failure. To trap for potentially absent data in a control, the following format of code can be used.

• If a Control is empty (e.g., not entered), the value returned to the template will be a blank. In some cases, blank values are saved in controls as a “?” to help with URL encoding. In these cases, the “?” will need to be replaced with a blank value during display.

• Case does matter when referencing variables so be sure that your casing is in sync.

• Configuration values (in the Vars.config, VarsOverrides.config, etc.) can be exposed to the document generator. These can be exposed by referencing the existing configuration properties in the following format:

Internal values can be exposed to the document generator. They can be exposed by referencing the existing internal data element in the following format:

Template Assignment to Workflow

In order for a document to be generated using a designed template, it must be attached to a workflow step as an action. To do this the form designer must first associate the template with the form via the form designer Document Templates tab.

Open

Add the document template and provide a display name.

Open

You will then see the document template attached to the form and it is now available for use in your workflow.

In the workflow step, define an action against the step that is responsible for generating the document as follows.

Specify the action of Generate Document and select the trigger, for example, ‘Step Completed’.

Then pick the Document Template. There will likely just be one, but the application supports many, so pick the one you wish to generate.

Specify whether or not this document will be shared with the submitter. Activating this setting will make the generated document visible to the submitter if they open the record in their account.

Note: The documents are not currently emailed to the submitter, although this option is being considered for inclusion in an upcoming release.

Include any additional text to include in the email notification.

Appendix

Standard Submission Attribute References

Below is a list of key standard submission attributes that are available for reference in the template.

Note: More properties may be available. Please see the nFORM Control Attributes Reference Guide for guidance if an attribute needed is not referenced.

You may use any of these standard data elements in your template, just copy and paste to the location you want, even in the header and footer.

FORM DATA

• Form Header:

  • Form Name:

    • Form Name: <<[formVersion.name]>>

    • Form Short Description: <<[formVersion.title]>>

    • Reference Number: <<[formVersion.referenceNumber]>> (this will only be populated after a processor has provided this number, post submission)

  • Alternative Identifier:

    • Label: <<[formVersion.altIdentityLabel]>> (only the label is from the form version)

  • Reason for Submission: <<[formVersion.formType]>> (this will only be populated when the Reason for Submission attribute is enabled on the form design)

  • Online Payments Accepted: <<[formVersion.isOnlinePaymentAvailable]>>

  • Form Version:

    • Full Version Number: <<[formVersion.version]>>

    • Major Version Number: <<[formVersion.versionNumber]>>

    • Minor Version Number: <<[formVersion.minorVersion]>>

• Fees:

  • Account Number: <<[formVersion.accountNumber]>> (must be populated on form design)

  • Flat Fees (static fee list): <<foreach [item in formVersion.fees]>><<[item.description]>>: $<<[item.amount] >><</foreach>>

  • Calculated Fee (will not have values if fee is not calculated)

    • Fee Description: <<[formVersion.fees[0].description]>>

    • Is Payment Calculated: <<[formVersion.paymentIsCalculated]>>

    • Minimum Threshold: <<[formVersion.fees[0].MinimumFee]>>

    • Maximum Threshold: <<[formVersion.fees[0].MaximumFee]>>

  • Fee Amount: <<[formVersion.processingFee]>> (not really relevant for FORM VERSION)

• Addresses: <<foreach [item in formVersion.addresses]>><<[ item.addressTypeName]>>:<<[ item.fullAddress] >><</foreach>>

SUBMISSION DATA

• Submission Header:

  • Submission Number: <<[submission.formattedNumber]>>

  • Revision Number: <<[submission.LastSubmittedSubmissionVersion]>> (not yet available)

  • Submission Locked Indicator: <<[submission.isLocked]>>

  • Is Test/Preview Submission: <<[submission.isTest]>>

  • Submitted Date: <<[submissionVersionSubmitted]>>

  • Submitted By: <<[SubmissionVersionSubmittedBy]>>

  • Responsible person information:

<<[responsiblePerson.LastName]>>

• Fees:

  • Account Number: (entered by Form Designer)

  • Payment Remittance Address: (Not yet available)

  • Fee Description: <<[submission.fee.description]>>

  • Calculated Fee:

    • Is Payment Calculated: <<[formVersion.paymentIsCalculated]>>

    • Minimum Threshold: <<[submission.fee.min]>>

    • Maximum Threshold: <<[submission.fee.max]>>

  • Fee:

    • Amount: <<[submission.processingFee]>>

    • Formula: <<[submission.fee.formula]>>

  • Payments/Adjustments:

    • Manual Payments/Adjustments: <<[submission.adjustments]>>

    • Online Payments: <<[submission.onlinePaymentsTotal]>>

    • Total Payments/Adjustments: <<[submission.paymentsTotal]>>

  • Payment Status:

    • Payment Status: <<[submission.financialStatus.name]>>

    • Are more Payments Required: <<[submission.hasMorePaymentsRequired]>>

ORGANIZATION DATA

• Organization Header:

  • Top-Level System Organization Name: <<[systemOrganizationName]>>

  • Organization Name: <<[organization.name]>>

  • Organization Code: <<[organization.organizationCode]>>

USER DATA

• User Information:

  • Name:

    • Full Name: <<[loggedInUser.displayName]>>

    • Username: <<[loggedInUser.login]>>

    • Email: <<[loggedInUser.primaryEmail]>>

  • Company: <<[loggedInUser.company]>>

    • Address: <<[loggedInUser.addresses.FirstOrDefault(a => a.addressType.Name =="home")]>> This is not yet available.

Dynamic Submission Attribute References

Submission attributes that are custom to a form or dynamically generated can also be referenced on a template. Control values can be referenced in a format such as below; here Tag Value is the Tag assigned to the control, and Control Type is the control type of the attribute being accessed. Please see the Control Value Properties Appendix within the nFORM Integration Guide for available Control Types that can be referenced for a Control. More properties may be available. Please see the nFORM Control Attributes Reference Guide for guidance if an attribute needed is not referenced.

The following describe how you would normally reference each control. Your Variable name is set to what you want to name the variable, the tag should be set to the tag within the control you wish to access.

Simple

Short Text

Establish Variable Example

Reference Variable Example

Paragraph

Establish Variable Example

Reference Variable Example

Instructions

No attributes are returned from this control.

Single Selection

Establish Variable Example

Reference Variable Example

Multi Selection

Establish Variable Example

Reference Variable Example

Formatted

Number

Establish Variable Example

Reference Variable Example

Date

Establish Variable Example

Email

Establish Variable Example

Reference Variable Example

URL

Establish Variable Example

Reference Variable Example

Phone

Establish Variable Example

Reformatting the input phone number:

Reference Variable Example

Advanced

Name

Establish Variable Example

Reference Variable Example

Location

Establish Variable Example

Reference Variable Example

Address

Reference Variable Example

Attachment

Establish Variable Example

Reference Variable Example

Table

Establish Variable Example

Advanced Table Example

DataGrid Summary Data

Contact

Establish Variable Example

Reference Variable Example

Hidden Text

Establish Variable Example

Reference Variable Example

Calculated

Establish Variable Example

Reference Variable Example

Repeaters

If references to data found within a form repeater are desired, consulting services will be required to perform advanced configuration of the document template. However, an example below could provide insight into the proper syntax depending on experience level:

Markup

If you are uploading a document that is in review, be sure and turn off track changes before you save it to upload. Markup will be considered part of the document and will impact rendering.