Fields and Line Blocks
Fields and line blocks are key components of a document definition in BizzStream Aero. Fields represent individual data elements, while line blocks are used to group fields together in a structured manner, often to handle multiple entries or list data.
Adding and Configuring Fields
To add fields in a document definition, follow these steps:
- Open the Fields and Lines tab in the document definition editor.
- Click the Add Field button and provide the necessary details in the right-hand column.
- Select a Type for the field, and configure its specific properties based on the chosen type.
Adding Line Blocks and Line Fields
Line blocks are used to represent structured data with multiple entries, such as a table or a grid. Line fields are fields that belong to line blocks and are used to capture data within each entry.
Example
Consider an invoice document. It typically includes header information like the recipient's name, invoice date, and address. In addition to this, an invoice may contain detailed information about individual costs incurred, such as call details for a phone bill. For such cases, line fields are created within a line block to accommodate the tabular representation of the cost details.
To add line blocks and line fields:
- Open the document definition editor and navigate to the Fields and Lines tab.
- Click the Add Line Block button to create a line block, and provide the necessary details in the right-hand column.
- Within the line block, click the + icon to add line fields and define their properties.
Line fields are specifically designed to handle list data within controls such as tables or grids.
Default Field Properties
BizzStream Aero provides various field types that enable administrators to define the required information format within documents. Each field type has a set of default properties that can be further customized. Here are the common properties shared by all fields:
| Property | Required | Purpose |
|---|---|---|
| Label | Yes | The label represents the field's name or description and is what end users see when viewing a document. |
| Name | Yes | The name serves as a unique identifier for the field within a document definition. It is used to reference and manipulate the field programmatically. |
| Type | Yes | The field type defines the characteristics and behavior of the field, such as text, number, date, or dropdown selection. |
| Active | No | This property allows a field to be deactivated if it's no longer needed, while preserving historical data. |
| Required | No | Indicates whether the field requires data entry from the end user. If a required field is left empty, the document cannot be saved. |
| Explanation | No | An optional field that provides additional guidance or instructions to end users about the expected input for a particular field. |
| Initial Dynamic Value | No | This property allows setting an initial value for a new document or document line. It can be defined using dynamic BizzStream expressions to make the value context-sensitive. Note: Not applicable for fields of type Attachment, Geolocation, Signature, or Chat. |
| Dynamic Value | No | This property enables setting or calculating a value based on another field's value. Note: Not applicable for fields of type Attachment, Geolocation, Signature, or Chat. |
By customizing these properties, administrators can tailor the behavior and functionality of fields and line blocks to meet their specific requirements.
Field types
BizzStream Aero supports a wide range of field types, each with its own unique properties that allow for fine-grained control over data input validation. By strictly defining what data is allowed, administrators can ensure accurate data capture and enable seamless data flow. Let's explore the different field types and their configurations:
Text
The text field is used to represent textual values in documents. It stores the input as a string value.
Properties
| Property | Required | Purpose |
|---|---|---|
| Maximum length | Yes | Specifies the maximum number of characters allowed for the field. The default value is 150. |
| Number of lines | Yes | Defines the number of lines the text field can use. If no value is entered, it will be a single-line control. |
Number
The number field is used to represent numerical values in documents. It stores the input as an integer.
Properties
| Property | Required | Purpose |
|---|---|---|
| Decimals | Yes | Specifies the number of decimal places to display or allow. The default value is 2. |
| Minimum Value | No | Defines the minimum value allowed for the field. |
| Dynamic Minimum | No | Sets the minimum value based on a condition or another field's value. |
| Maximum Value | No | Defines the maximum value allowed for the field. |
| Dynamic Maximum | No | Sets the maximum value based on a condition or another field's value. |
| Step | Yes | Specifies the increment or decrement step when using the picker. The default value is 1. |
| Enforce Step | No | Only allows inputs that match the defined step. For example, if the step is 5, only multiples of 5 will be allowed. |
| Prevent Entering values Outside Range | No | Restricts values to fall within the (dynamic) minimum and maximum range. |
Date
The date field is used to represent date values in documents. It stores the input as a string value.
Properties
| Property | Required | Purpose |
|---|---|---|
| Minimum Value | No | Defines the minimum date value allowed. |
| Dynamic Minimum | No | Sets the minimum value based on a condition or another field's value. |
| Maximum Value | No | Defines the maximum date value allowed. |
| Dynamic Maximum | No | Sets the maximum value based on a condition or another field's value. |
| Disabled days | No | Excludes selected days of the week from the date picker. |
Time
The time field is used to represent time values in documents. It stores the input as a string value.
Properties
| Property | Required | Purpose |
|---|---|---|
| Minimum Value | No | Defines the minimum time value allowed. |
| Dynamic Minimum | No | Sets the minimum value based on a condition or another field's value. |
| Maximum Value | No | Defines the maximum time value allowed. |
| Dynamic Maximum | No | Sets the maximum value based on a condition or another field's value. |
| Interval | Yes | Specifies the number of minutes by which the time value increments or decrements when using the picker. The default value is 15. |
| Enforce Interval | No | Only allows inputs that match the defined interval. For example, if the interval is 5, only times rounded to 5-minute intervals will be allowed. |
Checkbox
The checkbox field represents a boolean value (true/false) in documents. It does not have any special properties. In a layout, the checkbox field can also be rendered as a switch control.
Reference
The reference field is used to refer to a field value in another document. It allows administrators to create dynamic models where updates to referenced documents are automatically reflected in the reference field value. References can be made to documents in other document definitions or within the same document definition.
Properties
| Property | Required | Purpose |
|---|---|---|
| Reference Type | Yes | Specifies whether there are references to one or more documents. For references to a single document, select the one-on-one (1-1) option. For references to multiple documents, choose the one-to-many (1-N) option. |
| Document Definition | Yes | Specifies the document definition to refer to. Note that it's not possible to remove a document definition if it's referenced by another document definition. |
| Reference Label | Yes | Defines the label to be displayed for the options in the reference list. BizzStream text expressions can be used for dynamic labels. For example: {{F["name"]}} - {{F["code"]}}. |
| Filter | No | Filters the list of options available to the user based on a BizzStream filter expression. For example, only show documents with a particular status. |
| Search Method | Yes | Specifies how the user can search the options. It can be set to "contains," "starts with," or "ends with." |
| Sort Field | No | Determines the sorting order of the options presented to the user. The options are sorted based on the selected field's values within the referenced document. |
| Sort Order | Specifies whether the sorting order is ascending or descending. | |
| Validate Reference Field | No | Determines whether to validate only the reference fields that have been updated when saving the document. This option avoids unnecessary validation of all reference fields. |
| When a Related Document is deleted | Yes | Specifies the behavior when a referenced document is deleted. Options are: (1) Prevent deletion, (2) Delete the document containing the reference field, or (3) Delete the reference. |
Tips
The reference field is a very commonly used field. Often reference fields will be automatically filled by a dynamic value. This can be done in the following ways:
- Provide the
_idof the document. E.g.1234567890abcdefinds the document with that _id. - Use a BizzStream expression with a filter to find the correct document. E.g.
FILTER("items","code = 500")finds the document(s) in the "items" document definition for which the code field has value "500".
Autocomplete
The autocomplete field provides suggestions to the user based on the field label of the referenced document. It functions similarly to a reference field but does not establish a direct link between the autocomplete field and the referenced document. The autocomplete field persists the label of the referenced document as a string value, whereas the reference field stores the document ID of the referenced document. Unlike a reference field, updates to the referenced document do not affect the autocomplete field's value. The autocomplete field also allows free-text input.
Properties
| Property | Required | Purpose |
|---|---|---|
| Reference Type | Yes | Specifies whether there are references to one or more documents. For references to a single document, select the one-on-one (1-1) option. For references to multiple documents, choose the one-to-many (1-N) option. |
| Document Definition | Yes | Specifies the document definition to refer to. Note that it's not possible to remove a document definition if it's referenced by another document definition. |
| Reference Label | Yes | Defines the label to be displayed for the options in the reference list. BizzStream text expressions can be used for dynamic labels. For example: `{{F["name"]}} - {{F["code"]}} |
| Filter | No | Filters the list of options available to the user based on a BizzStream filter expression. For example, only show documents with a particular status. |
| Search Method | Yes | Specifies how the user can search the options. It can be set to "contains," "starts with," or "ends with." |
| Sort Field | No | Determines the sorting order of the options presented to the user. The options are sorted based on the selected field's values within the referenced document. |
| Sort Order | No | Specifies whether the sorting order is ascending or descending. |
| Allow Free Input | No | If checked, allows end users to provide their own input as a field value. |
Picklist
The picklist field allows users to choose from a fixed list of options.
Properties
| Property | Required | Purpose |
|---|---|---|
| Values | No | Specifies the values the user can choose from. |
Attachment
The attachment field can be used to attach additional information to a document such as images, photos, text documents or other files. All file types are supported.
Note:
- Please be aware that some browsers may block downloads. For instance, Chrome shows the popup blocker icon when downloads are blocked.
- When uploading attachments on a mobile device, ensure that the app remains in the foreground until all uploads are completed. If the app is closed, the mobile operating system may terminate the upload.
- Attachments have a maximum file size of 5 GB.
Properties
| Property | Required | Purpose |
|---|---|---|
| Maximum Attachments | No | Specifies the maximum number of files that can be added to the field. If no value is specified, there is no limit. |
| Maximum File Size (MB) | No | Specifies the maximum file size for each individual file in megabytes. |
| Maximum Image Width (px) | No | Resizes images to the specified maximum width in pixels while maintaining the aspect ratio. |
Geolocation
The Geolocation field type represents a location using longitude and latitude coordinates in documents. This field allows you to plot the locations on a map.
Although the geolocation field does not have any special configuration options, it supports an optional formattedAddress field. This field can store the address associated with the location, either entered manually or generated through geocoding. For more details, refer to the Geolocation Control (Web) documentation.
Signature
The signature field allows users to add signatures to documents. This field type does not have any special properties.
The email field is used to represent email addresses in documents. It validates whether the input matches a valid email address.
Properties
| Property | Required | Purpose |
|---|---|---|
| Maximum length | Yes | Specifies the maximum number of characters allowed for the field. The default value is 150. |
Setting Field Permissions
Most of the time, you will configure field permissions when configuring an access group tab. However, in the Fields & Lines tab, you can also configure field permissions as long as there is at least one access group. To set field permissions in this tab, do the following:
- Single-click the field you want to configure permissions for.
- Click the Add permissions button.
- Now you can set permissions for the selected field per access group per status.
