Fields
Overview
The Fields section in Studio allows administrators to create new fields for stock and custom modules as well as update existing fields. To access the Fields section in Studio, select "Fields" from the Modules panel under the desired module (e.g., Cases) and the Edit Fields tab will open in the main panel.
Field Types
Studio comes out-of-the-box with many different types of fields, which can be created in Sugar. Please note that the options and properties available when configuring the field varies for each data type.
The following data types are available in Studio:
Data Type | Description |
ActionButton |
Creates buttons in record view for shortcuts to specific actions (e.g., create email). Please refer to the Action Buttons documentation for information on configuring Action Button fields. |
Address |
Creates fields for street, city, postal code, state, and country. Note: Custom address fields cannot be grouped together like stock address fields (e.g., billing address). |
AutoIncrement |
Creates a field that automatically populates a number, increasing subsequent records' field values by one, on the first save of a record. As an integer-type field, AutoIncrement is limited at the database level to values up through 2147483647. Only one AutoIncrement field can be created per module; afterward, the option will not be available during field creation. Note: This field cannot be edited. |
Checkbox | Creates a checkbox for data fields with a Yes/No action. |
Currency | Creates a field to enter a currency value. The system automatically creates a dropdown of the currency type if the field does not already exist in that module. |
Date | Creates a field to enter a date. Includes a button for a calendar popup. |
DateTime | Creates a field to enter the date and time. Includes a Calendar icon button to choose a date via the popup calendar, as well as a dropdown list to select the time. |
Decimal | Creates a field to hold a number rounded to a specified decimal precision. Sugar stores the exact representation of the number in the database (e.g., For a precision of 2: 1.236 is stored as 1.24). |
Dropdown |
Creates a field where you can associate a dropdown list of values. Note: For calculated Dropdown fields, the result of the formula gets written to the database, and Sugar does not validate these results. So, if the resulting value is not a valid option in the dropdown list, then the dropdown field will be blank as it found no matches. For example, if the dropdown list has values "A, B, C" and the formula results in a value of "1", then "1" will be written to the database, and the field will appear blank. |
Encrypt | Creates a field for sensitive information, such as social security numbers, whose value is to be encrypted in the Sugar database. The value is encrypted using the Blowfish algorithm prior to being captured in the database. It is decrypted prior to display in the user interface to users. The first time an encrypted field is enabled, a unique key is automatically generated and stored on the filesystem in the file ./custom/blowfish/encrypt_field.php . This generated key is used for all subsequent field-level encryption and decryption operations. |
Flex Relate |
Creates a dropdown list from which you can relate a single record from a variety of modules. See the Introduction to Relationships and Relate Fields article for an explanation of the differences between relate fields, flex relate fields, and relationships. Note: Only one Flex Relate-type field is allowed per module. Out of the box, the Flex Relate option is not available for the Accounts, Calls, Contracts, Meetings, Notes, and Tasks modules. |
Float | Creates a field to hold a number rounded to a specified decimal precision. Sugar stores the value differently based on the database platform Sugar is running on. |
HTML | Creates static HTML-formatted text to display in record views. |
Iframe |
Creates a field to store or generate a URL to display an iframe in record views. Note: To load content from an external website in the iframe field, administrators will need to add the URL (e.g., https://www.example.com) as a trusted site via Admin > Content Security Policy Settings. |
Image | Creates an image field to upload an image to display on a record. |
Integer |
Creates a field to specify positive or negative numbers with no decimal places. Note: Integer fields are limited at the database level to values up through 2147483647. |
MultiSelect | Creates a dropdown list of values where multiple values can be selected at once. |
Phone |
Creates a field to enter a phone number. If the Enable Click-to-Call setting is turned on in Admin > System Settings, phone number fields are displayed as links that can be opened to dial them using the default computer telephony integration software on the user's computer. For Sugar Sell or Serve users logged in to Amazon Connect, calls are dialed in SugarLive. |
Radio | Creates a radio button for a user to select one value from a dropdown list. |
Relate |
Creates a field to associate a record with another module's record as a one-way relationship. You can add multiple Relate fields to a module. Note: Relate fields and custom relationships are independent of each other. Changes made to either one are not reflected in the other. Relate fields can be added to a report, but any data on the related record cannot be accessed in the report. To access related record data in a report you will need to create a custom relationship. See the Introduction to Relationships and Relate Fields article for an explanation of the differences between relate fields and relationships. |
Relationship |
This field type cannot be used when creating a field in Studio, but it is automatically created for one-to-one and many-to-one relationships that add a field representing the relationship in the module. For example, the Account Name field on the Contacts module has a type of "Relationship" because it is based on a many-to-one relationship between contacts and accounts. See the Introduction to Relationships and Relate Fields article for an explanation of the differences between relate fields and relationships. |
TextArea | Creates an open text area field for multiple lines of text. |
TextField | Creates a field for a single line of text. |
URL | Creates a field to store or generate a URL and display as a link. |
Note: Name-type and ID-type fields cannot be created via Studio. Each stock module and module created via Module Builder will have a Name-type and ID-type field. The Name-type field is automatically displayed in the header of each record view (for Sidecar modules) while the ID field is not available in Studio but is a part of the unique URL for each record.
Field Options
Fields provide ways to store different data types in Sugar. While many fields come with Sugar by default, there can be instances where your organization needs to create custom fields to store additional data.
Each field, depending on the data type, will have different properties and options available when configuring the field via Studio. Please note that some properties can exist across all data types and some are unique to only a few types.
The following properties and options are available for fields in Studio:
Allow Imports
Applies to: Address, Checkbox, Currency, Date, Datetime, Decimal, Encrypt, DropDown, Float, HTML, IFrame, Integer, MultiSelect, Flex Relate, Phone, Radio, Relate, TextArea, URL, TextField
Select one of the following options to determine the field's behavior when importing records:
- Yes: This field is available to be mapped to when performing an import.
- No: This field is not available to be mapped to when performing an import. It will be omitted from the Module Field dropdown list.
- Required: This field is required to be mapped to when performing an import. It will have an asterisk (*) next to it in the Module Field dropdown list to indicate that it is required.
Audit
Applies to: Address, Checkbox, Currency, Date, Datetime, Decimal, Encrypt, DropDown, Float, IFrame, Image, Integer, MultiSelect, Phone, Radio, Relate, TextArea, URL, TextField
Select this checkbox to audit the field for changes made in Sugar.
- Users can view the changes made to audited fields via the View Audit Log option in the module's record view (for Sidecar modules) or detail view (for Legacy modules).
- Fields marked as "Audit" will generate update posts in the activity stream for Sidecar modules (e.g., Accounts, Contacts, etc.) whenever the field gets updated. For more information on activity streams, please refer to the Activity Streams documentation.
AutoIncrement Next Value
Applies to: AutoIncrement
This field allows you to set and view which value is the next to be applied to a record. As an integer-type field, AutoIncrement is limited at the database level to values up through 2147483647.
Boost Value
Applies to: Phone, TextArea, TextField, URL
Enter a boost value for the field to enhance the relevancy of the field for full-text search. The default boost value is 1.0 which indicates a neutral boost. To apply a positive boost, set the boost value higher than 1. To apply a negative boost, use values lower than 1. For example, a value of 1.35 will positively boost a field by 135%. But using a value of 0.60 will apply a negative boost. It is not necessary to perform a full system index when boost values are changed for fields.
Border
Applies to: Image
Select this checkbox to add a border around the image for this field.
Calculated Value
Applies to: Checkbox, Currency, Date, Datetime, Decimal, DropDown, Encrypt, Float, Integer, Phone, TextArea, TextField
Select this checkbox to designate this field as a calculated field. This opens up the Formula option and disables the Default Value and Importable options. For more information regarding entering a formula for a calculated value, please refer to the Formula option listed in this section. The result of the formula will be entered into the field for any new or modified records. When selecting this option, the field value cannot be modified by users.
Note: For calculated Dropdown fields, the result of the formula gets written to the database, and Sugar does not validate these results. So, if the resulting value is not a valid option in the dropdown list, then the dropdown field will be blank as it found no matches. For example, if the dropdown list has values "A, B, C" and the formula results in a value of "1", then "1" will be written to the database, and the field will appear blank.
Columns
Applies to: TextArea
Enter the number of columns to specify the width of a TextArea data type field.
Comment Text
Applies to: All data types except Flex Relate
Enter a comment or description about the field. The comment text is only viewable via Studio.
Default Value
Applies to: Address, AutoIncrement, Checkbox, Currency, Date, Datetime, Decimal, Encrypt, DropDown, Float, IFrame, Integer, MultiSelect, Phone, Radio, TextArea, URL, TextField
Specify or select a default value for this field when a record is created. Default values for the record are populated by default but can be modified by users.
Dependent
Applies to: All data types except ActionButton and Address
Select this option to designate this field as being dependent on a formula or a parent dropdown.
- For dropdown data type fields you can select "Parent Dropdown" or "Formula" for the dependency.
- Selecting "Parent Dropdown" will open the Parent Dropdown option as shown below. Selecting "Formula" will open the "Visible If" option to create a dependency formula. For other field data types (e.g., Date), select the Dependent checkbox to open the Visible If option. For more information regarding entering a formula to make a dependent field visible, please refer to the Visible If option listed in this section.
Disable Format
Applies to: Integer
Select this checkbox to disable number formatting such as the thousands separator.
Display Label
Applies to: All data type fields except Flex Relate. Flex Relate uses the Label Value option.
Enter a value to display as the field label and header in layouts. Normally defaults to the Field name entered when creating field. This value is also modifiable via the Labels section of Studio.
Drop Down List
Applies to: DropDown, MultiSelect, Radio
Select a list of values to associate to the field. Only values in the chosen list will be available for selection in the field. Click "Edit" to change the values for the currently selected list, or click "Add" to create a new list.
For more information on editing dropdown values via the Dropdown Editor, please refer to the Editing Dropdown Lists section of the Developer Tools documentation.
Duplicate Merge
Applies to: All data type fields except Image
Select one of the following options to determine the field's functionality when records are being merged:
- Disabled: Selected by default. The field will not appear on the Merge Duplicates screen.
- Enabled: The field will appear on the Merge Duplicates screen.
- In Filter: (Legacy/BWC modules only) The field will appear in the Merge Duplicates feature, and will also be available in the Find Duplicates feature.
- Default Selected Filter: (Legacy/BWC modules only) The field will be used for a filter condition by default in the Find Duplicates page, and will also appear in the Merge Duplicates feature.
- Filter Only: (Legacy/BWC modules only) The field will not appear in the Merge Duplicates feature but will be available in the Find Duplicates feature.
Field Name
Applies to: All data type fields
Enter the name of the field being created. Once a field has been created the field name cannot be changed.
- Field names can contain only alphanumeric characters as well as the underscore character.
- Custom fields added via Studio are automatically appended with "_c" to ensure the field does not conflict with a current or future stock field.
- The following names are reserved system names and cannot be used when creating custom fields: processed, id, id_c, parent_name, or parent_id.
Formula
Applies to: Checkbox, Currency, Date, Datetime, Decimal, Encrypt, Float, Integer, Phone, TextArea, TextField when the Calculated Value option is selected.
Contains the current formula to return a calculated value. Click "Edit Formula" to launch the formula builder and change the formula. For more information on how to build a formula using the formula builder, please refer to the Using Sugar Logic documentation.
Full Text Searchable
Applies to: Phone, TextArea, TextField, URL
Specify whether or not the field should affect Global Search results.
- Disabled: Select "Disabled" if you do not want this field to be captured when the database is indexed for searches. Search indices collect the values of searchable fields for evaluation by the Global Search.
- Searchable: Select "Searchable" to include this field's value in search indexes.
- Selecting "Searchable" will reveal the Boost value field, which allows you to set a relevance weight for searches.
When a user's search query matches the value of a field with a higher boost level, the record will appear higher in the search results. For more information regarding boost values in Full-Text Search, please refer to the Search documentation in the Application Guide.
- Selecting "Searchable" will reveal the Boost value field, which allows you to set a relevance weight for searches.
Note: For a list of searchable fields for each module for global search, please refer to the Search documentation in the Application Guide.
Generate URL
Applies to: IFrame, URL
Select this checkbox to allow variables from the current module to be placed into the Default Value option for creating dynamic URLs.
- This is useful for providing links or Iframes to internal systems such as an ERP or to external systems such as Google Maps.
- Select the desired field to add from the dropdown and click "Insert Field" to add the field to the Default Value. When selecting this option, the field value cannot be modified by users.
Height
Applies to: Image
Enter the number of pixels to vertically scale the image for this field. Enter only the Width or Height options to retain the aspect ratio of the image.
Help Text
Applies to: All data types
Enter basic instructions for populating this field. The text entered here will display below the field when creating or editing a record for modules using the Sidecar user interface. For modules using the Legacy user interface, the help text will appear when users hover their mouse within the field in the Edit View layout.
HTML
Applies to: HTML
Enter static rich text with formatting or HTML code to display on a record. For more information on how to use the text editor please refer to the TinyMCE section of the User Interface documentation in the Application Guide.
IFrame Height
Applies to: IFrame
Enter the number of pixels for the height of the IFrame field. The width of the IFrame field is always the width of the field container.
Importable: Select one of the following options to determine the field's functionality when records are being imported:
- Yes: The field can be included in an import operation.
- No: The field cannot be included in an import.
- Required: A value for the field must be provided in any import.
Label Value
Applies to: Flex Relate
Enter a value to display as the field label and header in layouts. This value is also modifiable in the Modules panel under Labels. Defaults to "Flex Relate".
Make Visible for Calculations
Applies to: Checkbox, Currency, Date, Datetime, Decimal, Encrypt, DropDown, Float, Integer, MultiSelect, Phone, Radio, TextArea, URL, TextField
Select this checkbox to make the field available for use in the currentUserField()
Sugar Logic function. For more information and an example use case, refer to the Calculated Field - Setting Field Conditions Based on User Attributes knowledge base article.
Note: This field option is only available in the Users module.
Mass Update
Applies to: Checkbox, Date, Datetime, Decimal, DropDown, Encrypt, Float, IFrame, Integer, MultiSelect, Phone, Radio, Relate, Text, URL
Select this checkbox to add this field as an option to mass update.
Note: It is not possible to mass update a relate field based on a one-to-one relationship because doing so would invalidate the one-to-one relationship.
Max Size
Applies to: Address, Decimal, Float, IFrame, Integer, Phone, URL, TextField
Enter the maximum number of characters (or, for DB2 databases, the maximum number of bytes) allowed for this field. Defaults to 255.
Max Value
Applies to: Integer
Enter the highest value allowable for this field. If a user enters a higher value in the field than the specified value, a notification will appear upon save informing them of the set maximum value.
Note: Integer fields are limited at the database level to values up through 2147483647.
Min Value
Applies to: Integer
Enter the lowest value allowable for this field. If a user enters a value in the field that is lower than the specified value, a notification will appear upon save informing them of the set minimum value.
Module
Applies to: Relate
Select a module from the dropdown to relate to the current module. A module can relate back to itself, a good example of this would be a relate field on Contacts to relate back to Contacts for a referred by field. This will allow users to select which contact record referred a different contact. The chosen module cannot be modified once the field is created.
Open Link In
Applies to: URL
Select one of the following options to determine how a URL will open:
- New Window: Opens the URL in a new Tab or Window depending on your browser and settings.
- Same Window: Opens the URL in the same window as the record you are currently browsing.
Parent Dropdown
Applies to: All data types except ActionButton and Address
When the Dependent option has "Parent Dropdown" selected, choose an option from the dropdown to specify the parent that controls the visibility of this dropdown field. The Parent Dropdown option is populated with the other dropdown data type fields in the current module.
Click "Edit Visibility" to specify which options are available from the current dropdown for each value of the parent dropdown. In the Visibility Editor window, drag values from the current dropdown list to the value sections of the parent dropdown. This will determine which options in the dropdown list are available when the parent dropdown is set to the specified value. In this example, if the parent dropdown is set to "Apparel", then the current dropdown will have options 1, 2, and 3 where if the parent dropdown is set to "Banking", then the current dropdown will only have options 2 and 3 available. If there are no available options for a parent dropdown value, then the dependent dropdown will not display. To remove an item from the list, simply click and drag the value to the Trash bin on the left. Once the values are set, click "Save" to preserve your changes.
Precision
Applies to: Decimal, Float
Enter a number to specify the number of digits to the right of the decimal point the value should be stored as in Sugar.
Read-Only Field
Applies to: All field types excluding ActionButton, AutoIncrement, Currency, GeocodeStatus, and Image when the Mass Update option is disabled.
Select this checkbox to mark the field as read-only in Sugar. The user will not be able to enter a value for the field when editing the record.
Read-Only If
Applies to: HTML, TextArea when the Read-Only Field option is selected.
The "Read-Only If" option allows you to use Sugar Logic to define criteria that determine when the field should be read-only on the layout.
- If left blank, the field will always be read-only.
- To make it read-only conditionally, click "Edit Formula" to launch the formula builder. For more information on how to build a formula using the formula builder, please refer to the Using Sugar Logic documentation.
Reportable
Applies to: All data type fields except Encrypt, Flex Relate, HTML, IFrame, and Image
Select this checkbox to allow the field to be used in reports.
Required Field
Applies to: All data type fields except ActionButton, Checkbox, and HTML
Select this checkbox to mark the field as required in Sugar. The user will be required to enter a value for the field when saving the record.
Note: This field option is not available for the out-of-the-box Account Name field on the Contacts, Opportunities, Revenue Line Items, Leads, Quotes, Quoted Line Items, Cases, and Purchases modules. Instead, this can be controlled using the require_accounts
setting in the config_override.php
. See the Core Settings page in the Developer Guide for more details.
Required If
Applies to: All data type fields except ActionButton, Checkbox, and HTML when the Required Field option is selected.
The Required If option defines the criteria that determine when the field is required on the layout.
- If left blank, the field will always be required.
- To make it required conditionally, click "Edit Formula" to launch the formula builder. For more information on how to build a formula using the formula builder, please refer to the Using Sugar Logic documentation.
Rows
Applies to: TextArea
Enter the number of rows to specify the height of a TextArea data type field.
System Label
Applies to: All data types
Enter the system value for storing the label of the field. This is defaulted to the name of the field preceded with "LBL_". Any lowercase characters entered will be converted to an uppercase upon saving. Once the field has been created, the system label cannot be changed. It is recommended that administrators avoid naming fields with the same system label in order to prevent the same label and header values from existing in the system.
Note: Only single-byte characters are supported for system labels for fields.
Visible If
Applies to: All data types except ActionButton and Address when the Dependent option is selected or "Formula" is selected from the Dependent option dropdown.
Contains the current formula to determine if a field is visible on the layout or not. Click "Edit Formula" to launch the formula builder to change the formula.
The formula must result in a Boolean (true/false) response. For more information on how to build a formula using the formula builder, please refer to the Using Sugar Logic documentation.
Width
Applies to: Image
Enter the number of pixels to horizontally scale the image for this field. Enter only the Width or Height options to retain the aspect ratio of the image.
Creating Fields
Use the following steps to create a new field via Studio:
- Expand out the tree under the desired module (e.g., Cases) in the Modules panel and select "Fields".
- In the main panel, click "Add Field".
- Enter appropriate values for the Field Options.
Note: For ActionButton type fields, click "Configure Buttons" at the bottom of the field definitions, and then proceed with the configuration steps on the Action Buttons page. - Once the necessary information is entered, click "Save".
Please note that once a field is created, it must be placed on the record view (for Sidecar modules) or edit view (for Legacy modules) layout before users can enter data into that field. For more information on editing layouts, please refer to the Editing Layouts documentation.
Note: New fields cannot be created if you have reached the MySQL row size limit of the table in your database. For more information, please refer to the Troubleshooting Row Size Limit Errors in Sugar article.
Editing Fields
Use the following steps to edit an existing field via Studio:
- Expand out the tree under the desired module (e.g., Cases) in the Modules panel and select "Fields".
- In the main panel, select a field to edit. Sorting the fields by the column header will help in locating the field faster.
- Note: Fields created via Studio will display an asterisk next to their names.
- Enter appropriate values for the Field Options.
- Once the necessary information is entered, click "Save".
Deleting Fields
Use the following steps to delete an existing field via Studio:
- Expand out the tree under the desired module (e.g., Cases) in the Modules panel and select "Fields".
- In the main panel, select a field to delete. Sorting the fields by the column header will help in locating the field faster.
- Fields created via Studio will display an asterisk (*) next to their names.
- Note: Stock fields cannot be deleted.
- Click "Delete" to remove the field.
- A pop-up message will display asking for confirmation. Click "Ok" to proceed.
- When deleting fields, both the field and all the data related to the field in the database will be permanently removed. Before deleting a field, confirm that the field is no longer used or displayed in the following places:
- Report filters or display columns
- Workflows that filter by or display the field
- Dashlets that filter by or display the field
- Sugar Logic formulas for other fields
- Email templates
- Saved searches (legacy modules)
- When deleting fields, both the field and all the data related to the field in the database will be permanently removed. Before deleting a field, confirm that the field is no longer used or displayed in the following places:
- The field will automatically be removed from any module layouts when deleted.
Cloning Fields
Use the following steps to clone an existing field via Studio:
- Expand out the tree under the desired module (e.g., Cases) in the Modules panel and select "Fields".
- In the main panel, select a field to clone. Sorting the fields by the column header will help in locating the field faster.
- Note: Fields created via Studio will display an asterisk (*) next to their names.
- Select "Clone" to duplicate the field.
- Note: Some non-standard stock fields (e.g., Name) do not have the ability to clone.
- Enter appropriate values for the Field Options.
- Once the necessary information is entered, click "Save".