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.
|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
|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
You can also use
|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:
A one-to-many (1-N) reference is saved in the database by using the collection of BizzStream IDs of the referred document:
QR codes in mobile reference and autocomplete
In some cases, reference fields may point to documents that have reference labels that are very similar (say a 10 digit identification code). If users enter this code manually, there is a high risk of typing errors. This can be reduced by completing reference fields by scanning a QR code.
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.
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.
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.