Approval Workflow
This tutorial will give you an overview of setting up an Approval Workflow process for a progressive web application using the Form.io platform. For this workflow, we are going to create an Expense Report form where Employee users can submit an expense and Management users can review/approve the reports.
Find a full written guide as well as a video walking through these steps below:
Approval Workflow Video Guide
Before we set up our Expense Report form, we first need to establish our Resources (data models) for our different user groups. These user groups will authenticate into the application and will be granted different Roles and Permissions for the application depending on what Resource they belong to.
The first Resource we will create is the Management Resource. This Resource will hold all of our Manager user entities which will approve the Expense Reports submitted by the employees. Create the Resource inside your project and add some fields like first and last names and a checkbox to approve the reports. We also want to include the Email and Password fields to ensure Managers can Authenticate into the application.
Create another Resource called Department which will determine what Department our Managers and Employees are associated with. Add a text field for the Department name and then add a Select component to establish a reference between the Department and Management Resources.
Within the Select component settings, set the Data Souce Type to 'Resource' and then select Management from the Resource dropdown. Lastly, set the Item Template to interpolate the email data from the Management Resource
<span>{{ item.data.email }}</span>
The 'email' is referring to the Property Name of the email field inside the Management Resource.
Create an Employee Resource. Add some fields for First Name / Last name and Email / Password fields for authentication purposes. Next, we need to reference what Department the Employee is associated with.
Similar to the Department Resource, add a Select field, change the Data Source type to Resource, select the Department from the Resource options, and modify the Item Template to interpolate the date from the Department Name field within the Department resource.
<span>{{ item.data.departmentName }}</span>
The 'departmentName' is referring to the Property Name of the Department Name field inside the Department Resource.
For our final Resource, create an Expense Type Resource with a Textfield and make several submissions with different Expenses employees may want to report on (EG Travel, Food, Entertainment).
With our Resource Data Models in place, create the Roles that our different User groups will later use to grant permissions to the referenced Resource data and Expense Report Form.
Navigate to the Access section of your project and create the following roles:
ManagerEmployee
With our Roles in place, we need an Action to grant our Employees and Managers their respective roles when a new Manager and Employee entry is made.
Navigate back to the Manager Resource and click Actions. Add the Role Assignment to the Resource. Ensure you have New Resource selected for the Resource Association field, Action Type is set to Add Role, and Manager is selected for the Role field. Make sure to save the Action.
Next, add the Role Assignment action to the Employee Resource. Configure the action the same way except, the Role field will be set to Employee.
With these Actions in place, all entries submitted against the Manager and Employee Resources will contain their respective role within the submission.
Next, we need to ensure that our User groups have the correct Access settings within our Resources and Forms to Read Resource data and submit the Expense Report form. Navigate to the Access settings for the following Resources/Forms and add the Roles and Permissions detailed below:
Department Resource
Read All - Manager, Employee
Expense Type Resource
Read All - Employee, Manager
Manager Resource
Read All - Employee, Manager
Employee Resource
Read Own - Employee
Read All - Manager
Update All - Manager
Delete All - Manager
Expense Report Form
Create Own - Employee
Create All - Manager
Read Own - Employee
Read All - Manager
Update Own - Employee
Update All - Manager
Delete All - Manager
To ensure the Login form displays when the Expense Report Form is rendered, remove Anonymous from the Read Form Definition field within the Access settings. This will only display the Form when being viewed by an authenticated user.
Now we are ready to create our User groups by making submissions against the Manager and Employee Resources created in the previous steps.
Start off by Using the Manager Resource and create several Managers by submitting the form.
Now that we have our Managers, we need to associate those Managers with a Department. Navigate to the Department Resource, input a Department name, and select the Manager from the select dropdown. Map the remaining Managers to a new department by submitting the Resource.
For the final User group, Use the Employee resource and create a new employee for each Department within the Department Select dropdown.
With our User groups in place, each Employee is now associated with a Department, and each Department has a connected Manager.
Let's bring all of this work together by creating the Expense Report Form.
Create the Form and add a Text Field called Label to distinguish where the Expense(s) originated from. Next, add a Select Resource field called Employee and map the field to the Employee Resource. Add the following to the Item Template to map the Email data to the field
{{ item.data.email }}Ensure the logged-in user email is auto-populated to the field when the Employee initializes the form by setting
Formio.getUser(): within the Custom Default Value in the Employee field settings. value = Formio.getUser();
It's common in an Expense Report to have the ability to add several expense entries saved to one collection (or array). There are several fields and ways of accomplishing this, but for this example let's use a DataGrid component to facilitate our array. Some fields you may want to add to the DataGrid could be:
Now we can add multiple instances of our expense fields to one DataGrid array.
Add another Currency field called Total to calculate all of the Expense amounts.
Now we need a section only Managers can see when viewing the Expense submission where they can Approve or Deny the report. Drag and drop a Panel component to the bottom of the form called Manager Approval. Add a Radio component to determine whether the Manager will Approve or Deny the request and a Signature field to finalize the request within the panel.
With our Expense Report fields in place, it's now time to implement some conditions and logic to calculate our expenses and facilitate the approval workflow
Ensure the logged-in user email is auto-populated to the Employee field when the User initializes the form by setting
Formio.getUser(): within the Custom Default Value in the Employee field settings. value = Formio.getUser();
Within the Total field, we can add logic to calculate the sum of all the expense Amounts within the DataGrid. Within the Total field settings, write Javascript inside the Calculated Value section to calculate the DataGrid (array) amount fields.
value = data.expenses.reduce(function(sum, expense)
{ return sum + expense.amount; }, 0);
Next, let's add Conditional Logic to display the Manager Approval section when the submission is being viewed by a Manager authenticated within the application. Open the Manager Approval panel settings and click the Conditional tab. Within the Advanced Conditions, write Javascript to determine if the Form.io user authenticated into the application is a Manager and if the Manager has the 'Can Approve Expenses' flag. We can find this field reference within the Manager Resource.
show = Formio.getUser().data.canApproveExpenses;
This condition will search the logged-in user within the app and determine whether the user is a Manager with the Approval flag set.
In many cases, the department Manager will want to receive an email notification when a new Expense Report has been submitted. Within the Expense Report Form, click Actions and add a new action called Email.
Select an email Transport then make than following modifications to the To: Email Address:
{{ data.employee.data.department.data.manager.data.email }}This line of code will interpolate the data from the Expense Report Form, tapping into the Employee Resource, to the connected Department Resource, to the department Manager Resource, and finally the Department Manager's Email address. Once the Expense Report form is sent, the email action will send a summary of the data entered into the form to the connected manager.
Finally, a small modification needs to be made to our Login form so the form searches for the correct Resources when a User is logging into the application. Click Actions for the existing Login form within the project. Edit the Login action, remove the User Resource, and add the Employee and Manager resources to the Resources dropdown.
Now that we have our Approval Workflow setup, it's time to test it out. Click the Launch option for the Expense Report Form. This will open the form inside Form.io's very own Form View Pro application.
It's recommended to launch the Form View Pro application using an incognito window to avoid 'token collision' between the Form.io portal and the launched application.
Login as an Employee using the credentials for one of the Employee Resource submissions. Once logged in, you should see your Employee field automatically populated with the employee email address. Fill out the Expense form and make a submission. Log out of the application when finished.
The Manager assigned to the employee department will receive an email summarizing the Expense Report submitted by the employee in the previous step.
Introduce the Email Authentication workflow into your email action to allow the Management users to authenticate and view the expense report via a hyperlink inside the Expense Report email.
Next, log in as a Manager inside the Form View Pro application using the credentials for one of the Manager Resource submissions. Once logged in, click the Submissions tab at the top of the application header. Edit the submission from the Employee. You should see the Expense Report AND the Manage Approval section. Deny or Approve the request, sign the form, and Submit the form to complete the Workflow.
Last modified 3mo ago