Role-Based Conditions

Conditional logic allows users to show or hide components based on other factors on the form. This example will showcase how to use the user's Role ID to show or hide fields. The FormView Pro application will be used to authenticate the user base to facilitate the role-based conditions.

In this workflow, authenticated users will fill out an Expense Report form. Supervisor users will log in to view the report and conditional logic will trigger based on the Supervisor's role and display an approval panel. Managers will then log in to view the Expense Report and Supervisor's approval input. The Manager will then finalize the report with their own approval section that will display based on their role.

Project Creation

Start the workflow by creating a new project from the Developer Portal. The default User resource will be used to authenticate the users filling out the initial Expense Report.

Resource Creation

Resources will be used to establish our Users filling out the Expense Report as well as the Supervisor and Manager users that will be reviewing the reports.

Supervisor

Create a Supervisor Resource to establish a data model for the Supervisor users.

1. Create a new Resource called Supervisor

2. Add an field to the Form

3. Create the Resource.

Manager

Create a Manager Resource to establish a data model for the Manager users.

1. Create a new Resource called Manager

2. Add an field to the Form

3. Create the Resource.

Creating & Delegating Roles

Roles authorize users, allowing them to perform specific tasks and gain access to forms and their underlying submission data. These roles are managed within the Access tab of your project and utilized by the Role Assignment action to assign a designated role to a submission object. Roles operate in tandem with the Form.io Permission system, which helps regulate access and permissions throughout the project, forms, resources, and underlying submission data.

The Role ID will be used within the conditional logic found later in this workflow.

Create Roles

Before Roles can be delegated, they first need to be created within the Project.

1. Within your Project, click the Access tab on the left-hand side navigation bar

2. Click the +New Role button and create the following roles:

Supervisor
Manager

3. Within the Access tab, click each role and save the Role ID number found within the URL. These IDs will be used further in the walkthrough. E.G. https://portal.form.io/#/project/1235abc689def/roles/aghj12qwe890/edit

Assigning Roles

The next step is assigning the Roles to the various User groups. This is done by adding the Role Assignment action to the Resources we established in the previous steps.

Supervisor Resource

1. Navigate to the Supervisor Resource and click the Action tab

2. Click the Select an Action dropdown and select the Role Assignment

3. Click the +Add an action button

4. Click the Resource Association dropdown and select Existing Resource

5. Click the Action Type and select Add Role

6. Click the Role dropdown and select the Supervisor Role.

7. Save the Action settings

Manager Resource - Supervisor Role

1. Navigate to the Manager Resource and click the Action tab

2. Click the Select an Action dropdown and select the Role Assignment

3. Click the +Add an action button

4. Click the Resource Association dropdown and select Existing Resource

5. Click the Action Type and select Add Role

6. Click the Role dropdown and select the Manager Role.

7. Save the Action settings

Establishing User Groups

With our Resource models created and Role Assignment actions ready to distribute the Roles, we are now ready to establish the User, Supervisor, and Manager user groups.

User

The default User Resource will be used to create and manage the users filling out the Expense Reports.

Every Project automatically includes default Forms and Resources. The User Resource is one of these defaults.

1. Click the Resource tab from the left-hand sidebar

2. Navigate to the User Resource

3. Click the Use tab and make a submission to create a user E.G. [e-mail] / password

Supervisor

1. Navigate to the Supervisor Resource

2. Click the Use tab for the Supervisor Resource

3. Create a Supervisor by filling out and submitting the Form. E.G. [e-mail] / password

Manager

1. Navigate to the Manager Resource

2. Click the Use tab for the Manager Resource

3. Create a Supervisor by filling out and submitting the Form. E.G. [e-mail] / password

Expense Report Form

The Expense Report form is what the Users fill out and submit for review. This same form will be used by the Supervisor and Manager users to either approve or deny the request. Conditional logic will be implemented to display additional panels on the form depending on what user is logged in. The User should only see the expense portion of the form. The Supervisor will see the expense portion and their own Supervisor panel for approval. The Manager will see the entire form, including their own Manager approval section to finalize the expense approval.

1. Click the Forms tab from the left-hand navigation bar

2. Click the +New Form button

3. Name the Form Expense Report and create the Form.

Alternatively, import the following Expense Report form into your project using the Import button from the form tab. https://examples-khvenypsypifjpi.form.io/rolebasedconditions

Expense Report Panel

Users will fill this portion out

1. Add a Panel called Expense Report

2. Add some fields to the form for User Information (E.G> Text Field - Name, Email, Employee ID etc)

3. Add a DataGrid to the form called Expense

   • Add some fields within the Data Grid to indicate expenses (E.G. Text Field - Expense, Currency - Amount, Data/Time - Expense Date)

Hidden Field Calculation

This field will use calculation to convert the role ID of the logged-in into a string-based value.

1. Add a Hidden field below the Expense Report panel called Permission

2. Within the Hidden field settings, click the Data tab and open the Calculated Value tab

3. Add the following JavaScript to the code block

const permission = Formio.getUser();
permission.roles.forEach((role) => {
  if(role === "12345abc6789def") {
  value = 'supervisor';
}
if(role === "12345abc6789def") {
  value = 'manager';
}
});

4. Replace the placeholder ID number with your own Role ID referenced in the Create Role section of the walkthrough

How do I find my Role ID?

You can find the Role ID by navigating to the Role within your project and observing the ID number within the URL. E.G. https://portal.form.io/#/project/12345abc6789def/roles/12345abc6789def/edit

1. Within the Project, click the Access tab on the left-hand navigation bar

2. Click a Role

3. Observe the ID number after the roles endpoint within the URL

Supervisor Approval Panel

Supervisors will view the expense and either Approve or Deny.

1. Add a Panel called Supervisor Approval

2. Within the Panel Settings, click the Conditional tab

3. Set the Show or Hide this field setting to Show This Field

4. Set the When setting to When any conditions is met

5. Click the +Add Condition button

6. Set When to Permission, Is to Is Equal To, and Value to s

7. Save the condition

8. Click the +Add Condition to add an additional condition

9. Set When to Permission, Is to Is Equal To, and Value to

10. Save the conditions and component settings

11. Add some fields to the Panel so the Supervisor can approve the request (E.G. Radio - Approved Request? Y/N, Signature field)

Manager Approval Panel

Managers will view the expense and either Approve or Deny.

1. Add a Panel called Manager Approval

2. Within the Panel Settings, click the Conditional tab

3. Set the Show or Hide this field setting to Show This Field

4. Set the When setting to When all conditions are met

5. Click the +Add Condition button

6. Set When to Permission, Is to Is Equal To, and Value to

7. Save the condition and component settings

8. Add some fields to the Panel so the Manager can approve the request (E.G. Radio - Approved Request? Y/N, Signature field)

Roles and Permissions

Next, configure the Roles & Permissions on the form to determine what each User Group's role can do on the Leave Request form and its underlying data.

1. Click the Access tab for the Expense Report form.

2. Add the following Roles to the Submission Data Permissions:

Permission	Role(s)
Create Own	Authenticated
Create All	Supervisor, Manager
Read Own	Authenticated
Read All	Supervisor, Manager
Update Own	N/A
Update All	Supervisor, Manager
Delete Own	N/A
Delete All	Manager

3. Remove the Anonymous Role from the

4. Save the settings

Login

The final step before testing out the workflow is to reconfigure the Login form.

1. Find the form from the list of Forms within the Project

2. Click the Action tab

3. Edit the Login Action

4. Click the Resources field and add Supervisor and Manager

5. Save the Action

This will ensure the Login action will search the correct records when authenticating the user into the Form.

Workflow

With everything in place, let's test out the Workflow using the FormView Pro application.

1. Navigate to the Expense Report Form and click the Launch tab

2. Click the Go to Form button to launch within the FormView Pro application

User Workflow

1. Login using the credentials for one of the Users [e-mail] / password

2. Fill out the Expense Report

3. Submit the form

4. Log out of the Application

Supervisor Workflow

1. Login using the credentials for one of the Supervisors [e-mail] / password

2. Within FormView Pro, click the Submission tab for Expense Report

3. Click the Edit button on the submission created by the user in the previous step

4. Approve or Deny the request and Submit the report

5. Log out of the Application

Implement SSO Tokens within the Email action to facilitate more advanced workflows for the Administrative users for reviewing and approving the Expense Report.

Manager Workflow

1. Login using the credentials for one of the Supervisors [e-mail] / password

2. Within FormView Pro, click the Submission tab for Expense Report

3. Click the Edit button on the submission reviewed by the Supervisor

4. Approve or Deny the request and Submit to finalize the report

5. Log out of the Application