Properties of linked field: Linked field mapping

On the Linked field mapping tab, which is present when you have selected a new or existing data dictionary field in a database definition and set the Type of this field to Linked field on the Field properties tab, you set up the field mapping for fields that you want to retrieve (merge) from a linked record and display on a detail screen in the record in the current, primary database table, and the mapping for fields that you want to write back to the linked database table after editing them in the primary database table. Note that you do not have to specify a field mapping for the fields you wish to display in any zoom/edit or link screen associated with the linked field in the current database table; this is because when you "zoom" in to a linked record, Collections really opens the linked database table and allows normal access to all fields in it.

Click here for information on how to edit properties in general. On the current tab you'll find the following settings:

Copy fields from linked record

When you allow a user to select a value in a linked field, you sometimes want other data from that linked record to be displayed in screen fields in the current, primary record. Take for instance the reproduction Reference entry field (reproduction.reference in the data dictionary): when a user selects such a reference in the catalogue, you want other data from that reproduction record to be displayed next to the Reference entry field, like the path to the digital image, the format of the image and its reproduction type.
For each piece of data to be retrieved, you must specify which (source) fields from the linked database table are to be retrieved, and in which (destination) fields in the primary database table Collections must place this information for display of the record.
For Axiell Collections, all destination fields must have been specified in the current, primary database definition and all linked fields need to have a forward reference field.

The data in the merged fields from the linked record is retrieved each time you display a screen with these fields. And the retrieved data is not saved in the primary record, it is only displayed. Also, the linked field itself must be included in this merge-field list too, otherwise no value will be displayed in the linked field! So for linked fields with a forward reference, always include the linked-to field and the linked field as the source and destination fields in this copy-fields list. The forward reference field should not be included.
This construction has a potential problem: if you try to edit one of the merged-in fields in the primary record (which would be possible if the screen field which is associated with the merged-in field hasn't been set to read-only) and you save it, then the old value will reappear when you haven't specified this field as a write-back field too (see further down this topic).
If one or more of the fields to be merged in with a linked field, are linked fields to some other database table themselves (let's call them secondary linked fields), then it's often best (although only really required if the merged-in values must be written back to the linked record too, or if possibly more than one occurrence of the secondary linked field must be retrieved) to merge in the link reference fields associated with those secondary linked fields instead of the secondary linked fields themselves; the target fields in the primary database definition must then of course also be link reference fields for linked fields. If you merge in a secondary linked field itself, for instance because it won't be editable in the main record, then the target field can be a plain field of the same data type as the merged-in source field, but take into account that in this case only the first occurrence of the secondary linked field can be retrieved.
If one or more of the fields to be merged in with a linked field, are already merged-in fields (with some other, secondary linked field) in the secondary database, then there's no need to merge them into the current primary table if you already merge the relevant (link reference field of the) secondary linked field into an indentically defined field in the primary database definition (including its own merge list).

Note that merged-in fields are problematic to index, although it is possible to create an access point for them.

Also note that context fields can be merged in too.

Copy lists from linked record

With this functionality you are able to display all occurrences of some source field (let's call it C, for reference) from a record in a secondary database table, in a drop-down list (a dynamic enumerative list) of a destination field (B) in the current, primary database table, dependent on the value in the associated linked field (A) in the same primary database table that contains this Copy lists from linked record definition.
The destination field can also be a linked field (B) to a source field (C) that itself can be an internally linked field or a normal linked field in the secondary database table: linked field (B) will still offer a choice between all occurrences of field (C) from the linked record in the secondary database table, via the auto-complete drop-down for the field or via the Find data for the field window, but if the user doesn't know which to pick, he or she can use the Find data for the field Filter option to search on related data to find the right term or name to pick. A requirement for this second option is that both the current linked field (A) for which you are filling in the Copy lists from linked record definition, and the linked field (B) that is the "copy list" destination field, should link to the same database table. The linked dataset inside the linked database table can be different though.

This type of enumerative list has not been applied in our model applications yet, so some examples may clarify its purpose.

Example 1 (succinct): suppose you have a Contacts database table in which you register calls from customers. In a Contacts record you have a linked field to register the institution or company name of the customer but you'd also like an enumerative field (drop-down list) containing all employees of the relevant institution, to register the name of the caller. And this list must be generated automatically. This can be achieved if the institution name record in e.g. Persons and institutions also contains a list of all its employees in some repeated employee name field. Basically, what you would have to do is create an enumerative field in the Contacts database, of the Enumeration source: list from a record type (while not specifying a Dynamic list field). Then for the linked institution name field you would have to specify the source employee name field in linked institution records and the destination contact name enumerative field in the Copy lists from linked record box on the Linked field mapping tab. (After this, you would of course also still have to add the new enumerative field to the relevant screen to make it visible to users.) This would then make sure that whenever a user registers the name of an institution in a Contacts record, the employee names of the institution are copied from the linked record to populate the new contact name drop-down list from which the relevant caller can easily be selected.

Example 2 (elaborate): say we have a primary database table in which we document conservation activities in a museum. A part of the data in such a record must describe the environmental requirements for the activity. Some of the required fields are the type of Measure, the allowed Value (range) of this measure, and the Unit of measure: the type of measure could for instance be temperature or humidity, for temperature the Value could be any single degree or range of degrees, and the Unit could then be Fahrenheit or Celsius for example. In this case we would further like to store the types of measure as Thesaurus records (in their own domain, e.g. Environment), and we want each measure record to hold all possible values and units for it, since we want to limit the number of acceptable values and units strictly.
A logical way to implement this, would then be to add two repeatable fields to the thesaurus, one for the units and one for values; the measure type will be stored in the Term field. (Of course you must also adjust or create a screen and include it in your application, to display this data and allow user input.) A part of such a filled-in Thesaurus record could look like the following (screenshot not from Collections):

So with this (rather limited) record, the user will have no choice of measure unit, because it can only be Degrees Celsius, but there is a choice of two temperature ranges for the conservation activity.

In the conservation activities database definition we must now create three comparable fields:

(And finally you must of course adjust or create a screen and include it in your application, to display this data and allow user input.)

Now, when open your application, and access the data source associated with the primary database table (in this case the conservation activities data source), and edit a record by linking to Measure type temperature on the screen for environmental requirements, you will see something like the following (screenshot not from Collections):

The Measure field is validated against the Thesaurus (Environment domain), so the user can type a measure or choose one from the Find data for the field window. The Value and Unit fields have become drop-down list that are dynamically filled with data from the measure record that the user just chose. So for temperature the user will be able to choose from the two specified ranges, and if he or she opens the Unit list, the only choice will be Degrees Celsius, in this example.

Write fields to linked record

Write-back links were created to allow the user to edit merged-in fields directly in the primary record and have the changes written back to the corresponding fields in the linked record. Source fields are now fields in the current, primary database definition, while the destination fields are fields in the linked database definition. Data is written back when you save the primary record.

Write-back links should be used sparsely, since the consequences may be serious: after all, the user may change a linked record without him or her necessarily being aware of it, causing all records in other database tables which link to that record (with a forward reference), to reflect the changes.
On the other hand, when you do not specify write-back links, you should make sure that any merged-in fields are not editable, by making the relevant screen fields read-only.

If you do specify Write fields to linked record, then remember to never include the currently specified linked field and linked-to field (Lookup field) in this list, because that would cause errors due to the fact that writing to the linked database table is already part of the functionality for linked fields.
One special case in some applications is a linked tag like ti in the Orders database, which uses the Lookup field TX (a term index on the whole Title field in Document) instead of the ti free text index: because the linked tag ti must write a title back to the ti tag in Document, this tag pair should be (and is) included in the write-back fields list.

If one or more of the fields to be written along with a linked field, are linked fields to some other database definition themselves (let's call them primary linked fields), then you should always write the link reference fields associated with those primary linked fields instead of the primary linked fields themselves; the target fields in the secondary database definition must then of course also be link reference fields for linked fields.
If one or more of the fields to be written along with a linked field, are merged-in fields (with some other, primary linked field) in the primary database definition, then there's no need to write them to the linked secondary database definition if you already write the relevant (link reference field of the) primary linked field to an identically defined field in the secondary database definition (including its own merge list).

Further, it is recommended that write-back fields never have a default value in the primary database definition. If a default value is desired, set this value for the target field in the linked database definition instead. This does have the minor disadvantage that when you create a new linked record from within the primary database table, the default value won't be visible until you store the primary record. This problem does not occur when you link to an existing record.