Managing Entity Fields

Upon creation, Entities have a standard set of fields. Administrators can further customize Entities by adding additional fields of various types including text, number, date, picklist, lookup, master-detail, formula, and rollup summary fields. Fields are the fundamental building blocks that define what data an entity can store.

Before You Begin

Requirements

To add fields to Entities, users must be assigned a security role with the following permissions:

Administrator System Role

Understanding Default Fields

When a new entity is created, Magentrix automatically creates several standard fields that are present on all entities:

Standard Fields for All Entities

Name: The primary identifier field for the entity. For Object entities, this can be configured as a Text field or Auto-Number field. For Person entities, this is a read-only combination of First Name and Last Name.
Owner: The user who owns the record. This field determines record-level access based on sharing settings and permissions.
Created By: The user who created the record (automatically populated).
Created Date: The date and time when the record was created (automatically populated).
Modified By: The user who last modified the record (automatically updated).
Modified Date: The date and time when the record was last modified (automatically updated).

Additional Fields for Person Entities

For Person entities, two additional fields are automatically created:

First Name: Text field for the person's first name.
Last Name: Text field for the person's last name.

These fields are used to populate the read-only Name field.

Owner Field Behavior with Master-Detail Relationships

When a Master-Detail relationship is created for an entity, the Owner field behavior changes:

The Owner field is hidden from the child entity (it is not deleted, just hidden).
The child record's ownership is inherited from the parent record.
If the Master-Detail field is later deleted, the Owner field reappears with historical data preserved.

This ensures that child records follow the same ownership and sharing rules as their parent records.

Understanding Field Types

Magentrix supports a comprehensive set of field types for storing different kinds of data. Each field type is optimized for specific data and use cases.

Text and Long Text Fields

Text: Allows users to enter any combination of letters and numbers. Maximum length of 255 characters.
TextArea: Allows users to enter up to 65,000 characters on separate lines. Rich-text formatting is available.

Numeric Fields

Number: Allows users to enter any number. Leading zeros are removed.
Currency: Allows users to enter a dollar or other currency amount and automatically formats the field as a currency amount.
Percent: Allows users to enter a percentage number (for example, '10') and automatically adds the percent sign to the number.

Date and Time Fields

Date: Allows users to enter a date or pick a date from a popup calendar.
DateTime: Allows users to enter a date and time, or pick a date from a popup calendar. When users click a date in the popup, that date and the current time are entered into the Date/Time field.
Time: Allows users to select a time span value without its date portion.

Selection Fields

Checkbox: Allows users to select a True (checked) or False (unchecked) value.
Picklist: Allows users to select a single value from a list you define.
Multi-Select Picklist: Allows users to select multiple values from a list you define.
Global Picklist: Allows users to select a value from a pre-defined global list of values.

Contact and Reference Fields

Email: Allows users to enter an email address, which is validated to ensure proper format. If this field is specified for a contact or lead, users can choose the address when clicking Send an Email. Note that custom email addresses cannot be used for mass emails.
Phone: Allows users to enter any phone number. Automatically formats it as a phone number.
URL: Allows users to enter any valid website address. When users click on the field, the URL will open in a separate browser window.

Relationship Fields

Lookup: Creates a relationship that links this entity to another entity. The relationship field allows users to click on a lookup icon to select a value from a popup list. The other object is the source of the values in the list.
Master Detail: Creates a special type of parent-child relationship between this entity (the child, or "detail") and another entity (the parent, or "master").

Calculated Fields

Formula: A read-only field that derives its value from a formula expression you define. The formula field is updated when any of the source fields change.
Rollup Summary: A read-only field that displays the sum, minimum, or maximum value of a field in a related list or the record count of all records listed in a related list.
Auto Number: A system-generated sequence number that uses a display format you define. The number is automatically incremented for each new record.

Security Field

Password: Masked text field for storing secure information.

Understanding Field Properties

When creating or editing fields, administrators can configure several properties that control field behavior:

Required Fields

Checking the Required checkbox ensures that saving a record will always require a field value. Users cannot save a record without providing a value for required fields. Required fields are indicated with a red asterisk in the user interface.

Audited Fields

Checking the Audited Field checkbox enables field-level history tracking. All changes to the field value are recorded with the user who made the change and the timestamp. Audited field history can be viewed by adding the Entity History related list to the page layout.

Searchable Fields

Checking the Searchable checkbox makes the field searchable in global search. By default, only the Name field is searchable. Enabling this option for additional fields improves the ability to find specific records through search functionality.

Creating Custom Fields

To add fields to entities:

In the Setup Home page, click Create > Entities.
Click the Entity to which you want to add fields.
Select the Fields tab.
Click New.
Select a data type for the field and then click Next Step.
Configure the field details based on the selected field type:
- Label: Enter a label for the field (this is what users see).
- Name: This field is automatically populated based on the Label. The Name is used when referencing the field via the API.
- Length (for Text fields): Specify the maximum number of characters.
- Decimal Places (for Number, Currency, Percent): Specify the number of decimal places.
- Values (for Picklist fields): Enter the list of values, one per line.
- Related To (for Lookup and Master-Detail): Select the parent entity.
- Formula (for Formula fields): Enter the formula expression.
- Description: Enter a description of the field's purpose (optional but recommended).
- Inline Help: Enter help text that appears when users hover over the field's info icon.
Configure field options:
- Check Required if the field must have a value.
- Check Audited Field to enable field history tracking.
- Check Searchable to include the field in global search.
Click Save.
In the following screen, configure the field security by checking the Read and Edit boxes for security roles.
Click Save Changes.

The field is now available and can be added to page layouts for user access.

Editing Field Properties

To edit entity fields:

In the Setup Home page, click Create > Entities.
Click the Entity that contains the field you want to edit.
Select the Fields tab.
Click the field you want to edit.
Click Edit.
Configure the field properties as needed.
Click Save.

Note: Some properties cannot be changed after a field is created, such as the field type and the Name. You also cannot change the Related To entity for Lookup or Master-Detail fields once the field is created.

Understanding Master-Detail Relationships and Owner Field Behavior

Master-Detail fields create a special parent-child relationship between entities with specific ownership and deletion behavior.

Creating a Master-Detail Relationship

A Master-Detail field creates a special type of parent-child relationship between this entity (the child, or "detail") and another entity (the parent, or "master"). The Master-Detail field allows users with security permissions for seeing the master entity to also see the child entity. Administrators must still assign users read and edit access to the child entity.

Important Notes:

Deletion of the child record will not affect the master record.
If the parent record is deleted, all related records including the child record will also be deleted.
Master-Detail fields can only be created for native Magentrix entities. Salesforce and Dynamics CRM objects should not be selected as the parent entity.

Owner Field Behavior

When a Master-Detail relationship is created:

The Owner field on the child entity is hidden (not deleted, but hidden from view).
The child record's ownership is inherited from the parent record.
If a user has access to the parent record, they inherit the same access to child records based on the child entity's permission settings.
If the Master-Detail field is later deleted, the Owner field reappears with all historical ownership data preserved.

This inheritance ensures that access to child records follows the same rules as access to parent records, simplifying security management.

Configuring Lookup Field Filters

The Lookup field type allows users to populate a field with record values from another Entity. For example, Lookup Field X in Entity A can select values from Field Y in Entity B. Administrators can specify and limit the record values that can be selected with Lookup filters based on criteria such as related field values.

Use Case for Lookup Filters

A common use case for lookup filters is ensuring data relationships are maintained. For example:

On the Case entity, you have an Account lookup field and a Contact lookup field.
You want to ensure that the Contact selected must belong to the Account selected.
You can create a lookup filter on the Contact field that filters based on the Account field.

This ensures data integrity by preventing users from selecting Contacts that don't belong to the selected Account.

Creating a Lookup Filter

To add a lookup filter:

In the Setup Home page:
- If you want to add a Lookup Filter to a Magentrix Entity, click Create > Entities.
- If you want to add a Lookup Filter to a Salesforce Entity/Object, click Extend > Salesforce.
Click the Entity in which you want to add a Lookup filter.
Click the Lookup Field in which you want to add a Lookup filter.
Click Edit.
Under Filter Conditions, check the Use Filters checkbox.
Enter your filters and filter logic. See Filters and Filter Logic for detailed instructions.
In the Error Message field, enter a custom error message that will be displayed if the user selects a value that doesn't meet the filter criteria.
Check the box beside Active if you want to activate the filter.
Click Save.

When active, the lookup filter will restrict the available values in the lookup dialog and will display an error if users attempt to save a record with a value that doesn't meet the criteria.

Understanding Dependent Picklists (Salesforce Only)

For Salesforce Objects imported into Magentrix, dependent picklists are supported. Dependent picklists allow the values in one picklist to be filtered based on the value selected in another picklist (the controlling field).

Important: Native Magentrix entities do not support dependent picklists. This feature is only available for Salesforce objects that have dependent picklists configured in Salesforce.

How Dependent Picklists Work

When a Salesforce object with dependent picklists is imported into Magentrix:

The dependent picklist relationship is preserved.
When a user selects a value in the controlling picklist, the dependent picklist values are automatically filtered.
The dependent picklist configuration is managed in Salesforce and synchronized to Magentrix.

To configure or modify dependent picklist relationships, you must do so in Salesforce and then refresh the entity schema in Magentrix.

Enabling Field History Tracking

Field history tracking provides a complete audit trail of changes made to important fields.

Configuring Audited Fields

To enable field history tracking:

When creating or editing a field, check the Audited Field checkbox.
Click Save.
Configure field security to allow appropriate users to read and edit the field.
Click Save Changes.

Viewing Field History

To view field history for audited fields:

Navigate to the page layout for the entity.
Drag the [Entity Name] History related list from the Related Lists section onto the page layout.
Configure the related list to display the desired columns (Field, Old Value, New Value, Changed By, Change Date).
Save the page layout.

Users can now view the complete change history for all audited fields on the record detail page. Each change shows:

Which field was changed
The old value
The new value
Who made the change
When the change was made

Managing Fields for Salesforce and Dynamics Entities

When working with Salesforce or Microsoft Dynamics entities, field management follows a different process:

Field Management Process

Create or modify fields in Salesforce or Dynamics CRM: All field changes must be made in the source system using the native tools.
Refresh the entity schema in Magentrix:
- Navigate to Extend > Salesforce (or Extend > Dynamics CRM).
- Click the entity you want to refresh.
- Click the refresh option to update the field schema.
Configure field properties in Magentrix: After refreshing, you can configure field security, add fields to page layouts, and set other Magentrix-specific properties.

What Can Be Managed in Magentrix

For Salesforce and Dynamics entities, the following can be managed in Magentrix:

Field security (read/edit permissions by role)
Field placement on page layouts
Field visibility formulas on page layouts
Including fields in list layouts
Including fields in validation rules
Making fields searchable

What Must Be Managed in the Source System

The following must be managed in Salesforce or Dynamics:

Creating new fields
Deleting fields
Changing field types
Changing field properties (length, decimal places, picklist values, etc.)
Creating field dependencies (dependent picklists)

Best Practices and Recommendations

Plan field structure carefully: Before creating fields, consider how they will be used, what validations are needed, and how they relate to other fields.
Use descriptive field labels: Choose clear, descriptive labels that users will understand. Avoid technical jargon unless your users are technical.
Add field descriptions: Always add descriptions and inline help text to help users understand the field's purpose and expected values.
Use appropriate field types: Choose the most specific field type for your data. Use Currency for money, Date for dates, etc. Don't use Text fields for everything.
Enable Audited Field selectively: Only enable field history tracking on fields where you need an audit trail. Tracking all fields can create unnecessary data volume.
Make strategic fields searchable: Enable searchable on fields that users commonly search for, but don't enable it on all fields as this can impact search performance.
Use Lookup filters proactively: Implement lookup filters to maintain data integrity and improve user experience by showing only relevant options.
Consider field security: Not all users need to see or edit all fields. Use field-level security to control access to sensitive information.
Test Master-Detail relationships carefully: Understand that deleting a parent record will delete all child records. This is permanent and cannot be undone.
Document custom fields: Maintain documentation of custom fields, especially complex formulas and their business logic.

Troubleshooting Tips

Issue: Cannot change field type after creation.

Solution: Field types cannot be changed once a field is created. If you need a different field type, you must create a new field and migrate data if necessary.

Issue: Lookup filter not working as expected.

Solution: Verify that the filter logic is correct and that the Active checkbox is checked. Test the filter by creating or editing a record and attempting to select values that should be filtered out.

Issue: Field history not appearing on detail page.

Solution: Ensure that the Audited Field checkbox is enabled for the field and that the Entity History related list has been added to the page layout. Changes are only tracked after the field is marked as audited.

Issue: Cannot add field to page layout.

Solution: Verify that you have saved the field and configured field security. Fields must have at least Read permission for the current user's role to appear on the page layout.

Issue: Master-Detail field causing validation errors.

Solution: Ensure that the parent entity exists and that users have permission to view parent records. Also verify that the Master-Detail field is not required if users need to create records without a parent.

Issue: Owner field disappeared after creating Master-Detail relationship.

Solution: This is expected behavior. When a Master-Detail relationship exists, the Owner field is hidden because ownership is inherited from the parent record. If you delete the Master-Detail field, the Owner field will reappear.

Issue: Cannot create Master-Detail to Salesforce object.

Solution: Master-Detail fields can only be created between native Magentrix entities. You cannot create a Master-Detail relationship where the parent is a Salesforce or Dynamics object. Use a Lookup field instead.

Issue: Dependent picklist not working for imported Salesforce object.

Solution: Verify that the dependent picklist is properly configured in Salesforce. Refresh the entity schema in Magentrix to ensure the latest configuration is synchronized.

Issue: Field changes in Salesforce not appearing in Magentrix.

Solution: After making field changes in Salesforce, you must refresh the entity schema in Magentrix. Navigate to the entity under Extend > Salesforce and perform a schema refresh.

Table of Contents