Roles help group and categorise data so that it can be reused across documents. By assigning roles to fields, you make it clear who the data belongs to (e.g. Purchaser, Vendor, Applicant). This article explains how to create roles, apply them in your forms, and manage them over time.
Instructions
1. Understand what a role does
- Roles identify “who” the data belongs to and work alongside field aliases to create a reusable data path. For example, if you assign the role applicant to a field with the alias occupation, that combination becomes occupation >> applicant — and data entered here can be reused in future documents wherever the same alias-role combination appears.
2. Only use roles where appropriate
- A role can only be applied to fields that already have a field alias. Not all fields need a role — use them only when the data is part of a group you expect to reuse. Avoid assigning roles to general fields that aren’t reusable or don’t belong to a distinct person or party.
3. Apply a role to a field
- To assign a role:
- Open the form or section block in the form builder.
- Go to the Role Mapping tab.
- Click + Assign Role.
- Select a role from the dropdown. If the role doesn’t exist, type the name and click Create role.
- Click Add role to confirm.
4. Use naming conventions
- Use descriptive role names that reflect the group of data being collected, such as purchaser_details, property_details, or transaction_info.
- Avoid variations of the same concept (e.g. child and children) — these will prevent data from matching across forms.
TIP: Stick to your organisation’s naming conventions to avoid duplication and confusion.
5. Bulk assign or unassign roles
- To apply or remove a role from multiple fields at once:
- Select the checkboxes next to the relevant fields.
- Click Bulk Assign or Bulk Unassign.
- Choose or confirm the role to apply or remove.
6. Adjust existing roles on fields
- To edit or remove a role from a single field:
- Click the kebab menu (three dots) next to the field.
- Choose Edit role to select a new role, or Unassign role to remove it.
7. Manage the roles list
- To view and manage all roles in use:
- Go to Settings > Form Roles.
- Review the list of roles and their usage count.
- Use the icons to:
- Replace: Merge duplicate roles by replacing them with a consistent one.
- Edit: Rename a role across all forms.
- Delete: Remove a role that’s no longer in use.
NOTE: It’s a good idea to review the roles list regularly — at least fortnightly — to maintain consistency.
Common Issues & Solutions
- Issue: Data isn’t pulling through to future document
- Solution: Check that the alias and role names match exactly. Even small variations will break the data connection.
- Issue: Duplicate or unclear role names
- Solution: Use the Replace tool in the Form Roles tab to consolidate and clean up the list.