The FormDefinition defines the FormFields and FormTables that can be found on a typical invoice document. It also defines what fields and table columns will be output to the final form result.
 
The FormDefinition class comprises three members:

• FieldDefinitions
  Field definitions are used to define fields found in a document, both single value fields and table columns headers. The definition includes the Name of the Field/Header, alias values of the Field/Header, and metadata about the Field/Header.

• TableDefintions
  Table definitions are used to define tables found in a document. It defines a name for the table and a list of FormTableColumnHeaderDefinitions. The FormTableColumnHeaderDefinition's name must start with "LIT " and have a corresponding FormDefinition.FieldDefinitions item. The aliases in the FormDefinition are used when locating table columns.
  
  The following headers are expected by FormSuite for Invoices:
  • "LIT Description" - A description of the item in the Line Item Table.
  • "LIT Amount"  - The amount billed for the item in the Line Item Table.
  • "LIT Quantity"  - The quantity of an item in the Line Item Table.
  • "LIT Price"  - The price of an item in the Line Item Table.
  Currently, only the first table encountered in a document is used for processing.

• RuleDefinitions
  Rule definitions are defined rules applied at the document level. Document level rules are not currently used and should be empty.

Default FormDefinition

FormSuite for Invoices ships with a default FormDefinition. This default contains many common field and table definitions.

Default output fields:

• "Invoice Number"
• "Invoice Date"
• "Due Date"
• "Purchase Order Number"
• "Total Due"

Default output table columns:

• "LIT Description"
• "LIT Amount"
• "LIT Quantity"
• "LIT Price"

Creating a Custom FormDefinition

You can create a custom FormDefinition in one of the following ways:

• Edit the default definition
• Programmatically

Creating a Custom FormDefinition By Editing the Default Definition

The simplest way to create a custom FormDefinition is to edit the provided default form definition.

To edit the provided default form definition:

1. Get the default form definition
2. Serialize it to an XML file
3. Make changes to the definition in an editor
4. Deserialize the modified form definition

1. Get the Default Form Definition

FormDefinition formDefinition = FormDefinition.CreateDefaultDefinition();

2. Serialize the Default Form Definition to an XML File

DataContractSerializer serializer = new DataContractSerializer(typeof(FormDefinition));
 
 using (FileStream fileStream = new FileStream("MyFormDefinition.xml", FileMode.Create, FileAccess.Write))
 {
   using (XmlWriter xmlWriter = XmlWriter.Create(fileStream, new XmlWriterSettings() { Indent = true }))
   {
     serializer.WriteObject(xmlWriter, formDefinition);
     xmlWriter.Flush();
   }
 }

3. Modify the XML File

The previous step created an XML file with the current default form definition. It may now be modified in a text editor to meet your applications needs.

For example, let’s look at adding in a new "LIT Transaction Date" column to the existing Line Item Table:

• First, add a new FieldDefinition entry for the "LIT Transaction Date" to the FormFieldDefinition Element in the XML file.
  

  Field definition for  "LIT Transaction Date"

  Copy Code

  <FormDefinition> ... <FieldDefinitions> ... <KeyValuePair> <Key>LIT Transaction Date</Key> <Value> <Aliases> <FieldAlias> <Alias>transaction date</Alias> <Alias>sale date</Alias> </FieldAlias> </Aliases> <Group>ItemsFormFieldGroup</Group> <IsOutput>false</IsOutput> <IsRequired>false</IsRequired> <Name>LIT Transaction Date</Name> <RuleDefinitions/> <Type>Date</Type> </Value> </KeyValuePair> ... </FieldDefinitions> ... </FormDefinition>

• Then, add a new column to the table for a transaction date. This is added to the XML element TableDefinitions/KeyValuePair/Value/FormTableColumnDefinitions.
  

  Column definition for "LIT Transaction Date"	Copy Code
  <FormDefinition> ... <TableDefinitions> ... <KeyValuePair> ... <Value> ... <FormTableColumnHeaderDefinition> <DataType>Date</DataType> <Name>LIT Transaction Date</Name> </FormTableColumnHeaderDefinition> ... </Value> ... <KeyValuePair> ... <TableDefinitions> ... <FormDefinition>

• Finally, save this file to disk so it can be used for processing. Notice that the Name element for the field and column are the same and are prefixed with "LIT ". Any default or custom table column must have this prefix to be recognized by Form Suite for Invoices SDK.

4. Deserializing and Using the Updated FormDefinition

DataContractSerializer serializer = new DataContractSerializer(typeof(FormDefinition));
FormDefinition formDefinition;
 
using (FileStream fileStream = new FileStream("MyFormDefinition.xml", FileMode.Open, FileAccess.Read))
{
   using (XmlReader xmlReader = XmlReader.Create(fileStream))
   {
      formDefinition = (FormDefinition)serializer.ReadObject(xmlReader);
   }
}

Creating a FormDefinition Programmatically

A FormDefinition can be created programmatically, with the following steps:

1. Create an empty FormDefinition
2. Create a FormFieldDefinition
3. Create a FormTableColumnHeaderDefinition

1. Create an Empty FormDefinition

An empty FormDefinition can be created and populated programmatically. But, as stated above, FormSuite for Invoices does make some assumptions about how columns are defined. Specifically, column names start with the prefix "LIT ".

2. Create a FormFieldDefinition

A FormFieldDefinition can be created programmatically and added to a FormDefinition. 

// Create a field definition
 FormFieldDefinition fieldDefinition = new FormFieldDefinition();
 fieldDefinition.Group = FormFieldGroup.SummaryFormFieldGroup;
 fieldDefinition.IsOutput = true;
 fieldDefinition.IsRequired = true;
 fieldDefinition.Name = "My Field";
 fieldDefinition.RuleDefinitions = new List<RuleDefinition>();
 fieldDefinition.RuleDefinitions.Add(new RuleDefinition(RuleType.InsideTopRightZoneRule, 10, ""));
 fieldDefinition.Type = FormFieldDataType.Currency;
 fieldDefinition.Aliases.Add(new FieldAlias("My Field"));
 fieldDefinition.Aliases.Add(new FieldAlias("Other Field"));
 
 // Add the field definition to the form definition
 formDefinition.FieldDefinitions.Add(fieldDefinition.Name, fieldDefinition);

3. Create a FormTableColumnHeaderDefinition

Below shows adding a FormTableColumnHeaderDefinition to the form definition. Note that a FieldDefinition is created for each column definition. Also note that the name of the column and field must be the same and must start with the prefix "LIT "

 // Create a field definition for LIT Description
 FormFieldDefinition litDescriptionDefinition = new FormFieldDefinition();
 litDescriptionDefinition.Group = FormFieldGroup.ItemsFormFieldGroup;
 litDescriptionDefinition.IsOutput = false;
 litDescriptionDefinition.IsRequired = false;
 litDescriptionDefinition.Name = "LIT Description";
 litDescriptionDefinition.RuleDefinitions = new List<RuleDefinition>();
 litDescriptionDefinition.RuleDefinitions.Add(new RuleDefinition(RuleType.InsideTopRightZoneRule, 10, ""));
 litDescriptionDefinition.Type = FormFieldDataType.GeneralText;
 litDescriptionDefinition.Aliases.Add(new FieldAlias("Description"));
 litDescriptionDefinition.Aliases.Add(new FieldAlias("Desc"));
 // Add the field definition to the form definition
 formDefinition.FieldDefinitions.Add(litDescriptionDefinition.Name, litDescriptionDefinition);

 // Create a field definition for LIT Amount
 FormFieldDefinition litAmountDefinition = new FormFieldDefinition();
 litAmountDefinition.Group = FormFieldGroup.SummaryFormFieldGroup;
 litAmountDefinition.IsOutput = false;
 litAmountDefinition.IsRequired = false;
 litAmountDefinition.Name = "LIT Amount";
 litAmountDefinition.RuleDefinitions = new List<RuleDefinition>();
 litAmountDefinition.RuleDefinitions.Add(new RuleDefinition(RuleType.InsideTopRightZoneRule, 10, ""));
 litAmountDefinition.Type = FormFieldDataType.Currency;
 litAmountDefinition.Aliases.Add(new FieldAlias("Amount"));
 litAmountDefinition.Aliases.Add(new FieldAlias("Amt"));

 // Add the field definition to the form definition
 formDefinition.FieldDefinitions.Add(litAmountDefinition.Name, litAmountDefinition);

 // Create a table definition
 FormTableDefinition tableDefinition = new FormTableDefinition();
 tableDefinition.Name = "Line Item Table";

 // Setup the columns of the table
 FormTableColumnHeaderDefinition descriptionColumn = new FormTableColumnHeaderDefinition();
 descriptionColumn.DataType = FormFieldDataType.GeneralText;
 descriptionColumn.Name = "LIT Description";
 tableDefinition.ColumnHeaderDefinitions.Add(descriptionColumn);

 FormTableColumnHeaderDefinition amountColumn = new FormTableColumnHeaderDefinition();
 amountColumn.DataType = FormFieldDataType.Currency;
 amountColumn.Name = "LIT Amount";
 tableDefinition.ColumnHeaderDefinitions.Add(amountColumn);

 // Add the table definition to the form definition
 formDefinition.TableDefinitions.Add(tableDefinition.Name, tableDefinition);