Overview

In order to provide clients with payment vouchers to uniquely meet their needs, Windsor has implemented a feature that allows system users to:

1. Establish Payment Voucher Document Template(s), including:

   1. Assigning a standard Payment Voucher Document Template for use as the Payment Voucher for all Forms in the system, by default.

   2. Customizing the default Payment Voucher Document Template with a Form specific/customized template.

2. Access submission data for display within the document generated from the Payment Voucher Document Template.

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

Payment Vouchers are based on a Document Template and are made available to submitters after a submission is received by the agency and allow the submitter to remit a payment to the agency via paper process (e.g., sending a check in the mail).

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

The nFORM tool supports the ability to define documents that can be generated from the system. This includes Payment Vouchers for submitters to download in support of the payment remittance process.

A Payment Voucher can be designed for the system as a whole as well as for specific forms. The content in the Payment Voucher 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 payment voucher to online submitters.

This document provides some technical guidance on how to design the Payment Voucher template(s).

Please note that this is an advanced topic and is only to be utilized by advanced technical staff which knowledge of software coding practices.

Payment Voucher Design

Payment Voucher Formatting/Layout

Payment Vouchers 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 using the publishing and testing instructions in this document.

Referencing Submission Data

The Payment Voucher Document 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

**Disclaimer**

This is an advanced topic and is only to be utilized by advanced technical staff with knowledge of software coding practices.

Staff should know that if errors are encountered while running these documents, it is often due to issues with coding and data being presented not fitting into the assumed structure presented in this document. Most commonly, data referenced may not be present or may be returned in a different format than expected (e.g., text value returned in what was believed to be a numeric field). These situations must be handled/pre-empted to prevent errors during document generation. Professional services may be advisable/required from Windsor to assist in the creation of these documents.

Static Data Attributes

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

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

Submission Number Example

The following example returns a formatted Submission #.

Submission/Voucher Date Example

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

Payment Remittance Address Example

The following returns the Payment Remittance Address assigned to the Form.

Note: The Replace(“\n”,”<br/>”) reference replaces all newline characters with a line break. The “:upper” reference is used to make all text uppercase. The “format” –html reference used to ensure the displayed text honors the HTML formatting tags.

Amount Due Example

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

Dynamic Data Attributes

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

1. Define variables for the data to be accessed at the top of the template.

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.

See the Dynamic Submission Attribute References section of the Appendix for details on available attributes available for each control.

Please contact Windsor for assistance with any advanced data access needs.

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:

One defined, siteName can be referenced from anywhere in the form using the following syntax:

Note: The “:upper” reference is used to make all text uppercase.

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 “SITE_ADDR”. The code below performs the following tasks:

• Defines the siteAddressCtrl variable so 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:

Note: Each individual address component could be referenced separately (versus one address block, if desired.

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

Note: The “:upper” reference is used to make all text uppercase. The “format” –html reference used to ensure the displayed text honors the HTML formatting tags.

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 all 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:

Note: Each individual address component could be referenced separately (versus one address block, if desired.

One defined, the submitterInfo can be referenced, in uppercase, from anywhere in the form using the following syntax:

Note: The “:upper” reference is used to make all text uppercase. The “format” –html reference used to ensure the displayed text honors the HTML formatting tags.

Other Considerations

Below are some additional considerations when presenting dynamic data attributes:

• When defining the variables for the data to be accessed at the top of the template:

  • 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.

• Any Controls referenced in the Template must exist on Submission Form. If the control doesn’t exist, errors will be encountered and the Payment Voucher will not be generated, unless error handling code is added. To trap for potentially absent controls, the following format of code can be used.

• If a Control is empty (e.g., not entered), the value will be returned as a blank to the Payment Voucher. It’s worth noting that 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:

Testing

It is recommended that the Payment Voucher Template be tested in a test environment, prior to publishing.

Payment Voucher

If a test environment is not available, another means for testing the Payment Voucher Template is to add the draft Payment Voucher Template to an unpublished form as a non-default Payment Voucher Template and Preview that form.

Once a draft Template is assigned to the system/form, the user can navigate to the Confirmation and Payments step the Submission Wizard for a form with Offline payment option enabled and fees due. From this form, click on the “Pay by Mail” button and click on the “Download Payment Voucher” button.

Once submitted, you can also force the download of the payment voucher by assembling a URL to generate and download the Payment Voucher document directly. To do this assemble the URL in the following format:

[root application URL]/paymentvoucher/[SubmissionVersionID]

For example, in Windsor’s QA environment, for a specific submission, the URL would look like the following:

If issues are encountered and the Payment Voucher returns a runtime error, further details about the nature of the error can be found in the application logs which can be found here, [root web application folder]\App_Data\logs where root web application folder is equal to the location of the web application.

Publishing

Payment Voucher

To publish an established template, perform the following:

• If the template will be considered the default template:

  • Save the template

  • Name the template PaymentVoucher.docx

  • Copy/Move the template to your agencies Override folder, [root web application folder]\DocumentTemplates\Word where root web application folder is equal to the location of the web application.
    Note: any changes made to the Template should be backed up and provided to Windsor to ensure the master template is included in the client build, to ensure it is not overwritten with an old version during the next deployment process.

  • At this point, the template will be utilized during the next Payment Voucher, for Forms using the default template.

• If the template is form specific:

  • Save the template

  • Open the Form for which this Payment Voucher will be used, in design mode.

  • On the Fees tab, uncheck the “Use Default Payment Voucher” checkbox, upload this template to the Form.

  • At this point, the template will be utilized during the next Payment Voucher for this specific form.

Please note that the base Template that is shared throughout the system must be named PaymentVoucher.docx.

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.

Note: 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

Reference Variable Example

Advanced

Name

Establish Variable Example

Reference Variable Example

Location

Establish Variable Example

Reference Variable Example

Address

Establish Variable Example

Reference Variable Example

Attachment

Establish Variable Example

Reference Variable Example

Table

Establish Variable Example

Reference Variable Example

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 is desired, consulting services will be required to perform advanced configuration of the document template.

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.