Creating And Editing Entities

Administrators can create and edit Entities that will record data in database tables. Entities serve as the foundation for storing and managing information within the Magentrix platform, allowing administrators to create custom applications and data structures tailored to their organization's needs.

Before You Begin

Requirements

To create and edit Entities, users must be assigned a security role with the following permissions:

Administrator System Role

Understanding Entity Types

When creating a new entity, administrators must choose between two entity types. This choice determines the default fields and behavior of the entity.

Object Entities

Object Entities are database tables that can be customized to record any type of data. Save and retrieve data related to things such as Accounts, invoices, etc. Object Entities can also be used by developers to create and manage custom applications for a portal. Examples include Accounts, Opportunities, Cases, and custom objects like Projects or Inventory Items.

When creating an Object Entity, the Name field can be configured as either a Text field or an Auto-Number field.

Person Entities

Person Entities are database tables that record data directly related to a person such as location and contact information. Save and retrieve data related to a person such as Candidates, Volunteers, etc. Person Entities automatically include First Name and Last Name as separate fields upon creation. The Name field for Person Entities is read-only and displays as a combination of First Name and Last Name.

Understanding Entity Options

When creating or editing entities, administrators can configure several options that control entity behavior:

Track Activities

Enabling Track Activities allows Task and Event related objects to be associated with records in this entity. When enabled, users can log calls, schedule meetings, create tasks, and track other activities related to entity records. This provides a complete activity history for each record.

Allow Reports

Enabling Allow Reports allows the entity to participate in the Magentrix Reporting System. When enabled, users can create reports and dashboards that include data from this entity, enabling analytics and data visualization. Entities must have this option enabled to appear as data sources in the report builder.

Track Feeds

Enabling Track Feeds enables Mingel social collaboration for the entity. When enabled, users can follow records, post updates, share files, and collaborate on entity records through the Mingel feed functionality. This creates a social collaboration layer on top of the entity data.

Understanding Entity Schemas

Entities in Magentrix can have different schema types depending on their origin:

Native Magentrix Entities (Standard Schema)

Native Magentrix entities use the "standard" schema and are created and managed entirely within the Magentrix platform. Administrators have full control over all aspects of these entities, including field creation, validation rules, page layouts, buttons, list layouts, and all other configurations.

Salesforce Objects (Force Schema)

Salesforce objects use the "Force" schema and are imported from Salesforce through Extend > Salesforce. These entities synchronize bidirectionally with Salesforce, meaning data changes in either system are reflected in the other. The field schema for Salesforce objects is defined in Salesforce, and administrators must manage fields in Salesforce and then refresh the entity in Magentrix to update the field schema. However, page layouts, validation rules, buttons, and list layouts for Salesforce objects are all managed within Magentrix.

Microsoft Dynamics Entities (DynamicsCrm Schema)

Microsoft Dynamics entities use the "DynamicsCrm" schema and are imported from Microsoft Dynamics CRM through Extend > Dynamics CRM. They function similarly to Salesforce objects and synchronize bidirectionally. The field schema for Dynamics entities is defined in Dynamics CRM, and administrators must manage fields in Dynamics CRM and then refresh the entity in Magentrix to update the field schema. However, page layouts, validation rules, buttons, and list layouts for Dynamics entities are all managed within Magentrix.

Understanding Key Prefix and Magentrix IDs

Every entity in Magentrix is assigned a Key Prefix, which is an auto-generated three-digit identifier such as "001", "002", or "003". The Key Prefix becomes part of the Magentrix ID for every record in that entity.

A Magentrix ID is a 19-character base-62 number that is case-sensitive. The structure is:

First 3 digits: Key Prefix (identifies the entity)
Middle digits: Sequential base-62 number (unique record identifier)
Last 4 digits: Unique Organization ID for the specific client

This structure ensures that every record across all entities has a globally unique identifier within the Magentrix platform. Administrators cannot customize the Key Prefix, as it is automatically generated during entity creation.

Creating a New Native Magentrix Entity

To create a native Magentrix entity:

In the Setup Home page, click Create > Entities.
Click New.
Select the Entity type you want to create:
- Object: Save and retrieve data related to things such as Accounts, invoices, etc.
- Person: Save and retrieve data related to a person such as Candidates, Volunteers, etc.
Click Next.
Complete the following fields:
- Label: Enter a label for the entity (singular form, e.g., "Project").
- Plural Label: Enter the plural form of the label (e.g., "Projects").
- Entity Name: This field is automatically populated based on the Label. The Entity Name is used when referencing the entity via the API.
- Description: Enter a description of the entity's purpose (optional but recommended).
In the Record Name Label and Format section, configure the Name field:
- For Object Entities: Choose between Text or Auto-Number format (see below for details).
- For Person Entities: The Name field is automatically configured as a combination of First Name and Last Name (read-only).
Configure entity options by checking the desired checkboxes:
- Track Activities: Enable to allow Task and Event tracking on this entity.
- Allow Reports: Enable to include this entity in the Reporting System.
- Track Feeds: Enable to allow Mingel collaboration on this entity.
Click Save.

The Entity has been created with default fields and settings. Administrators can proceed to customize fields, page layouts, buttons, list layouts, validation rules, sharing filters, and record types.

Configuring Record Name for Object Entities

For Object Entities, administrators can configure the Name field using one of two options:

Text Field Option

When selecting Text as the Data Type:

In the Record Name Label field, enter the label that will be displayed for the Name field (e.g., "Project Name", "Case Number").
The Name field will be a text field with a maximum length of 120 characters.
The Name field is always required and users must enter a value when creating records.
Users can click on the Name field value to navigate to the record's detail page.

Auto-Number Field Option

When selecting Auto Number as the Data Type:

In the Record Name Label field, enter the label that will be displayed for the Name field (e.g., "Case Number", "Invoice Number").
In the Display Format field, enter the format for the auto-number. Use {0} as a placeholder for the number portion. For example:
- ABC-{0:0000} will display as ABC-0001, ABC-0002, ABC-0003, etc.
- INV-{0:000000} will display as INV-000001, INV-000002, etc.
- The format before {0} is a fixed prefix, and the format inside {0:} determines the number of digits with leading zeros.
In the Starting Number field, enter the starting number for the sequence (defaults to 1).
In the Increment By field, enter the increment value (defaults to 1).
The auto-number will be automatically generated when records are created.
Users can click on the auto-number value to navigate to the record's detail page.

Configuring Record Name for Person Entities

For Person Entities, the Name field is automatically configured and cannot be changed:

Two separate fields are created: First Name and Last Name.
The Name field is read-only and displays as the combination of First Name and Last Name.
Users enter values in the First Name and Last Name fields separately.
The Name field automatically concatenates these values for display purposes.
Users can click on the Name field value to navigate to the record's detail page.

Editing Entity Properties

To edit entity properties:

In the Setup Home page, click Create > Entities.
Click the Entity you want to configure.
Click Edit.
Update the desired fields:
- Label
- Plural Label
- Description
- Track Activities
- Allow Reports
- Track Feeds
Click Save.

Note: You cannot change the Entity Name, Entity Type (Object or Person), or Record Name configuration after the entity has been created. You also cannot change the Schema type or Key Prefix.

Creating Read Only Entities (Salesforce/Dynamics)

The Read Only checkbox is available when importing Salesforce or Microsoft Dynamics entities and serves a specific purpose for handling required lookup dependencies.

When to Use Read Only Entities

In some cases, a Salesforce or Dynamics object may have a required lookup field to another object that does not exist in Magentrix. For example:

A Quote Line Item object has a required lookup to an Asset object.
The Asset object does not exist in Magentrix.
If Quote Line Item is imported without the Asset object, users cannot create records because the required field cannot be populated.

To address this scenario, administrators can import the dependent object (in this case, Quote Line Item) as a Read Only entity.

Creating a Read Only Entity

To create a Read Only entity when importing from Salesforce or Dynamics:

Navigate to Extend > Salesforce (or Extend > Dynamics CRM).
Select the object you want to import.
During the import process, check the Read Only checkbox in the Additional Information section.
Complete the import process.

When an entity is marked as Read Only:

Records cannot be created in Magentrix.
Records cannot be edited in Magentrix.
Records cannot be deleted in Magentrix.
Existing records synchronized from Salesforce or Dynamics can be viewed.
The entity can be used in lookups, reports, and related lists.

This allows administrators to import objects with complex dependencies while maintaining data integrity. Records must be created and managed in the source system (Salesforce or Dynamics).

Best Practices and Recommendations

Plan entity structure carefully: Before creating entities, plan the fields, relationships, and business logic you will need. Changing the entity type or Name field configuration is not possible after creation.
Use descriptive labels: Choose clear, descriptive labels that users will understand. The Label is what users see throughout the interface.
Enable entity options appropriately: Only enable Track Activities, Allow Reports, and Track Feeds if you will actually use these features. Unnecessary options can clutter the interface.
Use Auto-Number fields strategically: Auto-Number fields are ideal for cases, tickets, invoices, and other records that benefit from sequential numbering. Use a meaningful prefix in the Display Format.
Document entity purpose: Always add a description when creating entities. This helps other administrators understand the entity's purpose.
Consider Person vs Object carefully: Use Person entities only for individuals (contacts, leads, candidates). Use Object entities for all other data types.
Import external entities selectively: Only import Salesforce or Dynamics objects that you actually need in your portal. Each imported entity adds complexity to your data model.
Use Read Only entities sparingly: Only use Read Only entities when absolutely necessary to resolve lookup dependencies. They should not be the default approach.

Troubleshooting Tips

Issue: Cannot change Entity Type after creation.

Solution: Entity Type (Object or Person) cannot be changed once an entity is created. If you need a different type, you must create a new entity and migrate data if necessary.

Issue: Cannot change Record Name configuration after creation.

Solution: The Record Name Label and Format cannot be changed after the entity is created. Plan this carefully during entity creation.

Issue: Auto-Number sequence skips numbers.

Solution: This is expected behavior. Numbers may be skipped if record creation fails validation or if records are deleted. Auto-Number fields guarantee uniqueness but not a gap-free sequence.

Issue: Person Entity Name field is not showing First Name and Last Name.

Solution: The Name field for Person Entities automatically combines First Name and Last Name. Ensure both fields have values. The Name field itself is read-only and cannot be edited directly.

Issue: Cannot create records in imported Salesforce/Dynamics entity.

Solution: If the entity was imported as Read Only, records cannot be created in Magentrix. You must create records in Salesforce or Dynamics, and they will synchronize to Magentrix. If the entity should not be Read Only, you may need to reimport it without the Read Only option.

Issue: Fields not appearing after refreshing Salesforce/Dynamics entity.

Solution: Ensure the fields exist in Salesforce or Dynamics and that you have proper permissions to access them. Try refreshing the entity schema again from the entity detail page.

Issue: Track Activities not working after enabling.

Solution: After enabling Track Activities, ensure that users have the appropriate permissions to create and view Tasks and Events. Also ensure that the Activity related list has been added to the page layout.

Table of Contents