Overview

In order to provide clients with hard copy signature form to uniquely meet their needs, Windsor has implemented a feature that allows system users to:

1. Establish Hard Copy Signature Document Template(s), including:

   1. Assigning a standard Hard Copy Signature Document Template for use as the hard copy signature form for all Forms in the system, by default.

   2. Customizing the default Hard Copy Signature Document Template with a Form specific/customized template.

2. Access submission data for display within the document generated from the Hard Copy Signature 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.

Hard Copy Signature Forms are based on a Document Template and are made available to submitters during the signature process (i.e., when enabled) to remit signature(s) to the agency via paper process (e.g., providing a wet ink signature and sending the form back to the agency).

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 a hard copy (i.e., physical) signature form submitters can download in support of the submission certification and signature process.

A hard copy signature form can be designed for the system as a whole as well as for specific forms. The content in the hard copy signature form 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 hard copy signature form to online submitters.

This document provides some technical guidance on how to design the hard copy signature form 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.

Hard Copy Signature Form Design

Hard Copy Signature Form Formatting/Layout

Hard Copy Signature Forms 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 Hard Copy Signature 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 which 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 #.

Form Name

The following returns the form name for the Form.

Site Address Example

The following returns the Site 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.

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

Any attributes referenced here can be accessed from within the document by referencing the configuration value without periods and capitalizing secondary words. So, the app.Title configuration setting will be referencing as:

The esa.recipient.mailing.address configuration setting will be referencing as:

Testing

It is recommended that the Electronic Signature Form Template be tested in a test environment, prior to publishing.

Hard Copy Signature Form

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

Once a draft Template is assigned to the system/form, the user can navigate to the Certification and Submission/Signing step of the Submission Wizard for a form and select the Hard Copy Signature option. From this form, click on the “Download Certification Form” button.

You can also force the download of the Hard Copy Signature Form by assembling a URL to generate and download the Hard Copy Signature document directly. To do this assemble the URL in the following format:

[root application URL]/DocumentGeneration/[SubmissionVersionID]?
template=HardcopySignatureTemplate&fileName=HardCopySignature.pdf

The template value references the name of the template to be utilized/tested (sans the .DOCX file type reference). The filename specifies the name that will be assigned to the generated document.

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

http://qaweb.windsor.com/nForm/DocumentGeneration/b96013ff-de07-4417-8f6c-0784e631778?http://qaweb.windsor.com/nForm/DocumentGeneration/b96013ff-de07-4417-8f6c-0784e631778?template=HardCopySignatureTemplate&fileName=HardCopySignature.pdf

If issues are encountered and the Hard Copy Signature Form 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

Hard Copy Signature Form

To publish an established template, perform the following:

• If the template will be considered the default template:

  • Save the template with the name HardCopySignatureTemplate.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 submission, for Forms using the default template.

• If the template is form specific:

  • Save the template.

  • Open the Form for which this Hard Copy Signature Form will be used, in design mode.

  • On the Certification tab, uncheck the “Use Default Signature Form Template?” checkbox, upload this template to the Form.

  • At this point, the template will be utilized during the next hard copy signature request for this specific form.

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

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]>>

<<[responsiblePerson.FirstName]>>

<<[responsiblePerson.DisplayName]>>

<<[responsiblePerson.PrimaryEmail]>>

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