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):
- Record label, if defined on the Form
- Concatenation of key field values, if key fields are defined on the Form
- First text field defined on the Form
- 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.
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.
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) |