Data Fields

Locating the Data Fields feature

Anyone in a Role with the View Data Fields privilege can view the program’s Data Fields by opening the PROGRAM DESIGN menu and clicking on Data Fields:

 

 
 

Viewing Available Data Fields

The Data Fields feature allows you to retrieve a list of all your program’s available Data Fields. Use the search bar at the top right to search Data Fields names and narrow down the list. PowerClerk also has a subset of Data Fields called are Built-In Fields and are always available across programs:
 

 
The Data Fields list can be filtered further with additional toggles at the top of the page. These filters also apply when exporting data fields to CSV. Exporting is done by clicking the Export to CSV button located at the top right.

 

 
Please Note: Users are unable to create Data Fields on the Data Fields page. To learn how to create PowerClerk Data Fields, please visit the Forms support center article.
 
 

Managing Data Fields

Once Data Fields have been created, their names can be changed using the Rename button available when the Data Field is expanded by clicking on the arrow to the left of the Data Field name. The View References button displays which program elements reference the Data Field beyond the available columns.

 

 
 

Attachment Data Fields

Attachment Data Fields can be further customized from the Data Fields menu by expanding the Data Field and clicking “Edit”.

 

 
The Attachment Data Field edit option allows specification of permitted file extensions for the respective attachment. Within this pop up, it is also possible to indicate whether Allow Large Files should be enabled. To permit files larger than the default 5MB limit, contact PowerClerk’s Support Team. Once enabled for the program, this toggle accommodates attachments exceeding the 5 MB default and should be used only when unusually large files are expected.
 
The Allow Document Merge option allows this Attachment to be used in a Merged Document Template. For additional information, please visit the Document Templates Support article linked here.
 
The Is Sensitive option allows an Attachment to be marked as sensitive when collecting sensitive documents such as W-9 forms or other personally identifiable information (PII) that requires protection. Warning: Setting an attachment slot as sensitive is irreversible and cannot be unchecked once set.
 
 

Referencing Data Fields with Template Tags

Template Tags will be used to reference the data field and populate it in features like Communication Templates. Template Tag naming is set when a Data Field is created and can be changed by renaming the Data Field. Renaming the data field, and therefore the template tag, will automatically update in Communications and Document Templates containing the renamed template tag.

 

 
When referencing string data field template tags in Communications or Document templates, a default value can be specified to display when the data field is blank. To do this, append a comma followed by the desired default value within the tag.
 
The format for using a string data field with a default value is as follows:

• {data: <data field name>, <default value to display if the data field is empty>}

 
Numeric data field output can also be customized by using the following format:

• Format: {data: <data field name>, <decimal point structure>, <number of decimal places>}
• Example: {data: <data field name>, 0.00, 2} will display a value such as 109,900.00.

Text Validation Rules

Text Validation Rules can be created to define custom validation rules and apply them to individual text data fields, including single line and multi-line text fields. This ensures the input matches the configured rules for text data fields when updated via Form entry and Automation Action rule. For example, a numeric data field can be configured to only accept values that have a maximum of nine numeric digits.
 
There are two types of Text Validation Rules:

1. Character Set: Each character in the text input must belong to an allowed character set. This can include configuring a variation of character sets (uppercase letters, lowercase letters, numeric digits, or punctuation characters) and enforcing a character limit.
2. Pattern Match: The text input must match the defined pattern.

How to Create Text Validation Rules

To create a Text Validation Rule, go to Program Design >> Data Fields. On the top of the Data Fields bar, select the tab Text Validation Rules.
 
Create a new rule by selecting the button New Text Validation Rule.
 

 

Validation Rule Type: Validate with Character Sets
Rules that validate with character sets are configured to allow one or multiple character sets. This type of rule can be applied to Single Line Text Fields and Paragraph Text Fields. Currently, the character sets that PowerClerk supports are:

• Uppercase letters: A to Z
• Lowercase letters: a to z
• Numeric digits: 0-9
• Punctuation Characters: !’#$%&*+,-.;=?@^_~:

Additionally, these rules can be configured to limit the length of text by enabling Enforce character limit. PowerClerk will then allow a Maximum input length to be set.
 
The figure below demonstrates an example of a Text Validation Rule that will accept all character sets with a maximum input length of nine.
 

 

Validation Rule Type: Validate with Text Pattern Matchings
Rules that validate with text pattern matching allow one or more defined patterns. This type of rule can only be applied to Single Line Text Fields.
 
Pattern rules can be configured to accept either a single pattern, or multiple patterns by clicking the Add Pattern button.
 

 

The Pattern Character column defines the character used to match any value of that character type. The Escape Sequence value is used to match the pattern character itself. For example, consider the following patterns:
 

Pattern: \####

• This pattern will only accept inputs that start with the # character and are followed by three digits of any value. A valid input for this pattern could be: #123.

Pattern: 0011AAA

• This pattern will only accept inputs that start with the exact digits 0011 and are followed by three upper case characters. A valid input for this pattern could be: 0011ABC or 0011XYZ.

Pattern: \AAAA

• This pattern will only accept inputs that start with the upper-case letter A and are followed by any 3 upper case letters. A valid input for this pattern could be: AZXY.

Pattern: (###) ###-####

• This pattern would match the standard American telephone number format. A valid input for this pattern could be: (123) 456-7890.

Pattern: ********-****-****-****-************

• This pattern would match a 128-bit Universally Unique Identifier (UUID). A valid input for this pattern could be: 6b9e7175-2699-433a-a295-8b9ccc637e4b

Validation Rule: Error Message and Test Tool
Once the Validation Rule Type has been configured, users are able to add a custom Validation Error Message. This will be the red error message that appears if the input is not valid. If not configured, the default validation error message is used: “Input does not match the expected format”.
 
Additionally, the Validation Rule can be tested in this module by using the Rule definition test tool. This tool allows users to test the Text Validation Rule they created to ensure that it is correctly configured to accept the intended input.
 

 
Once you have created a Validation Rule you will be able to edit the rule by clicking on the created rule and selecting the button Edit. Adding or updating a Validation Rule will not affect existing data unless it is re-inserted to a data field using the new rule.
 
Configuring Validation Rules to Text Data Fields
Once the Text Validation Rule has been saved, they can be added to a Data Field by selecting the Data Fields tab on the Data Fields page. Then select a string data field type and press Modify Text Validation Rule.
 
A module will appear to select and apply a Text Validation Rule to a data field. To save the configuration press OK.

 

 

Once the Text Validation Rule has been applied to a data field, on the edit Form page, help text will appear to confirm the data field has had a rule applied.

 

 

Custom Lists and Data Field Groups

PowerClerk’s Data Fields functionality allows you to define Custom Lists under the Custom Lists-tab. If you do not see this tab present, please submit a ticket on the PowerClerk Ticket System to request this feature to be enabled for your PowerClerk program. A Custom List can be any kind of hierarchical list of data that you would like your applicants to be able to select pre-defined data from.
 
To initialize a Custom List, you will need to create a .csv file with the columns you desire as your hierarchical fields in the Custom List. A sample file can be seen in the figure below:

 

 
Once the CSV template is created, navigate to the Custom Lists tab to find the Add Custom List button to upload your template CSV file as the Custom List data source:
 

 
Custom Lists can be setup to retain the ordering for the primary key value column as denoted in the original CSV file by clicking the following option Use Data Source Ordering in the setup dialog:
 

 
In the subsequent dialog you will be able to configure your data source columns to make them Key Columns (selectable within your Forms), or to exclude certain columns, or to define the data type of your output column to either be string, integer, decimal, or email, or to rename the display of the column name:
 

 
Note: When a Custom List is imported from a .csv file containing a column solely made up of email addresses, PowerClerk will automatically identify the column as containing emails and set the corresponding Custom List output column data type to “email”.
 
This enforces the email format as xxx@yyyy.zzz and enables further processing of the output field within Communication Templates in the To, CC, and BCC fields.
 
For required fields of the Email Type, no@email.com can be used where a valid email address is not available. PowerClerk interprets no@email.com as a signal to omit that address from any communication.
 
When ingesting a Custom List from a .csv file, empty values will not automatically convert the field type to a String Type when an empty value is found. A warning will be displayed noting the empty values, but the desired Type will be retained.If a required field contains empty entries, this can result in a user selecting an entry with no data preventing submission with that selection.
 
Next, please navigate to the Data Field Group tab and click on Add New Custom List Group:
 

 
The dialog that follows will present you with options to configure your new Custom List Field Group as shown in the figure below:
 

 

1. Set your hierarchy order here.
2. Select a display type for the selection fields. Available display types include:
• Drop-down List - Presents options in a collapsible dropdown menu. 
• Radio Button List - Displays all options simultaneously as radio buttons. 
3. Uncheck Include to exclude certain columns from the group. This allows you to use the same data source for multiple lists for different purposes.
4. Select a display type for the output fields. Available display types include:
• Text Box
• Static Text
• Do Not Display – This does not protect sensitive data, since it will still populate in the JSON response.
5. Allows the addition of an editable count field to the list, useful for expressing multiples of selected items.

Custom List output columns can be displayed as static text by selecting the following option:
 

 
To use a Custom List within a Form, ensure that at least one Custom List Data Field Group is defined. Once configured, the “Custom List” form element can be dragged onto the form for use as shown in the figure below:
 

 
 

Table Form Element

PowerClerk’s Table element enables data entry into a group of input fields organized in columns and rows. To make the Table form element available in the Form editor, the table’s schema must first be defined under Program Design >> Data Fields, within the Data Field Groups tab.
 

 
Please Note: Until the newly created Table element is added to a Form, it will not be present in the Data Field Groups tab. To reveal them, toggle Show groups not referenced on current forms. This will display the Table element within the list of available Data Field Groups for the program.
 

Adding a Table to a Form

Once a Table is created, the Form editor allows a Table form element to be dragged onto a Form to enable data entry in columns and rows.
 

 
The default for Tables on a Form is to allow the removal or reordering of rows added to the table.

 

 
In some scenarios, data entered in the table should be locked after entry. Select “Add Row Only” in the Table element properties to prevent editing or reordering of existing data but continue to allow additional rows to be added to the Table element for further data entry.
 

 
Additionally, some tables need at least one row of data in order to be considered complete. If users are expected to enter one or more rows of data every time they complete the form, the ‘Require at least one row’ property can be toggled for the table element on the form that it appears.
 

 

Importing Rows into a Table Element

If configured in the program, table elements can also have the option to “Allow Imported Rows From CSV”. Note: If you do not see this option, but would like it enabled for your program, please reach out to support@powerclerk.com or submit a ticket via the PowerClerk Ticket System.
 

 

 
When this option is enabled, users have the option to add rows to the table by importing a CSV file, rather than adding and completing rows manually. When selected, the user will be asked to choose a CSV file. This file must have columns that match the table exactly to be accepted.
 
Once uploaded, a preview will be generated to approve, then the rows will be added and editable in the table. Additional rows can be added manually in addition to the rows added by the import.
 

 
To expedite the user experience, you can provide a CSV template to quickly download and fill out. To do so, upload the CSV template to the Public Content Library, then add a Hyperlink element to the form pointing to the content library item. You may also want to include the below disclaimer about CSV behavior:
 
ATTENTION: Microsoft CSV files automatically convert 13+ digits to scientific notation and remove leading zeros. To avoid errors in CSV data, please add an apostrophe (‘) to the beginning of data with leading zeros or a length greater than 13 (e.g. ‘004 instead of 004).
 

 

Editing a Table Group

Once Table Groups are created, their schema can be edited by navigating to Program Design >> Data Fields >> Data Field Groups >> Edit Table Group.
 

 
In the ‘Edit Table’ menu, you can rename a column, add a new column, or ‘Hide’ existing column(s). There is a limit of 10 visible Table columns, meaning hidden columns do not count towards the total column count (e.g. a Table can have 10 visible columns, and 10 hidden columns).
 
Columns can only be hidden if they are not currently required on a Form or referenced elsewhere in Program Design. Once a column is hidden, it will no longer appear on Forms that contain the Table element.
 

 
If a column has previously been hidden, the option to ‘Show hidden columns in schema editor’ can be selected, allowing the column to be restored using the ‘Restore Column’ action.  
 
Please Note: Tables MUST contain between 1 and 10 visible columns. If the Table has reached the 10-column limit, the Restore Column button will be displayed, but will be inaccessible for hidden columns.
 

 
Any changes made to the Table schema will be immediately reflected on the Form(s) that the Table is present on.
 

Reporting Table Data

When generating Table data using Reports, each row of data will appear as a new row in Excel, with the instance (row number) listed.
 

 

Data Import into a Table

If a Table already contains existing data, the Data Import feature cannot be used to update it. To perform a bulk update of Table Data, please contact our support team by submitting a ticket on the PowerClerk Ticket System to request assistance with an API-based update.
 
In order to add a single row of data into an empty Table, you can use the following .CSV format:
 

 
 

Enabling PV + Battery Element

To capture PV systems where the storage equipment shares an inverter with the PV arrays (typically DC-Coupled), enable the Storage Equipment option of the PV system element. This enables an “add battery” button and introduces Energy Storage Systems capable of accepting PV DC Input into the inverter drop-down. Energy Storage System options in the inverter dropdown will contain an “[ESS]” to indicate the inverter type and will automatically include internal battery specifications.
 

 
To switch the storage equipment on for an existing PV System Data Field Group, please navigate to Program Design >> Data Fields >>  Data Field Groups. Then use the Edit PV System Group button to enable “Show Storage Equipment?” either Always or Based on Formula and confirm your selection with the OK button.
 
Please Note: Once the “Show Storage Equipment?” switch is turned on for a PV System element this setting *cannot* be reversed or turned off.

 

 
To capture stand-alone energy storage systems or storage systems that use an independent inverter, use the Energy Storage System form element. Note: Please contact our support team by submitting a ticket on the PowerClerk Ticket System to request the Energy Storage System element to be enabled for your PowerClerk program:

 
Learn more about the Built-in DER form element; the PV System element.
Lean more about program-wide PV System Element Options.

Video Guides

Would a video guide help to better explain Data Fields? Contact us and let us know.

FAQs

Have additional questions? Contact us to nominate your FAQ and help others find answers to your own questions concerning this feature.

Create A Support Ticket

Not finding your answer here?  Submit a question to our support team at the PowerClerk Ticket System and leverage the PowerClerk team’s expertise.