Articles in this section

Field Parameters

Avatar
Mark Edwards
  • Updated
Follow

Overview

Field Parameters control how a Field behaves, how its value is entered or calculated, and how it is displayed and used elsewhere in an App.

Some Field Parameters are essential because they define the Field’s identity, data type or core behaviour. Others are optional and can be configured when a specific business requirement applies.

The parameters available depend on the selected Field Type. Some parameters, such as Identifier and Type, are essential when creating a Field. Label is commonly used to identify a Field to users, but it is not always required. For example, a Label may be left blank when an Embedded Report does not need a heading or when an Action Field displays an image without text above the button.

Other parameters, such as Description, Default Value, validation rules, formatting and display options, are optional.

This article explains the purpose and effect of each Field Parameter. For guidance on creating a Field, see Adding and Editing Fields. For help choosing the appropriate Field Type, see Field Types.

Essential and Optional Parameters

Not every Field Parameter needs to be configured for every Field.

Essential Parameters

The following parameters are generally essential when creating a Field:

  • Identifier: Provides the unique system reference used by Expressions, Workflows, Reports, Templates and integrations.
  • Type: Determines the kind of data the Field stores and the controls available to users.

Label is commonly used to identify the Field to users, but it is not essential in every scenario. It may be left blank where the Field does not need a heading or where another visual element already communicates its purpose.

Examples include:

  • An Embedded Report that should appear without a heading above it.
  • An Action Field that uses an image as its button and does not need text displayed above the image.

Some Field Types also require additional configuration. For example:

  • A Selection Field requires a Select List.
  • A Range Field requires minimum and maximum values.
  • A Reference Field requires a Reference App.
  • A Grid Field requires DataSets and SubFields.
  • An Image List Field requires an Image List.
  • A Field using Auto Number requires an appropriate Next Auto Number.

Optional Parameters

The following parameters are optional and should be configured when they support a specific requirement:

  • Label, where a user-facing heading is needed.
  • Description
  • Required
  • Read Only
  • Default Value
  • Process Default Value as Expression
  • Expression
  • Validation rules such as Length, Pattern, Min Value and Max Value
  • Formatting options
  • Named Styles
  • Free Text Quick Filter
  • Title Field
  • Templated Record Copy exclusions
  • Field Type-specific display or behaviour options

Optional does not mean unimportant. A parameter may be optional when creating a Field but essential to the way it should work within a particular business process. For example, a Status Field may require a Default Value to ensure that every new Record starts in a valid state.

Basic Information

Label

The Label is the user-facing name of the Field.

It can explain what information the Field contains or what the user needs to enter. The Label may appear alongside the Field in Records, Templates and Reports.

A Label can contain spaces and other display characters.

A Label is optional in some scenarios. It may be left blank when the Field does not need a visible heading, such as:

  • An Embedded Report that should appear without a heading above it.
  • An Action Field that uses an image as its button and does not need text displayed above the image.

Where a Label is populated, it should clearly explain the purpose of the Field.

Identifier

The Identifier is the unique system reference for the Field. It is used when referring to the Field in areas including:

  • Expressions
  • Workflows
  • Reports
  • Templates
  • Imports and exports
  • APIs

The Identifier is an essential parameter.

The Identifier:

  • Must be unique within the App.
  • Must start with a letter.
  • Must contain only letters and numbers.
  • Must contain at least three characters.

The Identifier cannot contain spaces or other unsupported characters. For example:

Project Owner

is invalid because it contains a space. The valid Identifier would be:

ProjectOwner

When a Field is created, Softools suggests an Identifier based on the Label by removing spaces and unsupported characters. If the Label is blank, enter an appropriate Identifier manually.

Important: A Field Identifier cannot be changed after the Field has been created.

If an incorrect Identifier is used, the Field must be deleted and recreated. Any Expressions, Workflows, Reports, Templates, imports, integrations or other dependencies using the original Identifier must then be updated.

Choose an Identifier that is clear, concise and likely to remain appropriate throughout the life of the App.

Type

The Type determines the kind of data that the Field stores and the controls available to users.

Type is an essential parameter because it determines which other Field Parameters are available and how the Field behaves.

Examples include:

  • Text
  • Number
  • Date
  • Selection
  • Document
  • Grid
  • List
  • Reference

A Field Type can only be changed when the existing and new Types are compatible. The supported changes are:

Current Field Type Can be changed to
Email Literal, Long Text or Text
Literal Long Text or Text
Long Text Literal or Text
Person Person By Team
Person By Team Person
Text Literal or Long Text

Other Field Types cannot be changed after the Field has been created.

Existing Field data is retained when changing between compatible Types. However, changing a Type may alter how the value is displayed or used. Review any Templates, Reports, Expressions, Workflows, imports and integrations that depend on the Field before making the change.

For guidance on choosing a Type, see Field Types.

Description

The Description explains the purpose of the Field to both App Builders and Workspace users. It is available for every Field Type.

Description is optional, but it is recommended where users or App Builders may need additional guidance.

In the Workspace, a user can access the Description by hovering over the Field Label and selecting the information (i) button that appears. If the Field has no Label, the Description may not be accessible in the same way, so use a Label where users need to access Field guidance through the Workspace.

A useful Description might explain:

  • What information the user should enter.
  • Where the information can be found.
  • Why the information is required.
  • Any format or conventions the user should follow.
  • How the value is populated or calculated.
  • Which other Fields or processes depend on it.

Descriptions are particularly useful when a Label alone cannot provide enough guidance. They also help other App Builders understand how the Field is intended to work.

 

Data Entry and Field Behaviour

Required

Enable Required when the Record must contain a value in the Field before it can be created or updated.

Required is optional. Enable it when the information is essential to the business process, reporting or subsequent automation.

Required is checked whenever a Record is saved. If a required Field does not have a value, the Field is shown in red and a message indicates that a value is needed. The Record cannot be saved until a value is entered. This also applies when an existing value has been cleared.

Avoid making Fields required simply because the information could be useful. Consider whether the user will always have the information available at that stage of the process.

When updating Records through an import, required Field validation is applied differently depending on the Field’s existing value and whether the Field is included in the CSV:

  • If the required Field already contains a value, the import cannot clear it by supplying a blank value.
  • If the required Field was previously blank and is included in the CSV without a value, the import does not fail because of the required validation.
  • If the required Field is not included in the CSV, the import can still update other Fields without triggering a required validation error for the omitted Field.

This means that imports can update selected Fields without requiring every required Field to be included in the CSV. However, an existing value in a required Field cannot be removed through an import.

Read Only

Enable Read Only when users should be able to see the Field but should not be able to enter or change its value manually in the Workspace.

Read Only is optional and should be used when the value is controlled by another process or should not be changed by Workspace users.

Read Only controls editing through the user interface. It does not prevent the Field from being updated through other supported methods, including:

  • Imports
  • Workflows
  • APIs
  • Expressions

Fields containing an Expression are displayed as read-only because their values are calculated rather than entered manually.

Note: Read Only is different from user permissions. It controls whether the Field can be edited through the Workspace interface, not whether the underlying value can be updated by another process.

Default Value

The Default Value determines the initial value assigned to a Field when a new Record is created.

Default Value is optional, but it is useful wherever the App can sensibly predict the value most users will need.

For example, a new Action could begin with:

  • Status: Open
  • Priority: Normal

These are static Default Values. They can be displayed as initial values while the user is creating the Record, unless the user enters a different value.

Values such as the current date or the person creating the Record should instead be configured using Process Default Value as Expression. These values are calculated when the Record is created and are not displayed while the user is completing the new Record. They are applied only if the user has not entered a value.

Appropriate Default Values can:

  • Save users time and make Records faster to create.
  • Reduce uncertainty and input errors.
  • Improve ownership and accountability.
  • Reduce missing data and provide a more complete dataset for reporting.
  • Make the App easier for new users to understand and adopt.

Choose a Default Value that is appropriate for most new Records. Avoid setting a value simply to populate the Field if users are likely to overlook it or if it could make the Record misleading.

The value must be appropriate for the selected Field Type. For example:

  • A Number Field requires a numeric value.
  • A Text Field requires text.
  • A Bit Field uses a Boolean value.
  • A Selection Field requires a value from its Select List.

A suitable Default Value should also be configured for Field Types that expect a valid option. For example:

  • A RAG Multi-State Field could default to Unset.
  • A Harvey Ball Multi-State Field could default to 0%.
  • An Image List Field could default to one of its configured Image List values.

For a Literal Field, Default Value has a different purpose. It contains the text or HTML displayed wherever the Literal Field is referenced in a Template.

A Default Value is applied only when the Record is created. It is not applied again when the Record is subsequently updated.

If the user enters a value before the Record is created, their value takes precedence over the Default Value.

For more guidance, see Better Data, Clearer Ownership and Faster Records with Default Values.

Process Default Value as Expression

Enable Process Default Value as Expression when the initial value needs to be calculated when a new Record is created.

This is optional and is useful when the starting value should reflect the user, date or other information available at the point of creation.

Typical uses include:

  • Setting Date Raised to the current date.
  • Assigning the person creating the Record as the initial owner.
  • Creating an initial value from information already entered.
  • Populating a value inherited from a related process.

Unlike a static Default Value, a processed Default Value is not displayed while the user is completing the new Record. The expression is evaluated when the user creates or saves the Record. The calculated value is then assigned only if the user has not entered a value in the Field.

For example:

  • Date Raised: The expression can set the value to the current date when the Record is created.
  • Action Owner: The expression can set the value to the person creating the Record when the Record is created.

If the user enters a different value before creating the Record, their value takes precedence over the calculated Default Value.

After creation, the Field behaves like a normal entered value. The Default Value expression is not evaluated again when the Record is updated or when values used in the original calculation change.

Use the normal Expression parameter instead when the Field must remain calculated and should update whenever its dependencies change.

Requirement Appropriate option
Every new Action starts as Open Default Value
Every new Action starts with Normal priority Default Value
Date Raised is set to the current date when the Record is created, if the user has not entered a value Process Default Value as Expression
Action Owner is set to the person creating the Record when the Record is created, if the user has not entered a value Process Default Value as Expression
Total Cost changes whenever Quantity or Unit Cost changes Expression
Status changes when an approval is completed Workflow

Expression

An Expression calculates the value of a Field using values from the current Record or other supported data sources.

Expression is optional, but it is required when the Field value must be calculated rather than entered manually.

Expressions can be used to:

  • Calculate financial values.
  • Determine a status.
  • Combine text.
  • Calculate dates.
  • Populate information from related Records.
  • Apply business logic.

A Field containing an Expression is read-only in the Workspace because its value is controlled by the calculation.

Expressions are recalculated when their dependencies change. This differs from a processed Default Value, which is calculated only once when the Record is created.

For detailed guidance, see the Expressions (NCalc) section.

Validation Parameters

Validation Parameters restrict the values users can enter. They are optional unless the business process requires a specific format or range.

The available options depend on the Field Type.

Length

Length sets the maximum number of characters that can be entered into supported text-based Fields.

Length is optional. Use it where the target system or business process requires a specific maximum length.

For example, an external system might only accept a reference containing up to 20 characters.

Minimum and Maximum Values

Min Value and Max Value restrict numeric input to a defined range.

These parameters are optional for most numeric Fields but essential for Range Fields because they determine the scale available to the user.

For example:

  • A percentage score might allow values from 0 to 100.
  • An audit score might allow values from 1 to 5.
  • A quantity might require a minimum value of 0.

If a user enters a value outside the permitted range, the Record cannot be saved until the value is corrected.

Pattern

A Pattern uses a regular expression, commonly called Regex, to control the format of text entered by the user.

Pattern is optional. Use it when the Field must follow a defined format.

Patterns can be used to validate values such as:

  • Email addresses
  • Telephone numbers
  • URLs
  • Reference numbers
  • Values containing only permitted characters

The entered value must match the Pattern. If it does not match, the configured validation error is displayed.

Softools provides preset Patterns, and App Builders can also enter a custom Pattern.

For example:

Email:

^.+\@.+$

Telephone number:

^\+?(\d.*){3,}$

URL:

^((https?|ftp|file):\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$

For help creating and testing Patterns, see Patterns (Regex).

Error Message and Validator

When configuring a Pattern, provide a clear Error Message explaining what the user needs to correct.

These are optional parameters, but an Error Message is strongly recommended whenever a Pattern is used.

For example:

Enter an email address ending in @softools.net.

This is more useful than displaying the Regex itself or a generic message such as “Invalid value”.

Use the available Validator to test expected valid and invalid examples before publishing the App.

Rows

Rows controls the initial height of supported multi-line text Fields, including Long Text.

Rows is optional. It affects the amount of text visible when the Field is first displayed but does not restrict the amount of text that can be entered.

Choose a size appropriate to the expected response. A short explanation may need three or four Rows, while detailed meeting notes may benefit from a larger entry area.

Formatting and Display

Formatting and display parameters are optional. Configure them when users need a particular presentation, editing experience or visual style.

Number Formatting

Number Formatting controls how a numeric Field is presented without changing its underlying value.

It is available for:

  • Money
  • Number
  • Integer
  • Long

Options include:

  • Currency
  • Percent
  • Digit grouping
  • Minimum decimal places
  • Maximum decimal places
  • Prefix
  • Suffix

Number Formatting can display a value such as:

12500.5

as:

£12,500.50

The user can still select the displayed value to edit the underlying number.

Number Formatting is generally the preferred option where a numeric value needs to remain editable.

It can also be used in supported Word exports, Workflow emails and Workflow expressions.

Format String

A Format String creates a formatted text representation of a Money, Number, Integer, Long, Date or DateTime Field.

Format String is optional. Use it when a separate formatted text value is required or when more customised Number, Date or DateTime formatting is needed.

When a Format String is added, Softools creates a separate backing Field using the original Identifier followed by _Formatted.

For example:

InvoiceAmount

creates:

InvoiceAmount_Formatted

The formatted backing Field can be used in:

  • Records
  • Templates
  • Reports
  • Expressions
  • Exports

For example, the Format String:

{0:N2}

could display:

12500.5

as:

12,500.50

Display Formatted

Enable Display Formatted to display the _Formatted backing Field value wherever the original Field is shown on screen, including in Records and Reports.

Display Formatted is optional. Use it when the value should be presented in its formatted form but should not be edited directly.

The displayed value is read-only because it is the formatted text representation rather than the editable underlying value.

If users need to view a formatted numeric value and select it to edit the underlying value, use Number Formatting instead.

For full guidance and examples, see Field Formatting.

Named Styles

Named Styles apply a predefined style to a component, Field Label or Field value.

Named Styles are optional. Use them when a Field or its surrounding component needs a consistent visual treatment or when visual emphasis improves usability.

Depending on the selected predefined Style, it can affect:

  • Font size
  • Font weight
  • Text colour
  • Background colour
  • Alignment
  • Whether the component appears as a Read Only Rectangle or Rounded Rectangle

A Named Style can be applied to:

  • The whole component
  • The Field Label
  • The Field value

This allows the same Field to have different styling applied to its overall component, Label or value.

Styles can also be applied at Template, Form, Report, App or Site level. A Field-level Style takes priority over Styles applied at a higher level.

For more information, see Styles.

Search, Titles and Record Copies

These parameters are optional and should be configured when the Field has a specific search, identification or copying requirement.

Include in Free Text Quick Filter

Enable Include in Free Text Quick Filter to include the Field value in the searchable text stored against the Record.

Use it for information users are likely to search, such as:

  • Names
  • Reference numbers
  • Organisations
  • Email addresses
  • Key descriptions

When a user enters text into a Report’s Free Text Quick Filter, Softools searches this combined value and returns matching Records.

Any update to a Record rebuilds its searchable text using the current values of all Fields that have this parameter enabled.

Existing Records: Enabling this parameter does not immediately add existing Field values to the searchable text. Each existing Record must be updated. This can be done through a normal Record update or, where appropriate, a controlled export and re-import.

For Document Fields, the document name can be included in the searchable text. The contents of the uploaded document are not searched.

Is Title Field

Enable Is Title Field to use the Field value as the primary title for Records in the App.

This parameter is optional, but it is recommended that every App has a clear Title Field so users can identify Records easily.

The Title Field is used in locations including:

  • The breadcrumb when a Record is open in the Workspace.
  • The title displayed on default App Home cards.
  • Pop-Up Templates.
  • Other locations where Softools needs a recognisable title for the Record.

Only one Field can be configured as the Title Field for an App.

The following Field Types can be selected:

  • Email
  • Literal
  • Long Text
  • Text

A Text Field is normally the most appropriate choice. If the title needs to contain several values, use a Text Field with an Expression that combines them.

For example:

[ProjectCode] + " - " + [ProjectName]

could produce:

PRJ001 - Customer Portal

Although a Literal Field can currently be selected as the Title Field, this is not normally recommended.

 

Exclude This Field From Templated Record Copies

Enable Exclude This Field From Templated Record Copies when the Field value should not be carried into a new Record created using Template Copy.

Use it for values that should be unique or reset for every new Record, such as:

  • Approval dates
  • Signatures
  • Uploaded Documents
  • Completion information
  • Unique external references
  • Process-specific statuses

When the parameter is not enabled, the Field value can be included when a Templated Record Copy is performed.

This parameter affects Templated Record Copies. It does not define the behaviour of every other method of creating or copying a Record.

Field Type-Specific Parameters

Some parameters are available only for particular Field Types. These parameters are optional unless the selected Field Type requires them for its configuration.

Action

Action Fields provide a button that performs a configured action.

  • Action Type: Determines the action performed when the user selects the button.
  • Confirmation Message: Displays a message requiring the user to confirm the action before it proceeds.
  • Size: Controls the displayed size of the Action button.
  • Image: Selects the image displayed on the button.

Action Type is essential for an Action Field. Confirmation Message, Size and Image are optional.

A Label may be left blank when the Action Field is intended to display an image without a heading above the button.

Aggregate

Aggregate Fields calculate a summary value using related Record data.

  • Reference Field: Selects the numeric Field on which the aggregation is performed.
  • Summary Expression: Defines the calculation performed across the values in the Reference Field.
  • Filter: Restricts which related Records are included in the calculation.

Reference Field and Summary Expression are essential to define the aggregate calculation. Filter is optional.

Barcode

Barcode Fields capture data by scanning supported barcode formats.

  • Barcode Formats: Determines which barcode formats the scanner will accept.
  • Barcode Valid Code: Defines the code used to validate the scanned value.

Barcode Formats are essential to define what can be scanned. Barcode Valid Code is optional and should be used when scanned values require validation.

Date and DateTime

  • Show Calendar Event: Provides an option to download the Date or DateTime value as a calendar event so that it can be added to the user’s calendar.

Show Calendar Event is optional. When enabled, users can download the calendar event and add it to their preferred calendar application.

Document

  • File Type Restriction: Restricts uploaded Documents to the permitted file types.

File Type Restriction is optional. Maximum upload size is controlled by a site-level policy and is not configured through the Document Field.

Draw

  • Canvas Size: Controls the size of the area available for drawing or capturing a signature.

Canvas Size is optional.

Email

  • Link Text: Controls the text displayed for the clickable email link. Link Text prevents users from entering a value manually, so use it when the email address is populated by another process, such as an Expression, Workflow, import or integration.

Link Text is optional.

An Email Field can be changed to a Literal, Long Text or Text Field.

Embedded Report

Embedded Report Fields display a Report from an App within a Record.

  • Embedded App: Selects the App containing the Report.
  • Embedded Report: Selects the Report to display.
  • Height: Controls the displayed height of the embedded Report.

Embedded App and Embedded Report are essential. Height is optional.

A Label may be left blank when the Embedded Report should appear without a heading above it.

Embedded Template

Embedded Template Fields display a Template from an App within the current Record.

  • Source: Select from Parent App, Current App or App Level Template or Reference Field
  • App: Selects the App containing the Template (unless current app or reference field in which case App is based on the App the reference field refers to in which case the property is hidden).
  • Template: Selects the Template to display.
  • Hide When Unavailable: Hides the Embedded Template when it is not available to the user.
  • Show Header: Determines whether the Template header is displayed.
  • Frame Width: Controls the width of the frame containing the Template.

App and Template are essential. Hide When Unavailable, Show Header and Frame Width are optional.

Grid

Grid Fields contain defined DataSets and SubFields arranged as rows and columns.

  • Orientation: Determines whether the DataSets or SubFields are displayed horizontally.
  • Hide Grid Row Title: Hides the applicable row labels to provide more space for the Grid data.
  • DataSets: Defines the repeated categories or groups within the Grid.
  • SubFields: Defines the data captured across each DataSet.
  • Column Sizes: Controls the displayed width of Grid columns.
  • Click to Edit: Allows supported formatted values to be displayed clearly and selected for editing.

DataSets and SubFields are essential to define the Grid. Orientation, Hide Grid Row Title, Column Sizes and Click to Edit are optional.

For full configuration guidance, see Grid.

Image

  • Available Offline: Makes the Image available when the App is being used offline.

Available Offline is optional.

Image List

  • Image List: Selects the configured list containing the images and corresponding values available to users.

Image List is essential for an Image List Field.

Set a Default Value so the Field begins with a valid Image List option where required.

In-App Chart

  • In-App Chart Report: Selects the configured Chart Report displayed within the Record.

In-App Chart Report is essential for an In-App Chart Field.

List

List Fields contain a variable number of rows with one or more configured columns.

  • Default Sort By: Selects the column used to sort List rows initially.
  • Default Sort Order: Determines whether the initial sort is ascending or descending.
  • Add Row Enabled: Determines whether users with sufficient permission can add rows.
  • Delete Row Enabled: Determines whether users can remove rows.
  • Use Pagination Mode: Divides longer Lists into separate pages.

The List columns and their configuration are essential to define the information captured in each row. Default Sort By, Default Sort Order, Add Row Enabled, Delete Row Enabled and Use Pagination Mode are optional.

Each List column also has its own Label, Identifier, Type and supported configuration parameters.

Literal

  • Default Value: Contains the static text or HTML displayed wherever the Literal Field is used in a Template.

Default Value is essential for a Literal Field because it defines the content displayed by the Field.

Literal Fields do not use Expressions.

A Literal Field can be changed to a Long Text or Text Field.

Long Text

  • Rows: Controls the initial displayed height of the text-entry area.

Rows is optional.

A Long Text Field can be changed to a Literal or Text Field.

Lookup

  • Lookup Name: Selects the Lookup App containing the source data.
  • Lookup Search Field: Selects the Field used to find the source Record.
  • Field Mappings: Determines which source values populate which Fields in the current App.

Lookup Name, Lookup Search Field and Field Mappings are essential to define the Lookup behaviour.

Money, Number, Integer and Long

These numeric Field Types support:

  • Number Formatting: Controls how the value is displayed.
  • Format String: Creates a separate _Formatted backing Field containing the formatted value as text.
  • Display Formatted: Displays the _Formatted value as a read-only representation of the original Field.

All three parameters are optional.

For detailed guidance, see Field Formatting.

Number, Integer and Long: Auto Number

Number, Integer and Long Fields support automatic sequential numbering.

  • Auto Number: Enables automatic numbering for the Field.
  • Next Auto Number: Sets the value that will be assigned to the next Record created.

Auto Number is optional. Next Auto Number becomes essential when Auto Number is enabled because it defines the starting point for the sequence.

For example, if Next Auto Number is set to:

123

the next Record created will receive the value 123. App Studio will then update Next Auto Number to 124.

The value increases by one each time a new Record is created.

Important: Auto Number does not check whether a number has already been used. The App Builder is responsible for setting an appropriate Next Auto Number and ensuring the sequence does not create duplicates where unique values are required.

Take particular care when enabling Auto Number in an existing App or manually changing Next Auto Number, as existing Records may already contain values within the proposed sequence.

 

Multi-State

  • Sub Type: Determines the states and graphical presentation available to the user.

Sub Type is essential for defining how the Multi-State Field behaves.

The available Sub Types are:

  • RAG
  • RAGBB
  • Custom Colours
  • Harvey Ball
  • Harvey Ball Two State
  • Harvey Ball Tri State

Set an appropriate Default Value so that the Field begins with a valid option, such as Unset for RAG or 0% for a Harvey Ball. Default Value is optional but may be important for ensuring a valid initial state.

Notes

  • Note Display Order: Determines the order in which Notes are displayed.

Note Display Order is optional.

Person and Person By Team

Person Fields allow users to select a person. Person By Team limits the available people according to the relevant Team membership.

No additional parameter is required for a basic Person Field. The team configuration is essential where a Person By Team Field is used.

A Person Field can be changed to Person By Team. A Person By Team Field can be changed to Person.

Range

  • Min Value: Defines the lowest value available on the Range.
  • Max Value: Defines the highest value available on the Range.

Min Value and Max Value are essential for a Range Field because they define the available scale.

Reference

Reference Fields allow a user to select a Record from another App and map information from that Record into the current App.

  • Reference App: Selects the App containing the Records to reference.
  • Current App Field: Within the optional Matching Values Filter, selects a Field in the current App containing the value to match.
  • Reference App Field: Selects the Field in the Reference App that must match the Current App Field.
  • Reference Field Mappings: Determines which Fields from the selected Reference App Record populate Fields in the current App.

Reference App and Reference Field Mappings are essential for a Reference Field. Current App Field and Reference App Field are required when a Matching Values Filter is used.

The Matching Values Filter is optional and can restrict the available Reference Records. Reference options are filtered to Records where the selected Reference App Field matches the current Record’s value in the selected Current App Field.

Each value passed from the Reference App to the current App is configured as an individual Reference Field Mapping.

For full guidance, see Reference Field.

Selection

  • Select List: Selects the configured list containing the available options.
  • Sub Type: Determines whether the Select List values are stored as Text or Numeric.
  • Selection Type: Determines how users select values, including whether single or multiple selections are supported.

Select List, Sub Type and Selection Type are essential to define a Selection Field.

The Sub Type must correspond with the values configured in the Select List. Use Numeric where all stored values are numbers and need to be used in numeric Expressions. Otherwise, use Text.

Text

  • Length: Sets the maximum number of characters the Field will accept.
  • Pattern: Applies Regex validation to the entered value.
  • Error Message: Explains what the user needs to correct when the value does not match the Pattern.
  • Validator: Allows the Pattern to be tested before the App is published.

All four parameters are optional for a Text Field.

A Text Field can be changed to a Literal or Long Text Field.

Time

  • Display Seconds: Determines whether seconds are displayed as part of the Time value.

Display Seconds is optional.

URL

  • Link Text: Controls the text displayed for the clickable link. Link Text prevents users from entering the value manually, so use it when the URL is populated by another process, such as an Expression, Workflow, import or integration.
  • Open URL in New Tab: Opens the link in a separate browser tab rather than replacing the current page.

Both parameters are optional.

The available parameters depend on the selected Field Type. Parameters that are not relevant to a Field Type will not be displayed.

Important Considerations

Understand the purpose of each parameter

Field Parameters are available to support different aspects of a Field’s behaviour:

  • Identity: Identifier and Label
  • Data type: Type
  • User input: Required, Read Only and validation parameters
  • Initial values: Default Value and Process Default Value as Expression
  • Calculated values: Expression
  • Presentation: Formatting and Named Styles
  • Search and identification: Free Text Quick Filter and Title Field
  • Copying behaviour: Exclude This Field From Templated Record Copies
  • Field-specific behaviour: Parameters available for particular Field Types

A parameter may be optional in App Studio but still be important for a particular business requirement. For example, a Status Field may need a Default Value, while a calculated total may need an Expression.

Choose the Identifier carefully

An Identifier cannot be changed after Field creation. Choose one that is clear, concise and likely to remain appropriate throughout the life of the App.

Remember that Identifiers cannot contain spaces. For example:

Project Owner

is invalid, while:

ProjectOwner

is valid.

If a Field must be deleted and recreated because of an incorrect Identifier, any Expressions, Workflows, Reports, Templates, imports, integrations or other dependencies using the original Identifier must be updated.

Use the appropriate method of populating a value

Use:

  • Default Value for a fixed, sensible starting value that can be displayed while the user is creating the Record.
  • Process Default Value as Expression for a starting value calculated when the Record is created, which is applied only if the user has not entered a value. This value is not displayed while the user is completing the new Record.
  • Expression for a value that must remain calculated when its dependencies change.
  • Workflow for a value updated when defined events or conditions occur.
  • Link Text for an Email or URL Field when users should not enter the value manually and the underlying email address or URL is populated by another process.

Understand how imports update Fields

When importing a CSV to update existing Records:

  • A Field included in the CSV can be updated with the value supplied in the import.
  • If a required Field already contains a value, the import cannot clear it by supplying a blank value.
  • If a required Field was previously blank and is included in the CSV without a value, the import does not fail because of the required validation.
  • If a required Field is not included in the CSV, the import can still update other Fields without triggering a required validation error for the omitted Field.
  • Fields omitted from the CSV retain their existing values.

This means that an import can update only the Fields included in the CSV while leaving omitted Fields unchanged. However, an existing value in a required Field cannot be removed through an import.

Distinguish display behaviour from stored data

Formatting normally changes how a value is displayed rather than changing its underlying stored value.

Number Formatting keeps a numeric value editable. A Format String creates a separate _Formatted text value. Display Formatted shows that formatted value as read-only.

Link Text changes the way an Email or URL Field is presented and prevents users from entering the underlying value manually. Use it only when the value is populated by another process.

Named Styles apply predefined visual formatting to the whole component, the Field Label or the Field value. Depending on the selected Style, this may affect font size, font weight, text colour, background colour, alignment or whether the component appears as a Read Only Rectangle or Rounded Rectangle.

Consider dependencies when changing a Field

Changing a Field Type, deleting a Field or changing a parameter can affect other App components.

Consider whether the Field is used by:

  • Expressions
  • Workflows
  • Reports
  • Templates
  • Imports and exports
  • APIs and integrations

The impact depends on the parameter being changed. For example, changing a Label generally affects presentation, while changing a Type or Identifier can affect how other components refer to or interpret the Field.

Use this article as a reference

Apps may contain many Fields, and not every Field requires the same configuration. This article is intended as a reference for understanding what each Field Parameter does and when it may be relevant.

The appropriate configuration depends on:

  • The Field Type.
  • Whether users enter the value manually.
  • Whether the value is calculated or populated by another process.
  • How the Field is displayed.
  • Whether the Field is used in search, Reports, Templates or Record copies.
  • Any requirements of connected systems or integrations.

Related Articles

Related articles

Comments

0 comments

Please sign in to leave a comment.