Master Detail Fields and Lookup Fields

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. Deletion of the child record will not affect the master record. However if the parent record is deleted, all related records including the child record will also be deleted.

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.

Before You Begin

Requirements

To create Master Detail fields, Lookup fields, and Lookup filters, users must be assigned a security role with the following permissions:

• Administrator System Role

Understanding Master Detail Fields

Master Detail fields create a tight parent-child relationship with several important characteristics:

Key Characteristics

• Cascade delete: When a parent record is deleted, all child records are automatically deleted
• Inherited ownership: The child record's Owner field is hidden, and ownership is inherited from the parent record
• Required relationship: Master Detail fields are always required; child records must have a parent
• Native entities only: Can only be created between native Magentrix entities (not Salesforce or Dynamics objects)
• Enables Rollup Summary: Parent entities can include Rollup Summary fields to aggregate child data

When to Use Master Detail Fields

Use Master Detail relationships when:

• Child records have no independent existence without the parent (e.g., Order Line Items without Orders)
• You need to aggregate child data on the parent using Rollup Summary fields
• Child records should always inherit parent record ownership and sharing
• Deleting the parent should automatically delete all children

Owner Field Behavior

When a Master Detail relationship is created:

1. The Owner field on the child entity is hidden (not deleted, but hidden from view)
2. Child record ownership is inherited from the parent record
3. If the Master Detail field is later deleted, the Owner field reappears with historical data preserved

Understanding Lookup Fields

Lookup fields create a flexible relationship between entities with different characteristics than Master Detail:

Key Characteristics

• Optional relationship: Lookup fields can be optional; records can exist without a related record
• Independent deletion: Deleting the parent record does not delete child records
• Independent ownership: Each record maintains its own Owner field
• Flexible relationships: Can reference Salesforce, Dynamics, or native Magentrix entities
• No Rollup Summary: Parent entities cannot use Rollup Summary fields for Lookup relationships

When to Use Lookup Fields

Use Lookup relationships when:

• The relationship is optional (e.g., not all Contacts need an Account)
• Child records should continue to exist if the parent is deleted
• You need to relate to Salesforce or Dynamics objects
• Child records need independent ownership from the parent
• The relationship might change over time

Creating a Master Detail Entity Field

To create a master detail entity field:

1. In the Setup Home page, click Create > Entities.

2. Click the entity which will be selected as the child entity.

3. Select the Fields tab and then click New.

4. Select Master Detail and then click Next Step.

5. Configure the field details:

   Label: Enter a label for the Master Detail field (e.g., "Order", "Project", "Account").

   Name: This field will be automatically populated based on the Label. The Name is used when referencing the field via the API.

6. In the Related To dropdown box, select the Parent Entity.

   Important: Do NOT select a Salesforce or Dynamics CRM object. Master Detail fields can only be created between native Magentrix entities.

7. In the Child Relationship Name field, enter a name for the Master Detail relationship. This name is used when referencing the related list of child records on the parent entity (e.g., "OrderLineItems", "ProjectTasks").

8. In the Options pane, configure the following:

   Required: Check if saving a record will always require a field value. Master Detail fields are typically required.

   Audited Field: Check if all changes to the field will be recorded in field history.

   Searchable: Check if you want the field to be searchable in global search.

9. If you would like to configure a filter, in the Filter Conditions pane, check the Use Filters checkbox.

10. Enter your filter logic. See Filters and Filter Logic for detailed instructions.

11. In the Error Message field, enter the error message that will be displayed to users if they attempt to save a record that doesn't meet the filter criteria.

12. Check the box beside Active if you want to activate the filter.

13. Click Save.

The Master Detail field is now created, and the child entity's Owner field has been hidden. A related list is automatically created on the parent entity showing all child records.

Creating a Lookup Field

To create a lookup field:

1. In the Setup Home page, click Create > Entities.

2. Click on the Entity to which you want to add the Lookup field.

3. Within the related list of fields for this entity, click New.

4. Select the Lookup field option then click Next Step.

5. Configure the field details:

   Label: Enter a label for the Lookup field (e.g., "Account", "Related Contact", "Product").

   Name: This field will be automatically populated based on the Label.

6. In the Related To dropdown box, select the entity that this Lookup field will reference. This can be a native Magentrix entity, Salesforce object, or Dynamics entity.

7. In the Child Relationship Name field, enter a name for the lookup relationship. This name is used when referencing the related list on the parent entity.

8. In the Options pane, configure the following:

   Required: Check if saving a record will always require a field value. Unlike Master Detail fields, Lookup fields can be optional.

   Audited Field: Check if all changes to the field will be recorded.

   Searchable: Check if you want the field to be searchable.

9. If you want to provide an icon offering information on hover, enter a help message in the Inline Help text field.

10. If you want to provide a description of the field, enter a description in the Description text field.

11. Click Save.

12. In the following screen, configure the field security by checking the Read and Edit boxes for security roles.

13. Click Save Changes.

The Lookup field is now created and can be added to page layouts.

Adding a Lookup Filter

Lookup filters restrict which records users can select in a Lookup field based on criteria you define. This ensures data integrity and improves the user experience by showing only relevant options.

Common Use Cases for Lookup Filters

Case-Contact Relationship:

• On the Case entity, ensure that the Contact selected belongs to the Account selected on the Case
• Filter: Contact.Account = Case.Account

Opportunity-Contact Relationship:

• On the Opportunity entity, ensure the Primary Contact belongs to the Opportunity's Account
• Filter: Contact.Account = Opportunity.Account

Territory-Based Filtering:

• On the Lead entity, only show Sales Reps assigned to the Lead's Territory
• Filter: User.Territory = Lead.Territory

Creating a Lookup Filter

To add a lookup filter:

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

2. Click the Entity in which you want to add a Lookup filter.

3. Click the Lookup Field in which you want to add a Lookup filter.

4. Click Edit.

5. Under Filter Conditions, check the Use Filters checkbox.

6. Enter your filters and filter logic:

   • Select the field on the lookup entity to filter by
   • Choose an operator (equals, not equals, greater than, etc.)
   • Enter a value or reference another field
   • Add multiple filters if needed
   • Enter filter logic to combine conditions (e.g., "1 AND 2", "(1 OR 2) AND 3")

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

8. Check the box beside Active if you want to activate the filter.

9. Click Save.

When active, the lookup filter will:

• Restrict available values in the lookup dialog to only those meeting the criteria
• Display an error message if users attempt to save with a value that doesn't meet the criteria
• Improve user experience by showing only relevant options

Understanding Lookup Dialog Behavior

When users interact with a Lookup field, they can search and select records through the Lookup Dialog:

How the Lookup Dialog Works

1. Type-ahead search: As users type in the Lookup field, a dropdown automatically appears with matching records
2. Magnifying glass icon: Users can click the magnifying glass icon to open the full Lookup Dialog
3. Filtered results: If the user has typed text, the dialog shows filtered results and the search bar is pre-populated
4. Default view: If no text is entered, the dialog shows the first 20 records based on the sort order defined in the Lookup Dialog list layout
5. Configured columns: The columns and sorting are controlled by the Lookup Dialog list layout configuration

The Lookup Dialog list layout can be customized to show specific columns, sort orders, and filter options relevant to the lookup relationship.

Master Detail vs Lookup Comparison

Practical Examples

Example 1: Order and Line Items (Master Detail)

Scenario: Create Order Line Items that belong to Orders.

Configuration:

• Child Entity: Order Line Item
• Field: Order (Master Detail)
• Related To: Order
• Required: Checked
• Behavior: Deleting an Order deletes all its Line Items

Result: Line Items cannot exist without an Order, and ownership is inherited from the Order.

Example 2: Contact and Account (Lookup)

Scenario: Associate Contacts with Accounts, but allow Contacts without Accounts.

Configuration:

• Entity: Contact
• Field: Account (Lookup)
• Related To: Account
• Required: Unchecked
• Behavior: Deleting an Account does not delete Contacts

Result: Contacts can exist independently and have their own owners.

Example 3: Case with Filtered Contact (Lookup with Filter)

Scenario: On Cases, only allow selecting Contacts that belong to the Case's Account.

Configuration:

• Entity: Case
• Field: Contact (Lookup)
• Related To: Contact
• Filter: Contact.Account = Case.Account
• Error Message: "Contact must belong to the selected Account"

Result: Users can only select Contacts from the same Account, ensuring data integrity.

Example 4: Project Tasks (Master Detail with Rollup)

Scenario: Track tasks under projects and calculate total hours.

Configuration:

• Child Entity: Task
• Field: Project (Master Detail)
• Related To: Project
• Parent Rollup: Total Hours (Sum of Task.Hours)

Result: Projects show the total hours across all tasks automatically.

Best Practices and Recommendations

• Choose relationship type carefully: Consider whether child records should exist independently before choosing Master Detail or Lookup.
• Plan for deletion: Understand that Master Detail cascades deletes, which is permanent and cannot be undone.
• Use Lookup filters proactively: Implement filters to maintain data integrity and improve user experience.
• Test error messages: Ensure lookup filter error messages are clear and helpful to users.
• Consider Salesforce/Dynamics objects: Remember that Master Detail cannot reference external objects; use Lookup instead.
• Document relationships: Add descriptions to relationship fields explaining the purpose and any filtering logic.
• Leverage Rollup Summary: Take advantage of automatic aggregation on Master Detail parent entities.
• Configure Lookup Dialog layout: Customize the Lookup Dialog list layout with relevant columns for easier selection.
• Use required appropriately: Make Master Detail fields required (typical), but consider if Lookup fields should be optional.
• Test with various scenarios: Test relationship behavior with creation, updates, and deletions.

Troubleshooting Tips

Issue: Cannot create Master Detail field to Salesforce object.

Solution: Master Detail fields can only be created between native Magentrix entities. Use a Lookup field instead to reference Salesforce or Dynamics objects.

Issue: Owner field disappeared on child entity.

Solution: This is expected behavior when a Master Detail relationship is created. Ownership is inherited from the parent. If you delete the Master Detail field, the Owner field will reappear.

Issue: Child records were deleted when parent was deleted.

Solution: This is expected behavior for Master Detail relationships. Deleting the parent cascades to all children. If you need children to survive parent deletion, use a Lookup field instead.

Issue: Cannot create Rollup Summary field on parent entity.

Solution: Rollup Summary fields require a Master Detail relationship, not Lookup. If you have a Lookup relationship, you cannot use Rollup Summary fields.

Issue: Lookup filter not working as expected.

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

Issue: Lookup Dialog showing wrong records.

Solution: Check the Lookup Dialog list layout configuration to ensure the correct columns, sorting, and filters are configured.

Issue: Error message "Filter conditions not met" when saving.

Solution: The selected lookup value doesn't meet the filter criteria. Review the filter conditions and select a value that matches the criteria, or adjust the filter if it's too restrictive.

Issue: Cannot make Master Detail field optional.

Solution: Master Detail fields are always required by design. If you need an optional relationship, use a Lookup field instead.

Issue: Lookup field showing too many records in dropdown.

Solution: Configure a Lookup filter to restrict the available records, or customize the Lookup Dialog list layout to improve the display.

Issue: Users cannot see child records in related list.

Solution: Verify that users have read permissions on the child entity and that the related list has been added to the parent entity's page layout.

See Also

• Managing Entity Fields
• Custom Entity Fields Overview
• Rollup Summary Fields
• Configuring Magentrix Entity Picklists
• Designing Page Layouts
• Filters and Filter Logic

Jump to Magentrix Entity Checklist

<< Rollup Summary Fields | Configuring Magentrix Entity Picklists >>