This data type is a single field in the target table that draws its value from a single field in the source table. Links to Single Fields can be configured to allow links to multiple records in the source table, called having "multiple values enabled," or MVE. In practice, the Link to Single Field data type is always used with multiple values enabled.

If you don't need multiple values enabled, it's best to use a  Link to Selected Fields, because it allows you to pull in additional fields if you need them in the future.

When you create a Link to Single Field, you have more options for display than most linked field data types, which makes this data type useful when you have a specific design in mind. When you select a record in the field, it becomes a hyperlink to the linked record, unless you make the field view-only or select a display option that doesn't support hyperlinks. For example, view-only plain text display is useful for URLs that need to redirect to the actual URL, and input boxes are useful when the default value is usually correct or when you want users to enter search terms directly in the box without needing to open a search window.

These options offer a clean, compact way to link to multiple records in another table, which is usually why you might choose this data type over the Link to Selected Fields data type. The Link to Single Field with multiple values enabled supports four display options: checkboxes, drop-down lists, multi-value with pop-up selection, and multi-value with search pop-up. In comparison, a Link to Selected Fields with multiple values enabled is always displayed as an embedded table, which might not suit your needs.

The main limitation of this data type is that the records you're linking to must be identifiable using only one field. A common solution is to create a compound field in the source table that combines two fields together, creating a unique, identifiable value from two non-unique values, such as the Full Name field in the People table that combines first and last names.

Creating a Link to Single Field

To create a new Link to Single Field:

1. Click Setup [Table], or click the Setup gear in the top-right corner, click Tables, select the table, and click Edit.
2. Go to the Fields tab.
3. Hover over New and select "Link to single field from other table." This opens the wizard on the Table tab.

Table Tab

On the Table tab, you configure the data source for the linked field.

1. Select the source table for your linked field. This is the table that holds the data you want to reference in the table you're working in. For example, if you're editing the Contract table to pull in the name of a salesperson, you would select the People table. You can select tables from the current KB, another  Agiloft KB, or an external database table.
   • If you select a different source KB, provide the login credentials for a member of the admin group. Then, click Get Tables and select the table you want to use as the source.
   • If you select an external database, you must add a database descriptor to the application server. Then, click Get Tables and select the table you want to use as the source. Data pulled from external databases is view-only.
2. In the Admin Notes field, enter a brief description of the field and its function, as well as any interaction with other fields or automation that other administrators might need to know.

Mapping Tab

The Mapping tab holds some of the most important options for configuring the linked field.

1. First, select whether to allow the field to hold links to multiple records. Links with this option are referred to as "multiple values enabled," and they work differently from links that connect only one record at a time. Remember that the Link to Single Field data type is almost always used with multiple values enabled, so you'll usually choose the first option. After you create the field, you won't be able to change this selection. Choose one of the options:

   • Yes, fast search. This is usually the best option for linking to multiple records because it allows you to use the data from the linked records elsewhere in the target table, and it allows table searches to find the data and include it in search results.

     The  Maximum Number of External Records to Cache  global variable limits the number of external linked field records that  can be cached for Fast Search. By default, this global variable is set to 100 records.

   • Yes, save space.  This  option is only used when you want to display many fields from the source records but don't need to search on them. It only links to the data in the source table and doesn't actually copy it to the current table, which can help reduce the size of records.
   • No. This limits the field to a single linked record at a time. If you want to link to a single record at a time, consider clicking Cancel and creating a Link to Selected Fields from Other Table instead, which provides greater flexibility for future changes.
2. If you chose No, you can also choose whether to allow entries not in the source table. If you select this checkbox, users can enter values that don't match a record in the source table, but there won't be a link since there isn't a record to link to. We refer to non-source values in a linked field as a “loose link” as opposed to a “strict link.” If you do allow entries that aren't in the source table, select the Do not update option in the next section.
3. Next, select whether to update your linked field when updates are made in the source table. Sometimes you want to keep the linked field in sync, such as keeping a user's name up to date. In other cases, you might want to preserve the original value, such as when pulling in the original price paid for an item. Choose one of the options:
   • Do not update. After a value is chosen for the linked field, that value is static unless overwritten. This is useful when you want to preserve historical values, such as the price of a product at the time of sale, or when you want to allow entries not in the source table. This is one of the most common options.
   • Update matching fields. If you want to allow entries not in the source table, but you do want to update any entries that match the source table, use this option. With this selected, the value is compared to the old value in the source record, and if the old values matched, the new value in the source record is propagated to the value in the linked field.
   • Automatically Update in the background. When the linked record is updated, the update is propagated to the linked field. This is one of the most common options. For example, if you link to a Person record and the person's last name is changed, your link is updated to match.
   • Automatically Update synchronously. Like the previous option, this keeps the linked field up to date when the source record changes, but in this case, the linked field is updated immediately after the source record is changed, before other rules can run and before control is returned to the user. This option is usually only necessary in complex rule situations, and you should only use it if the option to update in the background does not work correctly for your situation.

Field Tab

The Field tab displays all the fields in the source table. Choose the field you want to pull into the target table:

1. Select the field. For a Link to Single Field, make sure the field you select is reasonably unique to make sure users can select the correct linked record.
2. In the Field Label column, enter the label you want to show for this field in the target table. For example, you might be linking to the Full Name field in the Person table, but in the target table, it might be relabeled as Assigned To or Salesperson.

Permissions Tab

The Permissions tab contains options similar to other wizards, but it also has a specific bulk option to copy permissions from the source table for the linked fields. To view these permissions, click View Permissions.

You also have the option to replace these permissions with those copied from a field in the current table. To copy the permissions from a field in the current table, select it in the drop-down list and click Copy Permissions.

When a field is linked to a field in another table, users must be given View Others' permissions to the field in the source table to be able to use the field in the target table. This allows them to view the currently selected value or select a new value for the linked field.

Options Tab

Now, determine how your linked field should behave.

1. First, choose how to set the default value, if at all:
   • The values from the record(s)... This imports the value from the record in the source table in which a specific field matches a value in the target table. For example, you can have the system choose the correct linked company record based on a match of the Company Name, in the Company table, to the Customer Company in a support case. You can also use a default value for linked fields based on the person who did something, e.g., changed a field value from x to y, created a record, or last modified a record. After you select the two fields you want to use, you can also define logic for the system to use if there are multiple records that match the criterion.
   • Run the [specified ]  action when the  [ specified ] field is first set or edited. With this option, you can use an Update Fields action to populate the linked field with one or more records based on multiple matching criteria whenever a specific field is changed. For more information, see  Populating a Linked Field with a Saved Search .
   • The values for the user in the [specified] field of the user who changes the [specified] field. This allows you to pull from a user relationship based on who changed a specific field.
   • [Specified record]. Click the search icon to select a record in the source table to use as a template. The linked field is automatically populated with the value from this record.

   • None. This leaves the fields empty until a value is selected.

     If you're linking to the People table, you can also set the default value to the user who creates or edits the record, the user in the [specified] field of the user who creates or edits the field, or the user who changed the [specified ]  field.
2. Next, choose whether the default values are reapplied. To illustrate these options, imagine a linked field from the Departments table with the default value set to the department whose ID matches the requester's department ID in the current record. Let's see what each option does:
   • Once the field has a value, never overwrite it. With this option, after a user updates the field value from the default, the default value is never applied to the record again. For example, using the department example, after a requester is selected, the linked department is set to their department. Afterward, if either the requester or the department is changed, the system simply saves those changes.
   • Always reapply the condition to the default value when the record is edited. In this case, when the record is edited, the system sets the default value again. For example, if a different requester is selected, the department updates automatically to that person's department; however, if a user changes just the linked department and saves the record, the department reverts back to the requester's department the next time the record is modified. Because this can seem confusing to users, this option is usually best paired with a view-only field or a field users don't have permission to edit.
   • Only update the default value when the source field in the current table changes. This means the default value is only reapplied when an edit in the current table makes an update to the field used to determine the default value. For example, if a user manually changes the department, the new department is saved and the default is not reapplied. However, if a user selects a new requester, which is the source field used to determine the default value, the department is updated to that requester's department.
3. In the next section, you can make your linked field required, not required, or required only under certain conditions.
4. If your field allows only a single record to be linked, choose whether to require a unique value in your linked field. For example, you might want to make sure each training schedule is assigned to only one user, and each user is assigned to only one training schedule.
5. Set Deletable? to Yes or No.

6. In the next section, you can restrict the source table records that are available for users to link. For example, to choose a company location in a contract, you could use a saved search to show only locations in which the Company Name matches the Contract Company Name.

   If you want to use a matching field search criterion, select the field in the source table from the field drop-down, choose an operator, and choose variable rather than value from the next drop-down, then click Formula Help. Go to the Parent Field tab to find the field in the current table that you want to match against and to insert it into the search.

7. If desired, add visibility conditions to hide or show the field as needed.
8. If desired, add conditions to make the field editable or not editable as needed. For example, if you chose the "Always reapply" option in step 2, you might want to make editing conditional.

Display Tab

Now that you've defined the behavior, it's time to determine how the linked field or fields should look. Before getting into the wizard options, take a look at the different outputs you can offer your users.

Display Options Without MVE

This table shows the options for displaying linked fields that allow single values.

Setting Display Options

To configure your field display in the wizard:

1. Select one of the display options. It can be helpful to display a hyperlink so users can navigate directly to the source record to see more information.

2. If you don't have multiple values enabled, you can click the edit icon next to the selected display option to adjust the length of the field. By default, linked fields are long enough to accommodate the longest possible value from the source record, which often disrupts existing layouts and takes up more space than necessary. Editing the field length here does not affect the field length in the source table. You can also add an instructional pop-up or input instruction for the field here.
3. If you have multiple values enabled for your field, choose whether to show them in alphabetical order or the order they were linked in.
4. Select a source table view to use in the search look-up window. Make sure the view you choose includes enough information for users to identify the correct record to link.
5. Define the default search used in the search look-up window.  It's helpful to choose  String  under Default search because a string search finds word fragments as well as whole words, and it's therefore more likely to produce the results that you’re looking for.
6. Complete the remaining standard field display options: input instructions, text alignment, and label and instruction placement.