Overview
A Custom Field serves as the fundamental unit of data storage, established as needed for your system, and is linked to a SmartSimple entity such as a contact, organization, role, or activity. These fields can be accessed and managed from either the Global Settings section of your system or on the Entity-based Settings page within the system.
New custom fields are introduced regularly; currently, we offer over 50 field types that can be utilized to capture and store data. For a comprehensive list of Custom Fields, please refer to Types of Custom Fields. Additionally, you may consult the Upgrades section of our knowledgebase for ongoing updates regarding the latest field types.
Custom Fields are utilized alongside Standard Fields, which are inherently integrated into your system (for instance, typical Standard Fields include Name or Address ). While Custom Fields can be added, removed, and tailored to specific needs, Standard Fields generally remain unchanged, although they may be renamed or modified.
All fields present data in configurable formats: for example, they can be organized into tabs or displayed in multiple columns to prevent page clutter.
- The maximum number of custom fields that can be displayed on a single page is 400 in total.
Accessing Custom Fields
Global Settings
System Administration (gear icon) >> Global Settings >> System (tab) >> [Custom Fields]
UTA-Specific
System Administration (gear icon) >> Tracking Applications >> [Edit] *UTAname >> Level 1/2/3 (tab) >> [Custom Fields]
The hyperlink to Custom Fields will be available under each tab. Clicking the Custom Fields link under a specific tab will direct you to the custom fields associated with the purpose of that tab. For instance, if you click on the Custom Fields under the User tab, you will be taken to a list of all custom fields specifically related to users, both internal and external.
| System - Custom Fields | A comprehensive list of all custom fields from all object types within the system. |
| Organizations - Custom Fields | Create and manage custom fields for Branch (Internal organization on the organization hierarchy) and Organization (External) |
| Users - Custom Fields | Create and manage custom fields for users, both Internal Staff and External Contacts |
| Associations - Custom Fields | Create and manage custom fields for associations, which can occur between companies and users or company-to-company |
| Transactions - Custom Fields | Create and manage custom fields for Transactions and transactions attributions |
When you click on a Custom Fields hyperlink from the Global Settings section, you will be directed to a list display of all available custom fields pertaining to that segment of the system. To modify a Custom Field, you may simply select the pencil icon to the left of the custom field name, as illustrated below:
- Utilizing the Search function located at the top right, you can search through all Object Entities or through the fields of specific entities. Simply select or deselect to manage your results.
- Tip: A search-based strategy for troubleshooting involves clearing your previous search, selecting All Object Entities within the search bar, and then clicking on the Last Modified field in the list view to arrange it in descending Sort Order to review the date when a custom field was altered, added, etc.
- You can also access all deleted fields by navigating to the second tab. There is no time constraint within the system that removes deleted records; thus, you can easily select and restore or purge these previously deleted fields.
- There should be no necessity to purge, as Custom Fields do not consume significant space within the system.
- When restoring fields, there is no loss of data.
Configuration - Essentials
This page will serve as the primary repository for setup information that is commonly shared among most field types. To find setup options specific to a certain field type, please refer to the Wiki page dedicated to that field type.
Common Custom Field Functions
At the top left of the Custom Field record, there will be a row of buttons, each serving different functions related to the field.
The following table outlines the functionality of each button from left to right:
| Custom Fields list | Clicking this list chart icon will take you to the list of all custom fields available in this section of the system. For instance, if you are viewing a Custom Field located under the Organizations tab of Global Settings, you will be directed to a comprehensive list of all custom fields related to Organizations. |
|
New Custom Field (+ icon) |
Clicking this plus icon will enable you to create a New Custom Field within this section of the system. For guidance on creating a new custom field by appropriately filling out the various settings, please continue reading the subsequent sections on this page. |
|
Field Data (stack of coins icon) |
Clicking this will open a page that displays all values that have been saved to the field. Custom Field Data comprises two general types: text type fields (saved as a text string) and object type fields (which include any files such as documents or images). |
|
Update History (reload icon) |
Clicking this will open a page featuring a list of all updates made to the settings of this field. |
|
Search Reference (magnifying glass icon) |
Clicking this will display all locations where the custom field is referenced within the system. Fields are fully searchable for any related application. For example, fields at the role level can be searched through the Search People feature or any application that provides access to contact data. Additionally, you may search and replace these values in bulk by utilizing the Field Data button and specifying the old and new required values. |
The following settings are commonly applicable to nearly all Custom Field types:
- General Settings
- Display & Formatting
- Validation
- Feature Options
- Value Storage
General Settings
The General Settings will be displayed immediately upon opening a Custom Field for editing.
| Option | Description | Format |
|---|---|---|
| Custom Field ID |
The unique ID number associated with the custom field.
|
Not Applicable |
| Field Type |
The list of available Field Types.
|
@fieldtype@ |
| Field Name |
The name of the field, used internally to reference the user's input;
|
@fieldname@ |
| Caption |
The introductory question or prologue preceding the field.
|
@caption@ |
| Display Order |
The order (relative to other fields) in which this field is presented.
|
@displayorder@ |
| Description | Definition and general description of the custom field. Will not be displayed. | @description@ |
Display Order with Related Entities
When incorporating custom fields into the fundamental contact entity and subsequently adding fields to roles associated with contacts, it is imperative to exercise caution, as the fields may become conflated if they share the same numbering sequence.
The table below outlines the areas where caution is advised:
| Entity | Related Entity |
|---|---|
| Contact | Roles |
| Companies | Categories |
| UTA Level 1 Entities | UTA Level 1 Template Entities |
It is advisable to commence the numbering sequence for these types of related fields at a higher level. For instance, role 1 may begin at 5000, while role 2 could start at 8000.
Display & Formatting
The Display & Formatting section of Custom Fields can be accessed by navigating to the first tab of General Settings during the editing of a Custom Field.
| Option | Description |
|---|---|
| Caption Location |
Determines the positioning and visibility of the caption relative to the field. Options include: Left of Field, Above Field, No Caption, Hide Caption.
|
| Instructions | Text entered here will be displayed beneath the caption. Even if the caption has the Hide Caption option enabled, any defined instructions will remain visible above the input. |
| Placeholder Text |
Text entered here will appear within the text box as placeholder text, which will disappear once the user clicks into the field to input content.
|
| Tool Tip | When the user hovers their mouse pointer over the question mark adjacent to a field, the text in this section will be displayed. |
| Classify as Personal Data | For use in identifying personal data. |
| SmartField View | Include or exclude this field from SmartField View (@SmartFields@) or display this field solely for SmartField Views. Refer to SmartField View for further details. |
| SmartFields PDF Formatting | PDF formatting option when rendered from SmartField View. |
| Width / Max Width | Width of the input box - options include Full, Large, Medium, Small. |
| Number of Columns | Determines the number of columns utilized for display purposes. |
| Align | Controls the justification of the text within the field - Left, Center, Right. |
| Number Format | Controls the format of the data displayed in View mode - for example, Comma, Currency, or Percent. |
| Number Precision | Controls the precision of the numerical amount displayed - for example, Whole Number, x number of Decimals, or Nearest Ten. |
| Thumbnail Width | Determines the width of the image's thumbnail, measured in pixels. |
| Thumbnail Height | Determines the height of the image's thumbnail, measured in pixels. |
| Sort Order | Establishes the sorting order for files uploaded to the field. Options include: file name, file size, and upload date. |
| Stroke Colour | Allows for the selection of the stroke color. |
| Button Label | Specifies the label for a custom button. |
| Apply Format in Edit Mode | Maintains the field data formatting in Edit mode. |
| Fixed Column Widths | Establishes a uniform width when multiple columns are specified. This is applicable with Layout fields. |
Caption - Label Display Options
Below are examples illustrating the outcomes of various selections for the Caption Location setting within a custom field:
Left of Field
Above Field
No Caption
Hide Caption
Instructions - Example
To add a button that downloads an Excel file template sourced from within a SmartFolder, use the following [Instructions] syntax within a Custom Field - such as an "Upload - Multiple Files Storage" Type:
Please download the <a href="/files/289180/f91226/Collaboration_worksheet.xlsx">Collaboration Worksheet</a> using the download button below, and copy/paste your data into this upload field.
<br>
<a href="/files/289180/f91226/Collaboration_worksheet.xlsx" class="Button" download>Collaboration Worksheet</a>- Add your XLSX file path within the
<a href=""tag - this file path may be located from within your SmartFolders by selecting the [Get Link] button
Validation
The Validation section is located under the General Settings tab and appears as follows:
| Option | Description |
|---|---|
| Mandatory | Selecting this option indicates that this field is required and must be completed. |
| Appear Mandatory | Causes the field to appear as though it is mandatory. This is typically used in conjunction with browser scripts, JavaScript Validation, or Submit Logic that perform validation. From the user's perspective, the field will usually be indicated with a red asterisk (*) to signify that it is mandatory. |
| Custom Validation | Specifies validation based on JavaScript syntax. |
| Failed Validation Message | Input the message that will be displayed if validation fails. |
| Minimum Length | Input the minimum required number of characters as a restriction on the user's input into the field; users must input at least this minimum number of characters for successful validation. A suitable use case for this would be a minimum of 9 characters for a mandatory Phone Number field. |
| Maximum Length | Input the maximum allowable number of characters as a restriction on the user's input into the field. Users must input fewer than this maximum number of characters (and, if required, more than the minimum) for successful validation. A suitable use case for this would be a maximum of 6 characters for a Postal Code field for a Canadian address. |
| Show Counter | Enabling this option will activate a counter that counts down the number of characters available for user input before reaching the maximum. It will also indicate if the user has exceeded the maximum by displaying negative digits. |
| Show Words | Enabling this option will restrict the maximum and minimum lengths, if specified, to the number of individual words rather than characters. |
| Exceeded Maximum Message | Enabling either Show Counter or Show Words will activate this option. Input the text that you wish to display to the user if they exceed the maximum length for either characters or words. |
Feature Options
The Feature Options section of Custom Fields settings can also be located under the General Settings tab while editing a Custom Field. The Feature Options section will appear as follows:
| Option | Description |
|---|---|
| Track Changes | Enables the logging of all modifications made to any specified Custom Fields or Standard Fields within the system, including within a Universal Tracking Application, contact, company or transaction record. |
| Show Display Value in List Views | Enabling this option will display the display value; by default, the stored value is shown when fields are referenced in List Views. |
| Enable Multiple Select | Enables users to select multiple values from the provided options. |
| Enable Map Service | Displays a map icon next to the field name. This icon will launch the user’s selected map service and display a map of the content of the field, provided a valid address is stored in the field. |
| Enable Translation Service | Facilitates language translation of data entered into text fields through integration with Google Translate. |
Value Storage
The Value Storage section represents the final area of General Settings when editing a Custom Field. It will appear as follows:
| Option | Description |
|---|---|
| From Custom Field(s): | Displays the name of the source field from which the current field is retrieving data; refer to Value Stores To. |
| To Custom Field: | Denotes the field to which this field will send data; refer to Value Stores To. |
Value Stores To
For most types of Custom Fields (all fields that store data rather than files) the Value Storage section allows you to select another field on the same entity (or within the Universal Tracking Application at the same level) to store the same data.
- This can be useful if you wish to display the data in another location on the record.
- It also allows you to have another field that displays the information with different Status Field Permissions, Role Field Permissions and/or Visibility Conditions.
Whenever values need to be passed between levels, a Template / Type Formula should be used. The exceptions are Web Page View, MS Word Merge and Single File or Multiple Files fields which allow selection of a file storage Custom Field using Value Stores To. The Single File or Multiple Files field selected in the Value Stores To option can be at the same level, or on the parent or grandparent levels (if available).
The To Custom Field option can also be used in Shadow Applications that don’t inherit their Custom Fields from the parent. Again, Value Stores To only allows storage of data to Custom Fields on the same level, either in the Shadow Application or in the Parent UTA.
The To Custom Field option can also be used with dependent (child) fields on Dynamic Control Fields to store to other fields on the same level.
The From Custom Field displays the name of the source field that the current field is pulling data from.
Permissions & Availability
The second tab accessible when opening a Custom Field is typically the Permissions & Availability section. The configuration of permissions and availability may vary based on the type of Custom Field and its association within the system; however, the Permissions & Availability options may appear as follows:
Access to a custom field is regulated by permissions. These permissions can be located and configured within any custom field on the Permissions and Availability tab. It is possible to restrict certain roles from viewing or editing a field, or to apply similar restrictions based on statuses. For example, one might deny the Applicant role the permission to view the Decision custom field, as this would disclose prematurely whether their application has been approved or denied.
| Role - Field Permissions |
Allow View Field: Click into this text box to select which roles will be permitted to view this field. When they access a record in the system that contains this field, they will be able to view the field and any content previously entered. Allow Modify Field: Click into this text box to select which roles will be permitted to modify this field. When they access a record in the system that contains this field, they will be able to view the field as well as modify any content that has been entered, or input content if no data has been entered previously. Deny View Field: Click into this text box to select which roles will be denied permission to view this field. If they access a record in the system containing this field, it will not be visible in the record details. Deny Modify Field: Click into this text box to select which roles will be denied permission to modify this field. If they access a record in the system with this field, they will be able to view it but will not have the ability to modify its content. |
| Organizations Status - Field Permissions |
Allow View Field: Click into this text box to select which statuses will have permission to view this field. In this context, the status must pertain to the organization; only an organization that is in the selected statuses will be able to view this field when accessing a record. Allow Modify Field: Click into this text box to select which statuses will have permission to modify this field. 'Deny View Field: Click into this text box to select which statuses will be denied permission to view this field. For instance, an organization that is in Inactive 'Status might be denied permission to view fields, as there is no necessity for them to access that information. Deny Modify Field: Click into this text box to select which statuses will be denied permission to modify this field. |
| Category - Field Availability |
Include Field For: Click into this text box to select which organization categories will be granted permission to complete this field. Exclude Field For: Click into this text box to select which organization categories will not be granted permission to complete this field. |
Visibility Condition
The Visibility Options section when accessing a Custom Field is available under the Permissions and Availability tab once the Advanced Options feature has been activated.
To enable Advanced Options, you must activate the feature from the upper right section of your page.
The visibility of a custom field can be controlled using conditional statements within this box. You may establish this visibility condition for new records based on the following options: Always Display, Hide on New Record, or Only Show on New Record.
Classic Options
The final tab accessible when opening a Custom Field record is typically the Classic Options section.
| Tab Name |
If you input a text value into the Tab Name, this field will be displayed on that tab.
|
| Custom HTML Tag |
Utilize this field for additional attributes to the field's HTML tag. For instance, you may add HTML such as style="background-color"=00ff00 to change the background color of this field box. Searchable - Read Only - Enable KML - Disable Quick Edit - Activating this option will prevent the user from modifying this field using the system's Quick Edit functionality. Disable Field from Global Search - Activating this option will exclude this field from any results generated by the system's Global Search functionality. |
Custom Field References
This feature is designed to assist in assessing the implications of a custom field modification by identifying where the custom field is referenced throughout the system. Each Custom Field includes a Search Reference—this button is located in the action bar and can be recognized by the magnifying glass icon.
When utilized, this feature will search for references to this custom field via variable syntax in various areas, including:
- Other custom field options/visibility conditions, including JavaScript Validation, Visibility Condition, calculated values, etc.
- Template formulas
- Submit buttons
- Submit Logic
- SmartCheck Validation
- Workflow Task
- Workflow connectors
- Data class policy
Import and Export Custom Fields
The custom field Import and Export functionalities allow for the transfer or duplication of custom fields between different entities, or even across different instances of SmartSimple. The export and import processes utilize the XML format.
To export a group of custom fields, simply click the Export button located at the top of the custom fields list. A window will appear displaying the custom field settings in XML format:
The XML block representing the complete set of custom fields in the list will be shown. Individual custom fields are identified by specific tags. You may copy the desired block of custom fields (edits can be made, such as adjustments to the display order in a text editor), then click the Import button at the top of the list of custom fields where you wish to add the new fields. Paste the XML block into the designated text area, and confirm the import by clicking Import at the bottom of the Import pop-up window.
The majority of field settings will be transferred with the copied fields. Exceptions include:
- any Field Permissions
- any Field Permission Matrix associated with the original custom field
- any Value Stores To setting linked to the original custom field
- the Description setting
However, Field Permissions and Field Permission Matrices can be assigned to the new fields through the Batch Update feature.
As the custom field ID is unique to each custom field within the system, the custom field IDs will not be duplicated. Any newly created custom fields utilizing the Export/Import feature will be assigned new custom field IDs.
Also refer to the Custom Field Import Wizard.
Custom Field Types: Special - Calculated Value
- Expressions entered into this field type are evaluated as JavaScript functions.
- These functions are integrated into the associated page and executed within the client browser.
- Any valid JavaScript construct may be incorporated into these expressions.
- A significant limitation of this expression type is that it can solely utilize values that are present on the current page.
- The expression is not capable of manipulating values stored on other tabs or aggregating data from related entities.