Linked field properties
Contents
On the Linked field properties 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 link to a field in another database.
Click here for information on how to edit properties in general. On the current tab you'll find the following settings:
This property contains the full or relative path to the database you want to link to, without the name of the file. You don't have to fill in this property manually: just select a database in the next option, and the relative path to that folder is automatically entered here. Usually, you keep your database definitions in one folder, and the relative path you'll often encounter here is: ../data. A single dot represents the current folder (which is the case for internally linked fields, like in thesau.inf).
First, enter or search for the name of the existing database (an .inf file) that you want to link to. Do not enter the extension of the file. Examples of database names are DOCUMENT, COPIES, and Collect. A single "=" symbol in the Database property represents either the current database definition or the current dataset (which applies to internally linked fields, like in thesau.inf), depending on the Database scope setting for the relevant internal link definition. If the Database scope property has been set to Undefined or Database, "=" refers to the current database definition, while if the Database scope property has been set to Dataset, "=" refers to the current dataset (within the current database definition).
Important: when you work in a copy of your live application, then make sure you search the right folder (in the copy) for the proper file: otherwise the relative path will be incorrect when you place back this copy as your live application later on.
If the database definition that you select has datasets defined for it, these datasets will be listed in the Dataset drop-down list. (Some database definitions may not have datasets though.) Selecting a dataset is optional, you can also just link to an entire database table. Typically, you select a dataset if for this link you only want to retrieve data from that specific dataset, and if you want new linked records to be created in that dataset automatically.
If you select no dataset, when the database table does have datasets, you must offer the user the choice of dataset when he or she creates a linked record from within the current primary database table (see the Dataset selection field option at the bottom of this tab).
Note that it is in principle possible that the database you link to has no data source specified for it in the .pbk, for example because although users of that application are allowed to create a link to a record in that database table, they are not allowed to search and edit records in that database table via a data source. In Axiell Collections, having no data source for a linked database does mean that once the user has opened the Find data for the field window to select a term or name from the index on the lookup field in the linked database table, then the Search dialog which is opened by the Extend search button in that window (to search for the appropriate record to link to, via other fields) will contain an empty Standard tab because there are no access points to show (access points are defined in a data source), but the user can still search using the Advanced tab.
If you link to a database table and/or dataset for which no data source is specified in the .pbk (or for which a data source is specified with no access rights for the user), then clicking a link in the currently specified field can't open any zoom screen (the user gets to see a "This action is not allowed" message and will have click OK and press F5 to make Collections responsive again) and the link won't be visible in the Related records view either (even if Relations texts are configured). The solution is to create a data source in the .pbk for the linked dataset still. You could make it read-only so that users can only search it.
Enter the tag or the field name from the linked database definition in which Collections must search for the key data when accessing the currently defined field in a running application. A Text (!) index must have been specified for this lookup field in the linked database definition.
(If you want to use a long text field, such as a title field, as lookup field, you should create an (additional) index of the Text type for that field. Then make sure the index Key size option is set sufficiently long, although maximally 100 characters for indexes in SQL databases, so that a title can be indexed as a single term in this index. Also, if a Free text index already exists for the field, then the new term index cannot list the tag to be indexed as the first tag, so a dummy tag (which must still be defined in this .inf) must be listed first and secondly the long text field. See the combined index on Tx and TI and the relevant field defnitions in collect.inf, for example.)
The best way to select a lookup field, is when you have selected a database definition to link to first, then click the ... button next to the current option to open the Database fields window, and just pick the desired field from the available fields in the linked database definition. The presented fields list is limited to fields which actually have a Text index. This way you can’t accidentally select a field with a different type of index as the lookup field.
Note that fields do not have to be text fields per se, to have a Text index. The Type column in the Database fields window indicates the field type, not the index type.
Forward reference (a.k.a. link reference)
Enter the unique tag or field name of the field in the current, primary database definition in which Collections must save the record number of the linked record. This is necessary if you want modifications in the key data in the linked record to be visible in all the records that refer to it. If you specify a link reference field, Collections will not save the key value of the linked field in the primary database, yet only the record number that points to the linked record.
After you've entered a tag or field name, and you leave this property, Designer will check if the tag or field name is not in use as a forward reference by another linked field already, and warns you if it is used elsewhere; then choose another tag or field name: each linked field needs to have its own link reference field. Collections doesn't allow for linked fields without a link reference field.
The linked field in the current, primary database table cannot be indexed itself. This is because the data for the key field is not saved in this database, only retrieved temporarily. Only the record number (the forward reference) of the linked record is stored in the current database table. Therefore you should always define an index (of the integer type) for the link reference field. (The only place where you refer to this indexed link reference tag instead of the linked field itself, is when you create a method/access point for the current linked field. In screens you always associate an entry field with the linked field name or tag, never the link reference tag.)
Specify the Data type of a forward reference field as Integer, and set Member of group to the group name to which the associated linked field may belong. And if the associated linked field is repeatable, then also make the forward reference field repeatable. The forward reference field is now a part of the data dictionary, is well documented, and will appear in all field lists in Designer and running applications. Now, when you select its tag or name for the Forward reference option in the Linked field properties, you can be sure the tag is unique.
It is not necessary though, to create the forward reference field in the data dictionary prior to assigning its (future) tag or field name to the current property, because when you enter a non-existing tag here, Designer automatically adds a data dictionary field definition for this tag in the current database definition and sets the Data type to Integer, copies any group name and Repeatable setting. But do check that the settings are right, also after you change the definition of the linked field.
Backward reference (a.k.a. reverse link)
If you're creating a reverse link, enter or select the forward reference tag used in the linked database definition to link to the field in the current database definition, that you are specifying now. The field in the linked database definition that is associated with that forward reference, should be reciprocally defined. (See Reverse links for more information.)
This option is used for setting up the storage of reverse relation metadata in a separate database table. See the relevant general topic for more information.
For reversely linked fields (like between collect (loan.in.number, with link reference tag lK) and loans (object-in.object_number, with link reference tag lL) which are displayed in a table grid in Axiell Collections and are used heavily (linking hundreds or thousands of records to a single record), you can implement so-called indexed link tables to improve loading and display performance of such records significantly. Please see the General topics: indexed link table structure topic for more information.
This checkbox must be marked as part of the setup of the indexed link table. The new table in the SQL database will automatically be created as soon as you mark the checkbox: only when the field already contained data you'll then also need to reindex it to fill the new table.
For reversely linked fields (like between collect (loan.in.number, with link reference tag lK) and loans (object-in.object_number, with link reference tag lL) which are displayed in a table grid in Collections and are used heavily (linking hundreds or thousands of records to a single record), you can implement so-called indexed link tables to improve loading and display performance of such records significantly. Please see the General topics: indexed link table structure topic for more information.
When occurrences of the current linked field are displayed in a reversely linked record, Collections needs to know how to sort them because the new table structure no longer saves the occurrence numbers in which data was originally entered, so the preferred sort order must be set here. So select a Sort field from the drop-down and set the sort Order: do the same for the reversely linked field. You can only pick from indexed fields in the same relevant field group. For example:
Select this option if you don't want to link this field to any specific domain in the authority database definition. This means that for the current linked field the user always gets to choose between all terms in the authority database table, when validating data entry.
Select Fixed if you want if you want this field to always retrieve its data from the same domain in the linked database table (or from a domain which partially depends on certain field contents). Also fill in the Name of the domain to link to option; not filling in a domain name results in a corrupted index.
Only for a Fixed domain. Fill in the neutral name of the domain in the linked database definition from which this field must retrieve its data.
This typically applies to fields in databases (like the catalogue) from which you link to authority databases (like the thesaurus). The specified fixed domain must of course exist in the concerning validation database definition.
Another possibility is to compose the fixed domain name of a fixed and a variable part (although this is not possible for linked fields in a metadata table). Suppose you have one or more linked fields that should be associated with their own domain which must consist partially of some fixed string (probably some string specific to the linked field) and for the other part of variable field contents which also represents a string, then from Designer 7.3 you can use a format string here in the Fixed property. This format string may contain zero or more strings and zero or more English field names in between percent characters, in any order you'd like.
Typically, you could use this functionality if records in a single dataset can be of different "types" while certain linked fields, although applying to all these types, should validate to different lists of thesaurus terms dependent on the record type.
Example: say you have a dataset which may contain records for films, audio and photos. Upon opening of a new record, the first thing to do would be to select the desired record type from a drop-down list containing film, audio and photo. Let's say the field name of this drop-down list is record_type. You may or may not have also set up some conditional screens (although this is in no way a requirement) so that dependent on the record type you select, screens with fields appropriate to the record type appear. Now suppose there are also several fields which link to the Thesaurus and must be filled in for each record type, maybe a quality field. It's likely that you'll have different terms to describe photo quality, audio quality and film quality, but if you would associate the quality field with a fixed domain, you would always have to choose from all descriptors when filling in the field and validation of the entered descriptor would also succeed if you entered a film quality descriptor in the quality field for the record type audio.
To avoid such confusion you could now store the three different types of quality descriptors in their own domain (manually in advance or automatically during editing of the object record), e.g. "QUALITY_FILM", "QUALITY_AUDIO" and "QUALITY_PHOTO" after you had set up the fixed domain for the quality field with the format string QUALITY_%record_type%. Every time you would then validate an entered term in the quality field or request a list of accepted terms in the Find data for the field window, Collections would concatenate the fixed string "QUALITY_" with the string value obtained from the record_type field ("FILM", "AUDIO" or "PHOTO") and consequently use the resulting domain ("QUALITY_FILM", "QUALITY_AUDIO" or "QUALITY_PHOTO") for searching or forcing the thesaurus term.
In principle you can use any type of field(s) in the format string. Of enumerative fields, the neutral value will be used (which is case-sensitive).
Note that as long as the field used in the format string hasn't been filled in in the record you are editing, Collections can only assume any fixed string in there constitutes the whole domain name (which may not exist as a separate domain). Try to avoid this situation from occurring (by using conditional screens for example).
From Designer 7.9, you can select the (neutral) name of this domain from a list of all available domains for this field, so you don't have to look up the desired value elsewhere and you can't accidentally make any typing errors. Open the list by clicking the ... button right next to the property box. A separate window opens with on the left the neutral value and its user-friendly translation in the currently set application language on the right side. Simply select the desired one and click OK to copy the neutral value to the property box.
You can also still type a neutral value yourself: as long as the value you type does not match one of the neutral values in the list, the background of the property box will be pink. The exception is a Fixed domain which consists of a fixed and variable part, like QUALITY_%record_type% for example: as soon as you type a percent character, Designer knows it can't validate this domain to the list anymore, so it won't show the pink background either.
Select Variable if you want to allow the user to choose a domain each time he or she enters a term in this linked field (not possible for linked fields in a metadata table). Also fill in the Tag which holds the domain name to link to option.
Tag which holds the domain name to link to
Only for a Variable domain, fill in the tag or field name in the current .inf (not the linked file) in which the applicable domain names are saved.
This typically applies to fields in database tables (like the catalogue) from which you link to authority database tables (like the thesaurus). This domain field, in for instance a catalogue, should preferably be an enumerated static list from which the user can choose a domain for the currently specified linked field. So in an application you'll then have two entry fields (usually above each other), of which in the first the user has to fill in some term, and in the second select a domain to which that term should belong. When setting this up in the current primary database, you should fill the enumerated list with the appropriate domain names yourself.
The values which can be selected by the user for a linked field can be limited by the application manager to values from a fixed or variable domain, to force users to pick an appropriate value for this field. Similarly you would sometimes like to limit the offered list of values even more or differently, based on an advanced search. For example, for databases that have multiple record levels (e.g. archives/film), it is only relevant to see the item-level records when attaching items to a loan. In that case you'd like only item records to be presented in the list of records to link to. One may also want to pre-limit that list to items that are actually available (i.e. items without lending restrictions or condition problems) so that an unavailable item isn't inadvertently selected by the user.
From Designer 7.7.5.3038, therefore a Search filter option has been made available. In it you can specify any* advanced search query you'd like to apply always when a list of available values for the current linked field is retrieved from the relevant linked database table, for example when the user starts typing in the linked field and the auto-complete drop-down opens for the user to pick a value from or when the user opens the Find data for the field window to search for a list of available values. Also when using the Extend search option from within the Find data for the field window, will the filter be applied to the list of found records.
The Search filter you set here, will be additional to any domain and lookup field you set for this linked field.
Also, the filter won't be visible in the Collections user interface anywhere. In many cases you probably don’t want that anyway if you have set a search filter based on sensitive information (the object value, for instance).
Collections version 1.13 or higher is required to handle this functionality.
* Note that you cannot use any %<variable>% (to include data from the current record) in the search statement. You can only use fixed values.
This checkbox should always be marked. The option to deselect it is obsolete and may lead to data corruption if the Allow creation of new linked records option below has been deselected as well.
To be precise:
| • | if both this option and Allow creation of new linked records have been deselected, then any entered term in the linked field will be stored directly in the linked field itself. If the current field is linked on reference, this leads to data corruption since the entered value is stored in the local record instead of in a linked record, while if the current field is not linked on reference, this leads to a discrepancy between terms registered in the linked database and terms registered in local records, which is undesirable as well. |
| • | if this option has been deselected while the Allow creation of new linked records option has been marked, a new linked record will be created automatically for any new term entered in the linked field, but the user won't be notified of this in any way. This is undesirable because instead of suggesting the user to select an existing term if possible (and thereby keeping your authority files as clean as possible) the user may incorrectly assume that any entered term is validated and therefore be unaware of redundant, non-preferred terms being entered. |
| • | Mark this option to make sure that any entered value in the linked field is validated against the linked database table. If the Allow creation of new linked records option has been deselected, the user will be forced to pick an existing term from the Find data for the field link window before leaving the linked field, while if the Allow creation of new linked records option has been marked, the user can choose between picking an existing term from the mentioned window or adding the new term as a new record in the linked database table explicitly. |
As a rule of thumb, always mark this checkbox. It ensures that of any merged-in fields only the first occurrence will be retrieved. This is essential if the current linked field is a repeated field, which is very common, because Collections cannot deal with repeated fields within a single repeatable field group occurrence. Note that any (repeatable) data dictionary field group is allowed to contain more than one linked field that links only to the first occurrence.
A special case, one which requires marking this checkbox too, is when the current linked field links to a database table which is reversely linked to the current database table. For example: an object record can link to multiple outgoing loans, while in reverse, an outgoing loan record can link to multiple object records. In the loan record, several details can be registered for each linked object, the loan status for example. A linked object and its accompanying details reside in a repeatable field group. Now what if you'd like the loan status of an object x in, say, occurrence 4 of this field group to be visible in the record of object x in the objects catalogue, which in return links to this loan? If you would merge-in the status field and mark the consequently mandatory Link only first occurrence option here, you would maybe expect that the status of the object linked in occurrence 1 of the relevant field group in the loan record would be merged in, which would be wrong. Fortunately, this is not the case: under these special circumstances, the reverse link makes sure that (with the current option marked) any merged-in fields will be retrieved from the correct field group occurrence in the linked record. So in our example, the status belonging to linked object x, as present in occurrence 4 of the relevant field group in the loan record, can be merged-in with the linked loan number in the record of object x.
You are only allowed to deselect this checkbox if the current linked field is not a repeated field and if the fields to be merged in are not part of a data dictionary field group: single repeatable source fields to be merged in are allowed though. You could then add individual repeated target fields in the main database definition and on screen, to contain the multiple occurrences of the repeated fields merged in with the current linked field.
<obsolete setting, has no function>
For linked fields (originally developed for linked fields which are validated on more than one field but applicable to normal linked fields too) you can optionally use the Selection list format string option to specify which fields (the validation fields for example) from the linked record should be displayed in the auto-complete drop-down list for this linked field, to quickly distinguish non-unique terms for example. For a multiple validated linked field on the term and term code fields for example: %te% (%tc%), meaning that the term will be shown, followed by the term code in between brackets. In this case, if no term code is present, the brackets will still show without anything in between. You can enter field tags enclosed in % and fixed text and spaces. Field tags do not necessarily have to be indexed. The format string is optional: if you leave it out, the auto-complete list will just use the forward reference field to look up and show terms.
Note that backwards compatibility with Designer versions older than 7.7.2 and Collections versions older than 1.10.1 is broken as soon as the Selection list format string option for a linked field has been filled in, but can be restored by emptying the option again.
Allow creation of new linked records
Mark this checkbox to allow the Adlib user to add or force (adding and forcing are two ways of creating new linked records) new records into the linked database table, by entering a new term or name in the linked field and explicitly add (Create and edit entry) or force (Create entry) the new record from within the Find data for the field link window.
If you deselect this checkbox, the Collections user will not be able to add or force records to the linked database table from within the current linked field and he or she will always have to pick an existing term or name from the linked database table through the Find data for the field link window (provided the Strict validation option above has been marked). Nor will the Collections user be able to edit any existing records in the linked database table, through the current linked field.
If you allow the user to create new records in the linked database table from within the current primary database table, and this table is divided into datasets, you'll have to choose whether you want the new linked records always to be created in the same dataset or in a dataset that the user chooses each time a new linked record is to be saved.
If you retrieve the data for this linked field from a fixed dataset, that you set in the Dataset option in the top part of this tab, you automatically save new linked records in that dataset too.
If you want the user to have the option to choose a dataset, then you leave the Dataset option in the top part of this tab empty (to be able to retrieve data from the entire database table), and you provide a Destination dataset field instead.
In this option you enter the tag or field name from which the user will be able to choose the name of a specific dataset to which a new linked record must be added.
Prior to version 1.10, Axiell Collections did not support this functionality and offered no choice of dataset and just wrote the new linked record in the first available dataset. However, from Collections 1.10, Collections does offer the user a choice of data sources in which he or she is allowed to create the linked record. Collections does use the field set up in the Destination dataset field property for this purpose, but not in the old (Adlib) way. The only requirement for the field is that it is a text field of sufficient length to contain the data source names and that it is repeatable, so it does no longer need to be an enumerative field and if it still is, it doesn't do anything with the translations in the specified list. It is just used by Collections as a temporary container for the user-selected data source: a temporary container is required since creating a new linked record with the Create term button is a delayed linked record creation. The list will dynamically be filled with the names of the data sources in which the user is allowed to create new records and the data source names will be retrieved from the .pbk. The field will not be stored in the record XML. So for existing applications, nothing needs to change: the enumerative lists might not serve their original purpose anymore, but you can leave them as is. Only for new linked fields which use a new destination dataset field, you now know what the requirements for that field are.
Note that you mustn't use the Destination dataset field functionality for internally linked fields.
It is possible to use multiple (external) thesauri in Axiell Collections, when searching or validating a linked field set up for this use. In the Find data for the field... window in Collections the user can then find the Thesaurus drop-down list in which he or she may choose a different thesaurus and select it for use.
There are no preset external sources by default. From Collections 1.10, any extra thesauri which might be used, must be set for the applicable linked field(s) first, here in Axiell Designer. The Thesaurus drop-down list will only become visible if the user tries to validate an entered value in the relevant linked field. The user may then choose between the external authority files preset by the application manager only.
You set external thesauri for the currently selected linked field by adding new data sources to the External sources list:
| 1. | Click the Add button to add a new data source. |
| 2. | Put the cursor in the Path or URL entry field and click the … button to look for a thesaurus .inf file on your system or on the local network. The path to the located .inf will be filled in for you. You may also enter a path manually or provide a URL to a web service which can search a database on the internet for a key entered by the user to receive the search result back in Adlib XML format. Termennetwerk (terminology network): in Axiell Collections, to validate terms in Dutch to a selection of multiple authoritative terminology sources/vocabularies used in the museum branch, one can opt to use the freely available Axiell Gateway to the NDE (Netwerk Digitaal Erfgoed) Termennetwerk. This allows users to validate an entered term to one or more terminology sources at the same time, although one cannot limit the validation to some term type. The format of this Gateway URL is: https://webservices.adlibhosting.com/termennetwerk/go.aspx?source=<sources>&stylesheet=<stylesheet>&search=%data% source - use the source parameter in the URL to specify one or more sources. An overview of the available sources can be found on: https://webservices.adlibhosting.com/termennetwerk/xml/sources.xml The id attribute of each source in this XML file indicates the name of the source and can be used as value for the source parameter. If you'd like to access multiple sources at the same time, you should separate those with a comma without space, for example: aat,rkdartists,wo2 stylesheet - with the (optional) stylesheet parameter you can specify the stylesheet with which the retrieved data from the source is transformed to Adlib XML. Since the gateway is hosted at Axiell, you can only choose from a few standard stylesheets which map not only the selected term or name but scope notes, PID URIs and any other available metadata as well. By default (if the parameter is left out of the URL), a stylesheet called tn2axiell42 for model applications 4.2 and 4.5.# will be applied: you can also specify this stylesheet explicitly of course. For model application version 5.0, please specify stylesheet=tn2axiell50. (A special stylesheet (stylesheet=tn) will convert the Termennetwerk JSON data to XML directly, without transformation to Adlib XML, should that be required.) So you can search multiple sources with a single Termennetwerk definition, but if you'd like to make it more clear to users to which individual source they are actually validating a term or name, then you can also list multiple Termennetwork URLs here (or other external sources for that matter), each one specific to one source for example. Click the Description entry field to be able to enter the name or description of the external thesaurus in multiple languages. This name will become visible in the Thesaurus drop-down list, e.g. Termennetwerk or External thesaurus. |
| 3. | Click the Link screen entry field to select a link screen for this external source. For Collections a link screen is optional: if not specified, a thesaurus link screen will be used. You may want to create a link screen especially for an external source though. The link screen must contain a small number of Axiell field tags (say 1, 2 or 3 tags) in a row with the associated labels above (!) each field. So a link screen contains only two lines of screen elements: the top line consists of labels for the field tags below them in the second line. Collections doesn't display this screen like other normal record screens in an application: the link screen is converted to the View table tab in the Find data for the field... window: with the labels on the link screen you specify the column headers, and with the field tags the contents of the columns on that tab. The tags that you place on the link screen must be Axiell field tags from the linked database, whose field names match the field names from the Adlib XML returned by the external source after XSLT transformation; if you do not use the Dutch Termennetwerk gateway, you may have to set up a local web service using a custom XSLT stylesheet to transform the source XML before Axiell Collections takes control over the XML output. Whenever the user searches for a term in this external source, the View table tab offers the user a list of terms to choose from. |
| 4. | If you wish, you can provide more external thesauri for this linked field by repeating these steps. |
The Advanced button and its functionality is not applicable to Axiell Collections.
(See the Axiell Collections Help for more information about the external sources functionality from a user's point of view.)