Reference field
The Reference field is used to refer to values of fields in other documents within the same document system.
The differences between a Reference Field and an Autocomplete field:
- The AutoComplete field persists the label of the referenced document. This in opposition to the reference field type that stores the referenceId to the document. In other words; there isn't a link between the Autocomplete field and the referenced document.
- The AutoComplete field allows free textual input.
For example: There is an Order document that holds information on the number of purchased items per company. Because companies are also used in other processes, it has it's own Document Definition and therefore each company is a document itself. With the help of a Reference Field, the Order document can make use of the information stored in a Company Document. When information changes within the Company Document, this information also changes in the Order Document.
Properties
| Setting | Required | Description |
|---|---|---|
| Label | Yes | The label is used for users of BizzStream. The label is shown in documents left to the value of the field. Labels can always be edited. |
| Translation key | No | Can be used to replace the field label with a translation. If set, BizzStream will try find the translation associated with the key set in this field. If no translation can be found, the label set in the Label field will be used. |
| Name | Yes | The name is a BizzStream system field. Once the Document Definition is persisted, this field cannot be edited anymore. Unless there are no documents based on this document definition. |
| Required | No | By checking the required-option, you force the user to fill out the field. By not checking this option, the option to fill out the field is to the discretion of the user. |
| Reference type | Yes | This field dictates whether there are references to one or more documents. If you refer to only one document you have to choose the one-on-one (1-1) option. If you refer to more documents please choose the one-to-more (1-N) option. |
| Related Document | Yes | Choose the Document Definition you want to refer to. Note that you can’t remove a Document Definition if it’s referenced to by another Document Definition. |
| Reference Label | Yes | The reference Label dictates how a label is set up. You can specify the field from the Document Definition you are referring to. You can use a BizzStream Expressions to set this up. For example you can use {!target.name!} |
| Filter | No | It is possible that the document to which you refer has to meet certain criteria for its characteristics. You can force this by using a filter. This field can contain BizzStream Expressions. For example you can use {!target.projectName!} == {!source.projectName!}You can also use currentUser expression, see System Expressions |
| Search Method | Yes | The 'Search Method' refers to how you search for the reference field. The options are contains, begins with and ends with |
| Sort Field | No | Select the field that is used to sort the suggestions. By default the suggestions don't get sorted. |
| Sort Order | No | Select here whether you want to sort the suggestions ascending or descending. |
| Validate Reference Field | No | Because sometimes it's unnecessary to validate all reference fields in a document when the document is saved, you have the option to validate only the fields that actually have been updated. |
| When a Related Document is deleted | Yes | When a Related Document is deleted you have three options 1. Prevent Deleting: the referred document cannot be deleted. 2. Delete this Document: the document that contains the reference will be completely deleted. 3. Delete Reference: the reference to this document will also be deleted. |
| Initial Value | No | By providing an initial value to the field, upon creation the field or linefield will have this value. This field cannot refer to values placed in other fields. A user/visitor can overwrite this value. |
| Initial Placeholder | No | When you provide an initial placeholder, the field will get the value of the field to which the placeholder refers. Users/visitors can update this value. Unlike placeholders, the field will not updated when the field to which the placeholder refers updates. This field can contain BizzStream Expressions referring to other fields. |
| Placeholder | No | By providing a placeholder, you ensure that the value of this field is replaced by the value of the field to which the placeholder refers when the referenced field updates. |
How the data is stored
Reference fields will be saved accordingly in the database:
A one-to-one (1-1) reference is saved in the database by using the BizzStream ID of the referred document:
referenceField:"3RTajydsHnJDTSg8v"
A one-to-many (1-N) reference is saved in the database by using the collection of BizzStream IDs of the referred document:
referenceField:["3RTajydsHnJDTSg8v","eNhwNaTRo9MDqCJhR"]
Connection between reference and access groups
"Type" and "Referenced document" fields can't be changed in settings when your access groups contain related access group members. You can read more about related access group here
Finding Documents using QR Codes
On mobile devices, it is possible to enter the search text of a reference field by scanning a QR code. This is particularly usefull when documents have reference labels that are very similar (say a 10 digit identification code). If you use a QR code to enter the search text, you elimnate the changes of typing errors.
To enable this functionality in a layout,
- Open a document page or search layout
- Click on a reference field so that you can see its properties
- Check the Enable QR Scanner on Mobile Devices checkbox
- Save the layout
When opening a document of overview filter, a user will see a QR code icon (
) next to the reference field. A user can open the QR code scanner by clicking on the icon. After scanning the QR code, a pane will open and the search field contains the text found in the QR code.
Filtering or selecting documents in a Reference Field using a QR Shortcut
On mobile devices, it is possible to set a filter on a reference field by scanning a QR code. To do this, administrators first need to enable this functionality in an overview layout:
- Open a document page or search layout
- Click on a reference field so that you can see its properties
- Set the property QR Scan Mode, there are two modes: Filter and Select.
- Save the layout
When opening the overview layout, a user will see a QR code icon () in the mobile toolbar.
In the document page layout the QR code icon will be showed next to the reference field.
The user can open the QR code scanner by clicking on the icon.
After scanning the QR code, it depends on the QR Scan Mode what will happen:
- Filter : A pane will open and the search field contains the text found in the QR code.
- Select : BizzStream will automatically search for the document based on the text found in the QR code, first it will look for an exact match. If there is no document found it will search based on the search mode set in the reference field. The found document will in case of a 1-1 reference field: replace the current value, and in case of a 1-N reference field add the found document to the values.
Using a Search Layout on desktop browser or mobile
In case a search layout has been specified in the layout editor, the user has extended search options in the reference field.
Only documents that pass the filter of the reference field are displayed in the search layout. The filter fields of the search layout can be used to filter within the documents that meet the filter criterea.
Desktop browser
For the desktop browser the regular search icon in a reference field is replaced by a clickable search layout icon 
.
The default functionality of searching in a reference field is still available. If a user clicks the search layout icon a popup will open with the specified Overview Grid layout, the user can use this grid to filter (if specified) and sort just like the regular Overview Grid Layout.
In case of a 1-1 reference field, the user can select only one value. In case of a 1-N reference field, the user can select multiple values. In both cases the selected values will be atop the grid, even if they don't match the filter or sorting. When the user clicks Ok, the value(s) will be transferred to the reference field.
Mobile application
For the mobile application a search layout will be shown if specified in the layout editor. The user can use the regular Overview Grid layout functionality like sorting and filtering. The user can select by swiping to the right and vice versa. When the user clicks the back button, the value(s) will be transferred to the reference field.