Fields are the individual data entry points within an App. They form the basis of all data and reporting. They are usually exposed within template as per the diagram below, but can also be hidden to the user and simply used as a hidden value or reporting Field.
First find the App that you would like to add a Field to in App Studio. To do this click on the COGs menu and select App Studio which will open App Studio in a new browser tab. Once in App Studio, click on the launchpad icon at the top left of the screen and select the App that you are adding the Field to. Lastly click on Fields folder in the App configuration to see a list of the Fields in the App.
Adding a new Field for an App
To add a new Field select the Fields folder in the left pane menu and then click on the '+' icon on the right of that row. This will open a new property sheet where we can define how the Field will look and what information it is expecting the user to input.
There are three key properties that a new Field will need:
Label: The label is what will appear beside the Field on a Record to tell Users what data point is being captured by the Field.
Identifier: The identifier is a unique reference to each Field that data for each Record will be captured against. By default the identifier will take it's value from the Label with any white space and special characters removed. The identifier must be a minimum of three characters, only contain letters and numbers and start with a letter. The identifier will be visible to Users as the column headers in a .csv export of the data from an App.
Field Type: There are a several options for field types, ranging from simple text entry fields to complex grids of fields. Selecting a specific field type will expose the parameters required to enable the field to function correctly and dictate the expected format of the data. For a full list of the Field Types available see our support article on selecting the correct Field Type
Once you have filled in these details for the Field you can save the Field by clicking on the tick at the top right of the screen. This will create the Field that you can then use expose to Users by adding them to Templates and Reports.
Required & ReadOnly
Two more features that are common across the majority of Fields are Required and ReadOnly
Required: By ticking this property a newly created Record will need to have a value in this Field before it can be created or updated. It will appear with a red outline until a value has been entered to show that it is required.
ReadOnly: When a Field has been set to ReadOnly it cannot be edited by a User through the UI. It will appear as greyed out and not allow Users to edit the value. It will allow for data to be entered into the Fields via a .csv import of data.
Field Parameters and Validation
Depending on the Type of Field that you have selected you will be able to set validation rules to restrict the value that a User can enter into the Field.
By selecting a Text Field there is the option to set 'Length' which will limit the entry to a specified number of characters.
A Range Field allows you to specify a 'Min Value' and 'Max Value' to set which value the slider on the range Field will move between.
A LongText Field allows you to set the default height of the Text Box by and number of 'Rows'.
For a full list of validation that can be added across Field Types see our article here on Field Parameters.
Expressions and Default Values
Expressions are a powerful tool to be able to process the data that is in an App. They can be used to set the status of a project to RAG, used for numeric calculation to evaluate financial data or used to pass data between Parent and Child Apps. These expression compiling articles will hep you to utilise all of the functions that are available to you as App Builders.
Adding a default value will determine the value that this Field takes on creation of a new record. Ensure that the value you enter for the default value matches the Field Type that you have selected such as numeric for Number, string for Text or boolean for Bit.
As well as adding a default value you can tick 'Process Default Value As Expression'. By adding an expression in the box for 'Default Value' and then ticking this property it will run the expression to populate the value for the Field on creation of the Record. If a User has entered a value for this Field before creation of the Record then that will still take precedence over the default expression. After creation of the Record the Field will be editable by the User.
Adding a Format String will convert the value for a Field into a Read-Only text value that is in the format that the user will expect to read the value. It does this by adding a _Formatted backing Field that contains the formatted string value of the Field. You can then use the original Field for use in expressions and to display in a Record for data input and you can use the formatted backing Field for Read-Only display in Records and Reports. 'Display Formatted' will default the formatted value to show in ReadOnly view of the Field in a Record and in Reports.
See our article on Format Strings for a full list of the options available to add format strings to numeric and date Fields
Exclude This Field From Templated Record Copies: When performing a Record Copy there is the option to do a templated copy. A templated copy will copy the Record and the data from all Fields that do not have this property checked.
Include In Free Text Quick Filter: The Free Text Quick Filter is available in a Report to filter down Records. It will return all Records that contain the Search Text in Field values for Fields that have this property checked.