Difference between revisions of "Custom Fields – General Information"
Nancy Sabo (talk | contribs) |
Nancy Sabo (talk | contribs) |
||
| Line 1: | Line 1: | ||
__TOC__ | __TOC__ | ||
| + | |||
| + | ==General Description== | ||
| + | A custom field is created on an as-needed basis, and is associated with a SmartSimple entity such as a contact, company, role, or activity. These fields can be accessed and controlled via links on the Global Settings page or on the Entity Settings Page within a UTA. New custom field types are added on a regular basis, so check the upgrade notes in the Wiki for the latest field types. | ||
| + | |||
| + | ===Overview=== | ||
| + | Many areas in SmartSimple are comprised mainly of custom fields--such as the Universal Tracking Application--so understanding their proper setup and use is vital in order to create an easy-to-use instance that addresses your organization's needs. There are over 50 field types that you can use to capture and store data; these can be grouped on tabs, or displayed in multiple columns to avoid cluttering the page. The maximum number of custom fields that can be displayed on a single page is 400 total. New fields can be created at any time, without affecting current data. | ||
The following settings are common to almost all [[Custom Fields|Custom Field]] types: | The following settings are common to almost all [[Custom Fields|Custom Field]] types: | ||
| Line 99: | Line 105: | ||
===Role Field Permissions and Status Field Permissions=== | ===Role Field Permissions and Status Field Permissions=== | ||
| − | Access to a [[Custom Field|custom field]] is controlled by permissions. | + | Access to a [[Custom Field|custom field]] is controlled by permissions. These can be found and set in any custom field, on the Permissions and Availability tab. You can set only certain roles to be able to see/edit a field, or you can do the same thing with statuses. An example would be denying the Applicant role permission to see the Decision custom field. |
See [[Role Field Permissions]] or [[Status Field Permissions]] for more information | See [[Role Field Permissions]] or [[Status Field Permissions]] for more information | ||
| − | + | <!-- | |
| − | [[Image:Cf8.png]] | + | [[Image:Cf8.png]] --> |
<!-- | <!-- | ||
| Line 122: | Line 128: | ||
These fields can consist of files of any type such as documents or images. Document type fields are searchable provided the '''File Index''' option is selected (this option is only available for these types of fields). --> | These fields can consist of files of any type such as documents or images. Document type fields are searchable provided the '''File Index''' option is selected (this option is only available for these types of fields). --> | ||
===Custom Field References=== | ===Custom Field References=== | ||
| − | This feature is intended to help determine the impact of a custom field change by highlighting where the custom field is referenced within the system | + | This feature is intended to help determine the impact of a custom field change by highlighting where the custom field is referenced within the system. |
| + | Each Custom field has a '''Search Reference'''--this button is found in the action bar, and can be identified by the magnifying glass icon. | ||
| + | <!-- | ||
| + | [[Image:SearchReference1.png|border]]--> | ||
| − | + | When used, the feature will search references to this custom field via variable syntax in various areas, including: | |
| − | |||
| − | |||
| − | |||
| − | When used the feature will search references to this custom field via variable syntax in various areas, including: | ||
* Other custom field options/visibility condition, including [[JavaScript Validation]], [[Visibility Condition]], [[Custom Field Type: Special – Calculated Value|calculated values]], etc. | * Other custom field options/visibility condition, including [[JavaScript Validation]], [[Visibility Condition]], [[Custom Field Type: Special – Calculated Value|calculated values]], etc. | ||
| Line 143: | Line 148: | ||
===Import and Export Custom Fields=== | ===Import and Export Custom Fields=== | ||
You can use the custom field '''Import''' and '''Export''' features to move or copy custom fields from one [[Entity|entity]] to another (or even another instance of [[SmartSimple]]). The custom fields are exported and importing by using [[XML]] format. | You can use the custom field '''Import''' and '''Export''' features to move or copy custom fields from one [[Entity|entity]] to another (or even another instance of [[SmartSimple]]). The custom fields are exported and importing by using [[XML]] format. | ||
| − | + | <!-- | |
| − | [[Image:Cf10.png|link=]] | + | [[Image:Cf10.png|link=]]--> |
To export a block of custom fields, simply click the ''Export'' button at the top of a list of custom fields. A window will pop up showing the custom field settings in XML format: | To export a block of custom fields, simply click the ''Export'' button at the top of a list of custom fields. A window will pop up showing the custom field settings in XML format: | ||
| Line 150: | Line 155: | ||
[[Image:ImportExportCustomFields.png|link=|500px]] | [[Image:ImportExportCustomFields.png|link=|500px]] | ||
| − | The XML block for the entire set of custom fields in the list will be displayed. Individual custom fields are delineated by the tags. Simply copy the block of custom fields you want to copy (you can make edits, e.g. to the [[display order]] in a text editor), click on the ''Import'' button at the top of the list of custom fields where you want to place the new fields, paste the XML block into the blank text area and confirm that you want to import the fields by clicking ''Import'' at the bottom of the Import pop-up. | + | The XML block for the entire set of custom fields in the list will be displayed. Individual custom fields are delineated by the tags. Simply copy the block of custom fields you want to copy (you can make edits, e.g. to the [[display order]] in a text editor), click on the ''Import'' button at the top of the list of custom fields where you want to place the new fields, paste the XML block into the blank text area, and confirm that you want to import the fields by clicking ''Import'' at the bottom of the Import pop-up. |
The majority of field settings will be included in the copied fields. Exceptions include: | The majority of field settings will be included in the copied fields. Exceptions include: | ||
Revision as of 09:46, 23 August 2018
General Description
A custom field is created on an as-needed basis, and is associated with a SmartSimple entity such as a contact, company, role, or activity. These fields can be accessed and controlled via links on the Global Settings page or on the Entity Settings Page within a UTA. New custom field types are added on a regular basis, so check the upgrade notes in the Wiki for the latest field types.
Overview
Many areas in SmartSimple are comprised mainly of custom fields--such as the Universal Tracking Application--so understanding their proper setup and use is vital in order to create an easy-to-use instance that addresses your organization's needs. There are over 50 field types that you can use to capture and store data; these can be grouped on tabs, or displayed in multiple columns to avoid cluttering the page. The maximum number of custom fields that can be displayed on a single page is 400 total. New fields can be created at any time, without affecting current data.
The following settings are common to almost all Custom Field types:
- Custom Field ID
- Field Type
- Field Name
- Caption
- Display Order
- Description
Field Name and Field ID
- The field name is mandatory and can be up to 255 characters in length.
- The name should not include special characters that could be misinterpreted by the browser.
- The Field ID is automatically generated by the system as a number value and is displayed to the right when viewing the list of custom fields.
Referencing Field Names and Field IDs in other Custom Field Types
You can reference fields by name or by ID in other fields. The following field types support this type of referencing:
- Display Only – External Entity Details.
- Display Only - Web Page View.
- Special – Calculated Value.
The syntax for these field types varies (some are processed on the server and other in a JavaScript in the client) and is explained for the individual field type.
Field Type The field type is used to define the characteristics of the field. There are over 50 field types currently available.
Display Order
- This setting determines the order that the field will be displayed on the page. The first field that is added to an entity will use a display order of 10.
- Additional fields that you add will automatically increase the display order by increments of 10.
- If you wish to insert a field between two fields you can set the display order to a number that will position the field where required.
- You can change the display order by setting the display order to a different number. For example, if you set the display order on a field to 5000 then the next field added will automatically become 5010.
Display Order with Related Entities
If you add custom fields to the basic contact entity and then add fields to roles associated with contacts, you will need to take care, as the fields will become mixed if they have the same number sequence.
The following table outlines where you need to be careful:
| Entity | Related Entity |
| Contact | Roles |
| Companies | Categories |
| UTA Level 1 Entities | UTA Level 1 Template Entities |
You should start the number sequence for these types of related fields at some higher level. For example, role 1 starts at 5000, role 2 starts at 8000.
Common Custom Field Settings
Each custom field contains a button at the top linking it to the three following settings pages:
- Field Data - displays all the values that have been saved to the field.
- Update History - displays all the updates to field settings.
- Search Reference - displays all locations where the custom field is referenced in the system.
Tab Name
- If you add a text value to the tab Name, the field will be displayed on that tab.
- The tab name can be any text string.
- Custom fields that are not associated with a tab will be displayed on a tab named Default.
- The Tab Name option appears once the Advanced Options are enabled, on the Classic Options tab.
Visibility Condition
Whether or not a custom field is visible can be controlled using conditional statements in this box. (Appears on the Permissions and Availability tab, once the Advanced Options are enabled.)
See Visibility Condition for more information.
Role Field Permissions and Status Field Permissions
Access to a custom field is controlled by permissions. These can be found and set in any custom field, on the Permissions and Availability tab. You can set only certain roles to be able to see/edit a field, or you can do the same thing with statuses. An example would be denying the Applicant role permission to see the Decision custom field.
See Role Field Permissions or Status Field Permissions for more information
Custom Field References
This feature is intended to help determine the impact of a custom field change by highlighting where the custom field is referenced within the system. Each Custom field has a Search Reference--this button is found in the action bar, and can be identified by the magnifying glass icon.
When used, the feature will search references to this custom field via variable syntax in various areas, including:
- Other custom field options/visibility condition, 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
You can use the custom field Import and Export features to move or copy custom fields from one entity to another (or even another instance of SmartSimple). The custom fields are exported and importing by using XML format.
To export a block of custom fields, simply click the Export button at the top of a list of custom fields. A window will pop up showing the custom field settings in XML format:
The XML block for the entire set of custom fields in the list will be displayed. Individual custom fields are delineated by the tags. Simply copy the block of custom fields you want to copy (you can make edits, e.g. to the display order in a text editor), click on the Import button at the top of the list of custom fields where you want to place the new fields, paste the XML block into the blank text area, and confirm that you want to import the fields by clicking Import at the bottom of the Import pop-up.
The majority of field settings will be included in the copied fields. Exceptions include:
- any Field Permissions
- any Field Permission Matrix assigned to the original custom field
- any Value Stores To setting assigned on the original custom field
- the Description setting
However, Field Permissions and Field Permission Matrices can be assigned to the new fields using the Batch Update feature.
As the custom field ID is unique to each custom field in the system, the custom field IDs will not be copied. Any newly created custom fields using the Export/Import feature will be assigned new custom field IDs.
Also see Custom Field Import Wizard
Custom Field Types
The full list of Custom Field Types can be found on the Custom Field Types page.
