Who is this article for?

Administrators who need to create custom forms for data collection and workflow management.

Form builder access required.

Creating a custom form allows your team to collect the right information, follow a specific workflow, and meet site or programme-specific reporting needs.

1. Navigating to the form builder

To access the form builder, follow these steps:

1. Go to Edit Forms from the main menu.
2. Click New Form.

This opens the Form Information section where you configure how your form appears and functions in the system.

2. Configuring form information settings

The Form Information section contains several settings that define your form's identity and behaviour. Each setting serves a specific purpose in how users interact with your form.

Prefix

The prefix appears before the form number (for example, INJ-001, SPILL-002) and helps identify the form type at a glance. You will see this prefix:

• On the Forms page
• In the Permit Authorisation Data Table, under the Forms and Additional Forms columns

Tip: Use something short and intuitive, like INJ for Injury or LAB for Lab Safety.

Form Name

This is the name users see when selecting or working with the form. Choose something clear and descriptive (for example, Injury Report Form, Chemical Spill Report). The form name appears:

• On the Forms page
• In the Permit Authorisation Data Table
• Within the permit approval workflow on the Permit Authorisation page

Category

Categories help organise your forms and make it easier to search, link, or import them later. Select the most appropriate category based on form type. To add a new category, use the New Category button on the Edit Forms page.

Submit Button Text

By default, the button at the bottom of the form says Submit. You can customise this text (for example, Send for Review or Request Permit) if needed, with a maximum of 32 characters.

Note: Changing this is optional and should only be done if there is a specific user experience need, as it may affect consistency across your forms.

Lock Form on Submission

This setting prevents users from editing a form after they have submitted it. If your form includes subforms, you need to enable this setting on each subform individually to ensure they all lock on submission.

Form Lockable/Unlockable

This option allows the form to be manually locked or unlocked after it has been submitted. As with the setting above, apply it to all subforms if you are using them.

Only Authorised User May Submit Application?

Enable this if you want only the original applicant to be able to submit the form. When turned on, administrators cannot submit the form on someone else's behalf.

Use AJAX Staggered Loading?

If your form includes hundreds of questions, enabling this setting improves performance by loading questions as the user scrolls, rather than all at once. This is recommended for large, complex forms.

Use Kiosk Mode?

Kiosk Mode creates a public, no-login link for submitting the form, which is ideal for common access points or self-service stations. Once enabled, you will find the kiosk link under Data Manager, then select Permit Types.

Print to PDF Language Support

Choose the appropriate language if your form will be filled out in a language other than English. This ensures the exported PDF prints with the correct language formatting.

Form Page Break

Set where page breaks occur in the printed PDF version of the form. This helps with readability and formatting when generating hard copies.

3. Adding basic field types

Once you have completed the Form Information section, the next step is to start adding fields to collect the information you need from users. You can mix and match different types of fields depending on what kind of data you want to gather.

Text

Use this for open-ended responses. You can adjust how many lines appear using the Number of rows of text setting. This field:

• Accepts letters, numbers, or both
• Can also be used as a parent or child question

Tip: Use text fields for collecting open-ended responses or notes. If you plan to analyse the data later (like spotting trends or generating reports), consider using a dropdown or collection field instead, as those are easier to sort and visualise.

Number

Use this when you want to collect numeric input only, which is perfect for things like counts, ID numbers, or measurements. The form will restrict users to numbers only.

Yes/No Question

This adds a simple Yes/No toggle. By default, if you add child questions to this, they will appear only if the user selects Yes. You do not need to configure extra logic for this to work.

Date

This adds a date picker so users can easily select a calendar date. It is great for tracking incident dates, deadlines, or scheduling.

DateTime

This allows users to enter both a date and a specific time in a single field. It is useful when timing is important, like incident reporting or shift-based entries.

Time

This field lets users enter just the time with no date. It is good for start times, end times, or scheduled checks.

Current User

This field auto-fills information about the person logged into the system and filling out the form. It saves time and helps ensure consistent data (like name, email, or user ID).

4. Configuring required field settings

When you are adding a new question to a form, there are a few required fields you need to complete. This helps define how the question appears, who can see it, and how it functions in the system.

Minimum Role Allowed

This setting controls the lowest system role that can see the question. For example, you may want only Managers and above to view certain fields.

Note: Related setting: Edit Forms, then select Permits, then choose Allow copying from previous. This lets users copy answers from a prior submission if permissions allow.

Label

This is the actual question text that shows up on the form. Keep it clear and simple, avoid using too much HTML (adding too much formatting here can create support issues later), and if you are building a form in another language, use the correct language keyboard when typing the label.

Field Name

This is the system's internal name for the question. It must be unique, fewer than 59 characters, and lowercase and underscore-formatted is preferred (for example, injury_description).

Important: Do not use reserved or restricted terms like status, default, select, from, update, delete, or insert. These can interfere with system operations. You can check the full list of restricted SQL keywords at the PostgreSQL Reserved Keywords documentation.

AutoFill Reference

This setting tells the system to reuse an answer elsewhere, for example, pre-filling a dropdown in another form. Accepted values must come from an internal table such as:

• User Table: name, email, phone, job_title, emplid, gender, ethnicity, dob, emp_address, hire_date, dept_name, dept_code, org_name, org_code, supervisor_name, supervisor_email and job_location
• Location Table: loc_name, loc_contactto
• Facility Table: fac_name, fac_contactto, location_name
• Room Table: room_name, room_dept_name, room_contactto, fac_name, location_name, room_tags
• Department Table: dept_name, dept_contactto, org_name
• Organisation Table: org_name, org_contactto

Use this only when the field should tie into another system reference.

Number of Rows of Text

Used for text field types only. This controls how tall the text box appears on the form. Setting this to two or more creates a multi-line field for longer responses.

Create New Group

Use this if you want the answer to a text field to automatically create a new group based on that response. This only works for text-type questions.

Help Text

This adds a small information icon next to the question. When users hover or click, they will see a brief explanation or note. Plain text only (HTML is not supported). It is great for clarifying what kind of response is expected.

Required

If checked, the form cannot be submitted unless this question has been answered.

Limiting Question Response

Used when you are working with child questions. This field ensures the child question only appears if a specific answer is selected in the parent question. This only works with collection-type question formats (for example, dropdowns, multiple choice).

Set Current Date

For date question types only. When enabled, this auto-fills the current date into the field when the form is opened.

5. Setting up dropdown fields

Dropdown fields let you pull in values from system data tables, like users, rooms, facilities, or departments. These searchable dropdowns make it easier for users to select from structured data without needing to type everything out.

Table

This is where you choose the data source that will populate your dropdown. Common tables include User, Room, Facility, Department, and Organisation.

Note: You can request additional tables if needed, but it is best to limit how many are added to avoid performance issues.

Field Filtered by This Selection

Use this to create dependent (hierarchical) dropdowns. For example, if your form has a Location, then Facility, then Room hierarchy, you will want each selection to narrow down the options in the next dropdown. If a user picks a Location, and the next field is Facility, set the Facility field name here so it filters correctly.

Important: You must include all levels in the hierarchy for filtering to work. Custom or expanded hierarchies will not filter properly.

Checklist Field Name of Personnel (PI, Room, User Only)

This feature lets you display a roster list with checkboxes based on a selected PI or Room. To use it, set the dropdown field name as one of the following:

• PI: cofe_permit_user_id
• Co-PI: cofe_copi_id

When selected, this links to a roster field where you can show associated personnel.

Checklist Field Label of Personnel

This is the display label that appears above the list of users in the roster (checkbox) field. For example, Authorised Users or Lab Staff for This Permit.

Restrict by Permissions

Turn this on if you want the dropdown to show only the records the user has permission to see, based on their assigned role or roster. This only works with the PI table and can be combined with User Tags in Edit Forms, then select Permits, then choose Configure, then select User Tags Allowed.

Note: For example, a PI has five people on their roster, but only the Lab Manager has the correct tag to submit an application.

Include Create New User Option

If you are using the User table and someone is not listed in the dropdown, this setting lets users create a new user on the fly by entering their email. The user will be added to the system immediately after submission.

Defines Access Role Permission

This setting ties the question to your Access Role configuration. When enabled, this field will control who has permission to view or interact with the form, based on access roles set in the permit type or incident type.

6. Configuring collection fields

Collection fields are great when you want users to choose from a predefined set of answers. You can configure these fields as dropdowns, radio buttons, or checkboxes depending on how you want them displayed. This is a flexible option for collecting standardised responses like Priority Level or Injury Type.

Selection Type

Choose how the answer choices will appear on the form:

• Dropdown: Clean and compact, best for short to medium lists
• Radio Buttons: Shows all options at once, user can select only one
• Checkboxes: Great for select all that apply questions, allows multiple selections

Tip: If you have a long list of options (over 10), dropdowns can become harder to navigate. Consider grouping items or simplifying where possible.

Collection Options

This is where you enter the actual answer choices for the question. Add each option as plain text. You can include numbers or letters (for example, Level 1, Low/Medium/High, Yes/No).

7. Adding file upload fields

The file upload field allows users to attach documents, images, or other files directly to the form. This is useful for collecting supporting documentation like photos, permits, SDS sheets, or lab results.

Users can browse and upload files directly from their device. Multiple file upload fields can be added if you need to separate document types (for example, Upload Permit, Upload Inspection Photo).

Tip: You can use field labels like Upload SDS or Attach Incident Photo to make it clear what type of file should be uploaded.

8. Building custom tables with array of objects

The array of objects field lets you build a mini table directly inside the form, which is perfect for capturing repeating sets of information without having to create separate questions for each one. Think of it like a dynamic spreadsheet row that users can fill in multiple times as needed.

Instead of making five different questions like Chemical Name, Amount, Unit, Location, you can group them together in one neat table and let users add as many rows as they need.

To set up an array of objects field, follow these steps:

1. Fill out the basics:
   • Label: What the user sees at the top of the table
   • Field Name: The unique system ID for the table
   • Help Text: Optional guidance users can view when filling it out
2. Configure the table columns, using familiar field settings like:
   • Type: Choose whether the column is a text field, dropdown, date, number
   • Label: The name of each column (for example, Material Name)
   • Field Name: System name for each column
   • Number of Rows of Text: For longer text inputs
   • Help Text: If you want to clarify the purpose of a column
   • Required: Mark specific columns as mandatory

Use arrays when you want to let users enter flexible, row-by-row data, like materials used, team members, equipment lists, or exposure logs, all in one spot.

9. Integrating external data with API query fields

The API Query V2 field type lets you pull in data from an external system using a configured API integration. This is especially useful for retrieving user information or other reference data that is not stored in SafetyStratus, like employee records, training history, or equipment IDs.

This field connects directly to an API you have already set up in the platform and allows users to search or auto-fill that data right into the form.

Select Integration

Choose the API integration from the list of those configured under Admin Panel, then select Edit Settings, then choose Site Management, then select API Integrations. Once selected, the API URL and available form field mappings will appear. Be sure the field names you want to pull into the form already exist in the selected form configuration.

Always Show Button

This controls whether the Query button is visible on the form:

• On: Shows a manual query/search button
• Off: Hides the button (ideal when the query runs automatically using pre-filled data from another field)

Option List Display

This defines what users will see in the dropdown results after running the query. Use %AttributeName% to format your display. For example:

• To display the employee ID: %EmployeeID%
• To display first and last name: %FirstName% %LastName%

You can include multiple attributes if needed, just make sure they match the field names returned by the API.

Tip: API Query fields work best when paired with auto-fill reference fields or when streamlining data entry from trusted external sources.

10. Adding radiation safety fields

Radiation safety fields are designed for permit forms that need to connect to specific details from a radiation permit. These fields automatically pull in relevant information based on the selected permit owner and help ensure the data is accurate and consistent.

You can choose to include one or more of the following field types:

• RAM Only: Displays radioactive isotope details associated with the permit holder
• Assets Only: Shows equipment (or assets) linked to the radiation permit
• Rooms Only: Lists the rooms tied to the permit

These fields are especially useful when you need to verify permit scope or location details during form submission. They help keep things centralised and reduce manual entry.

11. Capturing location with GPS fields

The GPS capture field captures the user's physical location when they fill out the form. This is especially useful for fieldwork, incident reporting, or any activity that takes place outside a fixed location like a lab or office.

When this field is added to a form, the system will prompt the browser or device to allow location access. Once granted, it will automatically capture and record the latitude and longitude. The coordinates are stored with the form submission and can be viewed in the response data.

Things to know:

• Works best on mobile devices or browsers with location services enabled
• Users may need to click Allow Location Access for it to populate correctly
• The field can be set to required if location data is essential for compliance or reporting

Use this field on forms where knowing exactly where something happened matters, like spills, equipment use, safety checks, or incidents.

12. Displaying training records

The configure training field lets you display a user's training history directly within a form. This is great for permits, inspections, or access requests that require a quick check of whether someone has completed the required courses.

This field pulls data from the training records already associated with the selected user, helping reviewers and submitters verify compliance without leaving the form.

To set up training display, follow these steps:

1. Click Add Training.
2. Choose which training courses you want to display in the form (for example, Lab Safety, Radiation Basics, PPE Use).
3. Select the field that holds the user's name or ID in Fields for Which Training to Be Shown.

This links the form to their training profile and ensures the correct records are shown.

Note: This question type only works with non-array fields. If you need to check training for multiple people, you will need to handle them individually.

Tip: This is especially helpful on forms where training is a prerequisite for approval, like hazardous material handling, equipment use, or permit access.

13. Adding instructional content with text blocks

The text block question type allows you to add static content or instructions directly into the form. This field does not collect responses. It is simply there to give users helpful context or guidance as they fill things out.

You can use basic HTML formatting to style the content (like headers, bold text, lists, or links), which makes it great for improving the flow and readability of longer forms.

Common use cases:

Form introductions: Provide a summary or purpose for the form, including instructions or what is required to complete it.

Conditional information display: When used with the Limiting Question Response setting, you can show a specific block of text only when a certain answer is selected (like displaying additional information when someone selects Yes to a risk-related question).

Tip: This is a great way to reduce confusion, reinforce policies, or keep users informed about next steps, all without needing separate documentation.

Example: Incident form introduction

<h2>Welcome to the Incident Reporting Form</h2>

<p>Please use this form to report any workplace incidents, including near misses, injuries, property damage, or spills. Your report helps us maintain a safe environment and take corrective action when needed.</p>

<p><strong>Note:</strong> If this is an emergency, contact your supervisor or EHS team immediately before completing this form.</p>

Example: Conditional information (for Yes to injury)

<h3>Additional Injury Details Required</h3>

<p>You indicated that an injury occurred. Please provide as much detail as possible, including:</p>

<ul>

<li>Injured body part(s)</li>

<li>Type of injury (for example, cut, bruise, sprain)</li>

<li>Whether medical attention was received</li>

</ul>

Example: Policy reminder or reporting instructions

<h3>Reminder: Reporting Guidelines</h3>

<p>All incidents must be reported within <strong>24 hours</strong> of occurrence, even if they seem minor. Timely reporting helps us meet compliance standards and address issues quickly.</p>

<p>If you are unsure whether something qualifies as an incident, err on the side of reporting. It is always better to log the event.</p>

Example: Confirmation message at the end of the form

<h2>You're Almost Done!</h2>

<p>Double-check your responses before submitting. Once submitted, your report will be reviewed by the safety team. You will receive a confirmation email shortly.</p>

<p>Thank you for supporting a safer workplace!</p>