Record Display Names, Record IDs, and Primary Fields in Data Entities

There are 3 important field types in an entity that have similar names and functions, and can thus be confusing to Data Entities users:

  • Record Display Name
  • Record ID
  • Primary Field

This confusion increases when these fields are sometimes referred to informally by names that sound similar. For example, some or all of these fields are sometimes referred to informally and interchangeably as primary key, primary key field, ID, record ID, or record name. This topic explains the technical differences between these field types, and how to use each one correctly.

Prerequisites

Record Display Names in Standard Entities

A Record Display Name (sometimes called the primary key field) is a required field in each record in an entity that uniquely identifies the record.

In standard (out-of-the-box) entities, the Record Display Name is pre-defined. For example, in the Application User entity, ApplicationUserId is the Record Display Name.



These rules apply to Record Display Name fields in standard entities:

  • The Record Display Name is required for each record in the entity.
  • The value of the Record Display Name field must be unique for each record in the entity.
  • If an eForm uses the entity as its data source, the Record Display Name field is required.

Record Display Names in Custom Entities

When you create a custom entity, you must complete several fields called the Unique Record Details. One of these fields is the Record Display Name, which serves as a unique identifier for each record in the entity.



Field Name Definition

Record Display Name
Function:
Specifies the display name for the field that uniquely identifies a record in your entity. This field is similar to a primary key in a database.

A value for this field is required for every record. The type of value this field accepts, and how it is handled in your application, depends on the option you select in the Record Internal Field Type list.

When you create a custom entity, the value for the Record Display Name field is the name that appears in the AgilePoint NX UI to identify the unique, identifying field at design time — for example, in Data Entities or the App Builder. It is a label that describes the type of data that a user or application enters when a record is created at runtime, but this label is not an instance of that data. For example, if you want to use an e-mail address as the Record Display Name, the value for this field should be Email Address, not a literal e-mail address.

Accepted Values:
One line of text that can have spaces.
Default Value:
None
Example:
Email Address

For more information, including examples of how this field is used in Data Entities and applications, refer to Record Display Names, Record IDs, and Primary Fields in Data Entities.

Example:
Refer to:

Record Internal Name
Function:
Specifies a unique, technical name for the Record Display Name field.

This is simply a technical identifier for the Record Display Name field. It is not a separate field from Record Display Name. It is a technical label for the same field. AgilePoint recommends you use a value that is similar to the Record Display Name field, only without spaces, so you can easily identify this field.

Accepted Values:
One line of text with no spaces.
Default Value:
None
Example:
EmailAddress

For more information, including examples of how this field is used in Data Entities and applications, refer to Record Display Names, Record IDs, and Primary Fields in Data Entities.

Record Internal Field Type
Function:
Specifies the type of data that is accepted in the Record Display Name field.
Accepted Values:
  • Text - The Record Display Name field accepts one line of letters and numbers that can not have spaces.

    When a new record is created, these rules apply to the Record Display Name field:

    • Each value entered for the Record Display Name field must be unique.
    • Values can be entered in the Record Display Name field through manual user entry (like in a form control form control on an eForm) or with variables that pass data from elsewhere in the application application or an external data source.
    • The value for the Record Display Name field can not be auto-populated by Data Entities.
  • Auto-Increment - Each time a record is created for the entity, Data Entities creates a value for the Record Display Name field with an automatically incremented integer.

    When a new record is created, these rules apply to the Record Display Name field:

    • The Record Display Name field value for the first record that is created for the entity is 1. Each new record is created with an auto-incremented number — 2, 3, 4, and so on.
    • You can not give a custom value for the Record Display Name field.
    • In eForms that use this entity as a data source, the Record Display Name field is not required.
Default Value:
Text
Example:
For more information, including examples of how this field is used in Data Entities and applications, refer to Record Display Names, Record IDs, and Primary Fields in Data Entities

Also refer to:

Once you complete these configuration fields and the custom entity is created, the these rules apply:

  • The Record Display Name field is required for each record in the entity.
  • If the Record Internal Field Type is set to Text, you must give a value for the Record Display Name field in each record. If an eForm uses the entity as its data source, the eForm must include the Record Display Name field.
  • If the Record Internal Field Type is set to Auto-Increment, you can not change the value for the Record Display Name field. An eForm that uses the entity as its data source is not required to include the Record Display Name field.
  • In most places in the AgilePoint UI — for example, in Data Entities or the App Builder — only the Record Display Name is visible. The Record Internal Name, which is a technical identifier for this field, is only visible in detailed configuration settings.

Example A

Company A, a shipping company, creates a custom entity to store information about their delivery routes. They set this configuration for their entity and Record Display Name field:

  • Entity Display Name - Delivery Route
  • Record Display Name - Route Number
  • Record Internal Name - RouteNumber

Company A wants to have this number auto-generated in Data Entities, and sets Record Internal Field Type to Auto-Increment.

Entity Configuration



Entity Fields Created



These are the results:

  • Data Entities creates an auto-numbered value for the Record Display Name field. This is the value associated with an individual record in the Route Number field. As a result, the Route Number for the first record created is 1, the second record is 2, and so on.
  • When a new Delivery Route is created (i.e., a new record in the Delivery Route entity), a value for Route Number does not need to be specified because it is auto-generated in Data Entities. In fact, a custom value for this field cannot be specified.

Example B

Similar to Company A, Company B is a shipping company that creates a custom entity to store information about their delivery routes. Company B uses the same values for the Entity Display Name, Record Display Name, and Record Internal Name fields as Company A:

  • Entity Display Name - Delivery Route
  • Record Display Name - Route Number
  • Record Internal Name - RouteNumber

However, in this case, Company B already has a database that contains information about its shipping routes in a database table. In this database table, the Route Number is the unique identifier (primary key) for each shipping route.

To handle this requirement, Company B does this:

  • Sets Record Internal Field Type to Text.
  • Uses a variable to pass the value of the primary key database column to the Record Display Name field in the AgilePoint NX entity.
  • In any eForm where the Delivery Route entity is the data source, the Route Number field is required. Company B uses an Auto-Lookup form control to do a lookup from the database, and populate the value of this field.

Entity Configuration



Entity Fields Created



Example C

Company C creates a custom entity to store information about independent contract employees, and wants to identify the contractors by their e-mail addresses. Company C uses this configuration for the entity and record:

  • Entity Display Name - Independent Contractor
  • Record Display Name - Email Address
  • Record Internal Name - EmailAddress
  • Record Internal Field Type - Text

Entity Configuration



These are the impacts applications that use the Independent Contrator entity:

  • Email Address is a valid Record Display Name field because e-mail addresses must be unique. AgilePoint NX enforces unique values for the Record Display Name field through data validation.
  • In any eForm where the Independent Contractor entity is the data source, the Email Address field is required. This field can be populated through manual user entry, or this value can be passed from another location — such as another eForm in the application, or an external data source — with a variable.

Record IDs

The ID field in a record is a unique, internal, system-generated identifier in every entity record. Do not confuse the ID field in a record with:

  • Record Display Name - This is a customizable, user-friendly identifier for the record. It is a separate, unrelated field.
  • Entity ID - There is another unique, GUID identifier at the entity level. This topic is talking about IDs at the record level, not the entity level.


These rules apply to the record ID field:

  • When you create a custom entity, Data Entities automatically creates an ID field at the record level.
  • When a record is created for an entity, Data Entities automatically populates a value for the ID field to associate with the record.
  • You can not change the value of the ID field for a record.
  • The record ID data type is a GUID.
    Note: If a Record Display Name field accepts a text value, it can also accept a GUID. If you want to pass a GUID from an external system to be the main identifier for a record, pass this value to the Record Display Name field, not the ID field.
  • The ID field is not used in AgilePoint NX applications. It is only used for internal, technical purposes and APIs.
  • Even though it is an internal field, you can use the ID field in some places in AgilePoint NX at design time. For example, you can use the ID field to create a relationship between 2 entities, and you can show the ID as a text field on an eForm.

Primary Fields

You create a relationship where the value of a field (called the dependent field) in one entity changes when the value of the Record Display Name or record ID in another, parent entity changes. This is similar to the a primary key/foreign key relationship in a relational database. In a relationship, the Record Display Name or ID is called the primary field. In thix context, the term primary field refers to a field's position as a parent in the relationship.