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 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.

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: All field types excluding ActionButton, AutoIncrement, Currency, GeocodeStatus, and Image 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)
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".