Approval Workflow
Last updated
Last updated
This tutorial illustrates the process of establishing an Approval Workflow system, where Employee Users complete a Leave Request form that undergoes a series of approvals from a sequence of Administrative Users. The Administrative users will have the authority to approve or reject the request. In certain cases, based on the type of leave, the request may directly go to the Manager, bypassing the Department Supervisors.
The Employee and Administrative user accounts will be stored in a Resource database within the Form.io project. When creating these accounts, roles will be assigned to each user group to distinguish the different groups.
To control the functionalities available to different users within the Approval Workflow process, permissions will be assigned to the Leave Request forms in conjunction with their respective Roles.
Additionally, a series of Emails will be configured to be triggered during various stages of the workflow, such as when a Leave Request is submitted, approved, or denied. Each Email will incorporate conditional rules and SSO tokens to ensure a smooth sign-on process.
Open the video to review the chapter list containing time-stamped links that lead to code snippets and URL examples featured in the tutorial video.
Start the workflow by creating a new project from the Developer Portal. We will be utilizing the default Admin Resource included with the Project during the Approval Workflow process.
Resources are essential for establishing the RESTful databases required for the Approval Workflow process. These Resources will be used to establish our Employees filling out the Leave Request as well as the Administrative users that will be reviewing the requests.
Departments will be used to associate the different Employee and Administrative users utilized within the workflow.
Resources are flexible and can accommodate as many fields as needed. For instance, if the Department requires a physical location, you have the option to add fields such as Building address or the Department's HR contact information. However, for this example, the Department will be defined using a single "Name" field.
Start by creating a new Resource called Department.
Add a Text Field to the Resource and label it Name
Ensure the Property Name within the API setting tab is name
Create the Resource
Use the Resource and make 3 submissions to create the Departments:
Click the Data tab to review your records. This table represents the RESTful database that contains the Department entries that will be utilized by other Resources and logic within the Approval Workflow process.
Create an Employee Resource to establish a database for our Employee users. The records created within this Resource will utilize a Select component which will associate the Employee with a Department.
Create a new Resource called Employee
Add a Select component to the form and label it Department.
Click the API tab and ensure the Property Name is department
Click Data within the Department settings
Click the Data Source Type setting and select the Resource option
Click the Resource option and select Department
Set the Item Template to present the User with the Department Names
Next, add an field to the Form
Ensure the Property Name for the Email field is email
Create the Resource.
Additional modifications will be made to this Resource after Roles have been created
The Admin Resource will be used to create and manage Supervisor and Manager users. Within this Resource, a Select component will be used to determine whether the User is a Supervisor of a specific Department or a Manager overseeing all Departments.
Every Project created within Form.io automatically includes default Forms and Resources with the Admin Resource being one of those defaults. Instead of creating a new Resource, utilize the Admin Resource included with the Project for the following steps.
Click the Admin Resource to edit it.
Add a Select field called Department
Click the API tab and ensure the Property Name is department
Click Data within the Department settings
Check the Multiple Value setting
Click the Data Source Type setting and select the Resource option
Click the Resource option and select Department
Set the Item Template to present the User with the Department Names
Save the Department settings
Add another and call it Role.
Within the Role field settings, click the Data tab
Add the following to the options.
Save the Role settings
Save the Resource.
Additional modifications will be made to this Resource after Roles have been created
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. They operate in tandem with the Form.io Permission system, which helps regulate access and permissions throughout the project.
Before Roles can be delegated, they first need to be created within the Project.
Within your Project, click the Access tab on the left-hand side navigation bar
Click the +New Role button and create the following three roles:
With our Roles in place, we need to assign these Roles to the Permissions for our Resources.
Navigate to the Department Resource
Click the Access tab
Add the following to the
Read All
Employee, Manager, Supervisor
Save the settings
Repeat the same steps for the Employee and Admin Resource
The next step is assigning the Roles to our User groups. This is done by adding the Role Assignment action to the various Resources we established in the previous steps.
Navigate to the Employee Resource and click the Action tab
Click the Select an Action dropdown and select the Role Assignment
Click the +Add an action button
Click the Resource Association dropdown and select Existing Resource
Click the Action Type and select Add Role
Click the Role dropdown and select the Employee Role.
Save the Action settings
Navigate to the Admin Resource and click the Action tab.
Delete the pre-existing Role Assignment Action by clicking the Trash Can icon
Click the Select an Action dropdown and select the Role Assignment
Click the +Add an action button
Set the Title of the Action to Role Assignment - Supervisor
Click the Resource Association dropdown and select Existing Resource
Click the Action Type dropdown and select the Add Role option
Click the Role dropdown and select the Supervisor Role.
Add to the Action
Scroll down to the Action Conditions section
Click the Select the conditional field dropdown and select the Role option
Click the Select Comparison dropdown and select the Equals option
Add to the Enter Value field
Save the Action
Add an additional Role Assignment action to the Admin Resource
Click the Select an Action dropdown and select the Role Assignment
Click the +Add an action button
Set the Title of the Action to Role Assignment - Manager
Click the Resource Association dropdown and select Existing Resource
Click the Action Type dropdown and select Add Role
Click the Role dropdown and select the Manager Role.
Add to the Action
Scroll down to the Action Conditions section
Click the Select the conditional field dropdown and select the Role option
Click the Select Comparison dropdown and select the Equals option
Add to the Enter Value field
Save the Action
With our Resource models created, Permissions in place, Role Assignment actions ready to distribute the Roles, we are now ready to establish the Employee and Admin user groups.
This tutorial will utilize an SMTP Transport where all emails sent through the transport will be received within one inbox. If you do not have an email transport that functions in this way, you may have to modify the emails submitted within these user groups to ensure you have unique user emails that can be received within one single inbox.
E.g. - youremail+sales@example.com, youremail+it@example.com
Navigate to the Employee Resource
Click the Use tab for the Employee Resource
Create an Employee for each Department by filling out and submitting the Form.
The Department dropdown will determine what each account will associate with. Create enough submissions to associate an employee with all of the available Departments. Ensure you fill out the Department, Email, and Password fields for each submission.
Click the Data tab to review your records. This table represents the RESTful database that contains the Employee database.
Navigate to the Admin Resource
Click the Use tab for the Admin Resource
Create a Department Supervisor for each Department by filling out and submitting the Form.
Create a Manager for all Departments by adding all 3 departments to the Department field and submitting the form.
The Department dropdown will determine what each Admin account will associate with. Create enough submissions to associate a Department Supervisor with all of the available Departments. The Manager account will include all three departments. Ensure you fill out the Department, Role, Email, and Password fields for each submission.
Click the Data tab to review your records. This table represents the RESTful database that contains the Employee database.
The Leave Request form is what the Employee users will fill out when requesting their leave. This same form will be used by the Administrative users to either approve or deny the request and move the form status along in the Approval Workflow process.
Click the Forms tab from the left-hand navigation bar
Click the +New Form button
Name the Form Leave Request and create the Form.
The Leave Request Panel section is designed for Employees to view and complete. This part of the form will be submitted by the Employee and subsequently reviewed by the Administrative users to either be approved or denied.
Remember to periodically save the form
The basic input fields within the Leave Request section of the form.
Add a Panel component to the form called Leave Request.
Within the Leave Request section, add a Select component called Status
Within the Display tab, check the setting.
Click the Data tab and the following to the options.
Within the Data tab, click the setting and select Requested
Within the Data tab, uncheck the setting
The Status field will determine the State of the submission within the Approval Workflow process. Later in this documentation, a Form Controller will be used to control these values to create a State Machine for the Form, which will kick off the Approval Workflow process.
Add a Select component called Leave Type.
Click the Data tab and the following to the options.
Personal
Sick
Bereavement
Maternal
Other
Add a Date / Time component called Start Date.
Within the Display tab, remove the Time portion of the Format so it reads:
yyyy-MM-dd
Click the Time tab and uncheck the to ensure we only have a Date input within the field
Add another Date / Time component called End Date and repeat steps 4
Use different layout components to change the way the fields are presented on the Form. For example, a column component was used in the screenshot below to have the Date fields appear side by side.
Fields that will only show when certain values on the form are selected.
Add a Text Area component below the Leave Type field called Explain the type of leave you are requesting
Within the Display tab, click the Editor setting and select CKEditor
Click the tab
Set the Show or Hide this field setting to Show This Field
Set the When setting to When all conditions are met
Click the +Add Condition button
Set When to Leave Type, Is to Is Equal To, and Value to
Save the condition and component settings
Add another Text Area component below the Leave Type field called Please explain the emergency
Within the Display tab, click the Editor setting and select CKEditor
Click the tab
Set the Show or Hide this field setting to Show This Field
Set the When setting to When all conditions are met
Click the +Add Condition button
Set When to Leave Type, Is to Is Equal To, and Value to
Save the condition and component settings
Hidden components will be added to hold Admin Resource data associated with the logged-in user. This data will be fetched by the Data Source component and will emit an event that our conditional and calculation logic will use detailed further in the documentation.
Add a Hidden component to the form called Supervisor.
Ensure the Property Name is supervisor
Add another Hidden component to the form called Manager.
Ensure the Property Name is manager
Add a Data Source component to the form called Admin
Ensure the Property Name is admin
Click the Trigger tab and add the following to the Trigger on Event setting
fetchAdmins
Click the Fetch tab
Add the following URL to the Data Source URL setting
The yourdomoain.form.io within the URL will need to be changed to your own Form.io project domain. You can find the domain within the header of your Project underneath the Project Title.
Within the Fetch tab, click the Transform Data tab
Add the following JavaScript to the Code Block
This JavaSript will check the meta-data of the logged-in Employee and will populate the hidden components with the associated Admin data for the employee. This data will then be utilized within other conditions and calculations workflows within the Form.
Finally, within the Fetch tab, check the Form.io Authentication setting
Calculated Fields
Calculated Fields will be used to calculate data from the application and other fields within the form. These fields will output account information and other administrative information the form will utilize.
Add a Select component above the Status field called Employee.
Ensure the Property Name is employee
Click the Data tab within the component settings
Select Resource value from the Data Source Type dropdown
Select Employee value from the Resource dropdown
Set the Item Template to the following:
Click the Calculated Value tab and add the following JavaScript to the Code Block
This code will use the Formio.getUser() variable to populate the Employee's email within the field. It will also ensure this information is cleared out after a timeout occurs on the Form.
Add a Content component to the form
Add the following table to the Content section
Check the setting
Department
{{ data.employee?.data?.department?.data?.name }}
Manager
{{ data.supervisor?.data?.email }}
Supervisor
{{ data.manager?.data?.email }}
This table will interpolate the metadata from the logged-in Employee and display the Employee’s Department, Supervisor, and Manager.
This Panel will display when the Department Supervisor logs in to review the Leave Request.
Add a Panel below the Leave Request panel called Supervisor Approval
Click the Conditional tab
Open the Advanced Conditions tab and add the following JavaScript to the Code Block
This Javascript is using the getUser variable to determine who is logged in. If the User carries the Supervisor or Manager role, the Panel will display within the Form.
Add a Select component within the Panel called Supervisor Approval.
Ensure the Property Name is supervisorApproval1
Click the Data tab and add the following option Labels
Approved
Denied
Ensure the Values for the options are approved and denied'
Add a Text Area component called Denial Reason
Within the Display tab, click the Editor setting and select CKEditor
Click the tab
Set the Show or Hide this field setting to Show This Field
Set the When setting to When all conditions are met
Click the +Add Condition button
Set When to Supervisor Approval, Is to Is Equal To, and Value to
Save the condition and component settings
Add a Signature component so the Supervisor can sign off on the request.
This Panel will display when the Manager logs in to review the Leave Request.
Add a Panel below the Supervisor Approval panel called Manager Approval
Within the Panel settings, click the Conditional tab
Open the Advanced Conditions tab and add the following JavaScript to the Code Block
This Javascript is using the getUser variable to determine who is logged in. If the User carries the Manager role, the Panel will display within the Form.
Add a Select component within the panel called Manager Approval.
Ensure the Property Name is managerApproval1
Click the Data tab and add the following option Labels
Approved
Denied
Ensure the Values for the options are approved and denied'
Add a Text Area component called Denial Reason
Within the Display tab, click the Editor setting and select CKEditor
Click the tab
Set the Show or Hide this field setting to Show This Field
Set the When setting to When all conditions are met
Click the +Add Condition button
Set When to Manager Approval, Is to Is Equal To, and Value to
Save the condition and component settings
Add a Signature component so the Manager can sign off on the request.
Next, configure the Roles & Permissions on the form to determine what each User Group's role can do on the Leave Request form and it's underlying data.
Click the Access tab for the Leave Request form.
Add the following Roles to the Submission Data Permissions:
Create Own
Employee
Create All Submissions
Supervisor, Manager
Read Own
Employee
Read All Submissions
Supervisor, Manager
Update Own
N/A
Update All Submissions
Supervisor, Manager
Delete Own
N/A
Delete All
Manager
Remove the Anonymous Role from the
Save the settings
The Form Controller is a powerful tool within Form.io that provides an additional layer of control over the rendered Form by using JavaScript. In this example, we are going to use the Form Controller to manage the State of the Form using JavaScript code. The State will be mapped to the Status field values within the form. Follow the steps below to more efficiently manage the workflow of the Leave Request Form:
Within the Leave Request Form, click the More Settings (...) tab and select Form Settings
Copy the following JavaScript code
Scroll down to the Form Controller code block and paste the code
Save the settings
To summarize, the code is adding a beforeSubmit handler that identifies the State of the Form. The Workflow starts with the Employee submitting the Form with the Requested value from the Status field. When the Supervisor Approves the request, the Form enters into the Supervisor Approved state by applying that value to the Status field. From there, the Manager will review the request, and if approved, will enter into the Manager Approved state. If either the Supervisor or the Manager denies the request, the form will enter into the Denied state. If a Leave Request is submitted with the Emergency Leave Type, the form will carry the Emergency state.
The Email Action will fire off an email when something happens on the form, like when an Employee initially submits the Leave Request submission or an Admin updates the submission with an Approval or Denial. These Email Actions will take into account the current State of the form set by the State Machine and execute Actions based on the state. There will be several Email Actions saved to the Leave Request form that will execute each possible Leave Request scenario. Each Email will include an SSO Token to seamlessly log in to the appropriate user within the workflow.
This tutorial is utilizing an SMTP Transport, like Mail Trap, where all emails sent through the transport will be received within one inbox. It's required you set up your own Email Transport in order for this Email workflow to function properly.
Click Here for more information on setting up different transports.
Click the Action tab within the Leave Request form
Add an Email Action titled
Click Transport and select your integrated email transport.
Add the following within the To: Email Address
Modify the Message field to include an SSO Token that will authenticate the Supervisor.
https://pro.formview.io/?token=[[token(data.email=admin)]]#/abcdqweruiiopjkkl/leaverequest/submission/{{ id }}/edit
Here's a summary of what the SSO token is doing:
https://pro.formview.io/
The Application domain the SSO token will authenticate the user into. In this example, we will be using the FormView Pro Application to test out the workflow.
token=[[token(data.
email
=
admin
)]]
The token will then search within the Admin resource and try to find a record that matches the To:Email Address within the action and the Email data within the given Resource. If a match is found, a special JWT token will be generated.
/abcdqweruiiopjkkl/leaverequest/submission/
This is the Form.io project domain, and the submission endpoint of the form the token will be authenticating the user into.
{{ id }}/edit
The specific ID of the submission the SSO token is authenticating the user into. The user will be viewing the submission in Edit mode when the SSO token is clicked.
In order for the SSO token to function with your own Project, you will need to modify the example URL to include your own Form.io project domain.
You can also use HTML classes and the integrated Bootstrap library to create your own custom ways of presenting the SSO link. Here’s an example of the SSO Token link within a button block:
Scroll down to the Action Conditionals
Click the Select the conditional field setting and click the Status option
Click the Select comparison setting and select Equals
Input in the Value field
Save the action
Add an additional Email Action titled
Click Transport and select your integrated email transport.
Add the following within the To: Email Address
Modify the Message field to include an SSO Token that will authenticate the Manager.
https://pro.formview.io/?token=[[token(data.email=
admin
)]]#/myformio.domain/leaverequest/submission/{{ id }}/edit
Within the Action Execution section, click Methods and add
Scroll down to the Action Conditionals
Click the Select the conditional field setting and click the Status option
Click the Select comparison setting and select Equals
Input in the Value field
Save the action
Add an additional Email Action titled
Click Transport and select your integrated email transport.
Add the following within the To: Email Address
Modify the Message field to include an SSO Token that will authenticate the Manager.
https://pro.formview.io/?token=[[token(data.email=
admin
)]]#/myformio.domain/leaverequest/submission/{{ id }}/edit
Scroll down to the Action Conditionals
Click the Select the conditional field setting and click the Status option
Click the Select comparison setting and select Equals
Input in the Value field
Save the action
Add an additional Email Action titled
Click Transport and select your integrated email transport.
Add the following within the To: Email Address
Modify the Subject of the action to Your Leave Request Has Been Approved
Modify the Message field to include an SSO Token that will authenticate the Employee. To do this, change admin to employee. This will change the SSO token to search the email field within the Employee Resource.
https://pro.formview.io/?token=[[token(data.email=
employee
)]]#/myformio.domain/leaverequest/submission/{{ id }}/edit
Within the Action Execution section, click Methods and select
Scroll down to the Action Conditionals
Click the Conditional Field setting and select the Status field
Click the Comparison setting and select Equals
Input in the Value field
Save the action
Add an additional Email Action called
Click Transport and select your integrated email transport.
Add the following within the To: Email Address
Modify the Subject of the action to Your Leave Request Has Been Denied
Modify the Message field to include an SSO Token that will authenticate the Employee.
https://pro.formview.io/?token=[[token(data.email=
employee
)]]#/myformio.domain/leaverequest/submission/{{ id }}/edit
Within the Action Execution section, click Methods and select
Scroll down to the Action Conditionals
Click the Conditional Field setting and select the Status field
Click the Comparison setting and select Equals
Input in the Value field
Save the action
That completes the Actions for the Leave Request form.
The final step before testing out the workflow is to reconfigure the Login form.
Find the User Login form from the list of Forms within the Project
Click the Action tab
Edit the Login Action
Click the Resources field and add Admin and Employee
Save the Action
This will ensure the Login action will search the correct records when authenticating the user into the Form.
With everything in place, let's test out the Workflow using the FormView Pro application.
Navigate to the Leave Request Form and click the Launch tab
Click the Go to Form button to launch within the FormView Pro application
Login using the credentials for one of the Employee Users joe@example.com / password123 You should see the email address populated in the Employee field and a summary of the Employee's Department, Manager, and Supervisor
Click the Leave Type field and select Sick
Input dates into the Start Date and End Date fields
Submit the form
Log out of the Application
To ensure the FormView Pro application does not get confused with multiple tokens being used to authenticate into the application, be sure to log out of the application after each workflow exercise
The form will now be in the Requested state and will fire off the initial workflow by sending an email to the Department Supervisor of the Employee.
There should now be a Leave Request email waiting for the Employee's Department Supervisor.
Check the inbox for the Department Supervisor
Open the Leave Request by clicking the SSO link within the email
You should see the Supervisor Approval panel
Review and Approve the request.
Submit the form.
To ensure the FormView Pro application does not get confused with multiple tokens being used to authenticate into the application, be sure to log out of the application after each workflow exercise
The form will now be in the Supervisor Approved state and will fire off another email to the Manager to further progress the workflow.
There should now be a Leave Request email waiting for the Supervisor of the Department the request came from.
Check the inbox for the Department Supervisor
Open the Leave Request by clicking the SSO link within the email
You should see the Supervisor and Manager Approval sections
Review and Approve the request.
Submit the form.
To ensure the FormView Pro application does not get confused with multiple tokens being used to authenticate into the application, be sure to log out of the application after each workflow exercise
The form will now be in the Approved state and will fire off another email to the Employee to notify them of the approved request.
Check the inbox of the Employee and ensure you have an email Approving the request
Start a new workflow of the Leave Request form using the Emergency Leave Type.
Launch the Leave Request form
Login using the credentials for one of the Employee Users sally@example.com / password123
Click the Leave Type field and select Emergency
Input the reason for the emergency.
Input dates into the Start Date and End Date fields
Submit the form
The form will now be in the Emergency state and will fire off an email that bypasses the Department Supervisor and go directly to the Manager to be approved or denied.
At any point during the Leave Request's workflow, the request can be Denied by the Department Supervisor or Manager.
Check the inbox for the Manager Supervisor
Open the Emergency Leave Request by clicking the SSO link within the email
You should see the Supervisor and Manager Approval sections
Review and Deny the request.
Submit the form.
The form will now be in the Denied state and will fire off another email to the Employee to notify them of the denied request.
Check the inbox of the Employee and ensure you have an email Denying the request