Key field

Overview

The "Key" property of a Field has multiple purposes including labeling records in the user interface, enforcing record uniqueness during data entry, and helping users look up related records during data entry for a Reference field. You can set Key fields in the Field cards under “Settings.”

Behavior

Key fields in ActivityInfo are used for the following functions:

  • A way to label Records in the user interface
  • Enforce Record uniqueness during data entry
  • Look up related Records during data entry
  • Match related Records when importing
  • Match existing Records to update during importing
  • Indicate which Fields date-based locks apply to

Labeling records

When selecting or deleting records, the records are labelled in the user interface using the following values (listed in order of system preference):

  1. Record label, if defined on the Form
  2. Concatenation of key field values, if key fields are defined on the Form
  3. First text field defined on the Form
  4. Record id, if no text fields are defined. Each record in ActivityInfo is automatically assigned a unique, auto-generated Record ID that never changes. The Record ID is used to store the relationship between two records, and is essential to preserving referential integrity, but is not very user friendly.

Record IDs are normally hidden from the user, but you can display them in the Form View by clicking “Select Columns” and then checking “Record ID”:

If no Record label is defined, then the Key field is used. If no Key field is specified, the Record ID is used to label the Record. This is probably not what you want.

What users see when no Record labels or Key fields are defined
What users see when no Record labels or Key fields are defined

For easier readability, we recommend Specifying a Record label.

Enforcing uniqueness

ActivityInfo does not allow adding Records with the same Key field.

If there are multiple Key fields, then the combination of Key field values must be unique. For example, if you have two Key fields “First Name” and “Last name”, then “John Smith” and “John Smith” are considered duplicates, but “John Brown” and “John Smith” and “Bill Smith” are different combinations and can all be added to the Form.

If you try to add a Record with the same combination of Key fields, an error message is displayed:

Checking for duplicates requires access to the existing Records. If two users are working offline and are disconnected from the internet, it is possible for them to add duplicate Records. Both copies of the Records are synchronized to the server when the users connect.

Looking up records in Reference fields

When you add a Reference Field to another Form, Key fields are used by default to display the list of Records to choose from.

If you designate multiple Fields as Key Fields, then ActivityInfo provides a cascading set of dropdowns.

By default, Key fields are used to look up values in a Form. Alternatively, select the Fields you wish to include in a look up or add your own custom Formula(s).

When designing a Form, you can configure which Fields on a reference Form may be useful for lookup. These may or may not be Key fields, or may be just a subset of Key fields.

Lookup fields section.png
Lookup fields section.png

For more information on lookup Fields, see Reference field.

Labeling reference values in the Table view

When viewing a form with a reference field in the Table View, the values of the key fields are used to label the related record.

Key fields and date-range locks

When you add a date-range lock, it only applies to Forms that have a date-like Field designated as a Key Field. This includes:

  • Date
  • Month
  • Week
  • Fortnight

In many cases, you may want to apply a lock based on a date that is not a Key field. In these cases, you should a rule-based lock instead.

Optional Key Fields

The first Key Field in a Form is “Required” by default.

However, subsequent Key Fields can be optional. This can be useful if a Field is part of a Record’s unique identifier, but only some of the time.

Supported Field Types

The following Field types may be designated as Key fields:

  • Serial number
  • Fortnight
  • Barcode
  • Date
  • User
  • Reference
  • Month
  • Text
  • Week
  • Fortnight
  • Single Selection

Limits

Each Form can have a maximum of 10 Key fields.

A Serial Number Field is always the only Key Field. A Serial Number field cannot be combined with other Key Fields.

Example

The following table provides a few example of forms and common choices for Key Fields.

Form Key Field(s) Notes
Province Name (Text)
Territory

Name (Text)

Province (Reference to Province)

NFI Distribution

Date of Distribution (Date)

Location (Reference to Village)

Unless your programme is planning on providing multiple distributions to the same place on the same day, these two fields are good natural keys.
Beneficiary Email Address (Text) An email would be a good natural key if your assistance is delivered digitally, as all beneficiaries can be expected to have an email address.
Beneficiary

First Name (Text)

Last Name (Text)

Date of Birth (Text)

In many cases, you’ll need a combination of Key fields to identify beneficiaries.
Activity

Type of Activity (Single Select)

Date of activity (Date)
Partner (Reference to Partner)

Next item
Geographic Point field