Links

Actions

General Information

Actions are ways of extending <form.io> to perform tasks when there is form submission activity. These actions can be triggered when certain things occur like a form submission, submission update or deletion, and so on. There can be multiple actions on any given form providing the ability to initiate different business workflows. For example, you can authenticate a user account against your User Resource, send an email with data details, or fire off a webhook to send the data to an external system.

Adding an Action

To add an action, go to the Actions tab of a form. Select the type of action to add and the click Add Action button. You can add multiple actions to run on each form submission.
Click the white Edit icon to open the action for review or updates. Click the red Trash Can icon to delete the action from the form or Resource.

Common Settings

All actions perform different functions, however, many of the actions share some common settings that can be configured by the user.
Title: The name or label of the action. Modify the Title to provide more of a description of the action's specific purpose or function. The Title will display on the Action overview page.
Handler: The handler determines whether the email will be sent Before or After the MongoDB query mechanism (that is, before or after your submission is saved to the database). If you select both, it will run twice, once before your submission is saved and once after.
Method: The Method determines when to run this action on a form. Select which system events will trigger this action:
Create - Action will fire when a new submission is created
Read - Action will fire when a submission is Read (or viewed)
Update - Action will fire when a submission is updated
Delete - Action will fire when a submission is deleted
Index - Action will fire when indexing (or searching) a submission within the Database
Action Conditionals: Use the Simple conditional dropdown workflow or write your own Javascript to execute the action only when certain conditions have been met on the Form or Resource. The Conditional system is the same system used to facilitate field conditions.

Email

The email action allows sending an email when an event occurs on a form. With a multitude of options, users can configure this action to satisfy different workflows and use cases. Connect to your own Email transport, configure the email template, or dynamically attach files to the email.
Settings
Nunjuck Templating
Pro Tips
Video
Transport: Select which email transport to use. These need to be configured in your project settings. Transports will not be available for selection if you haven’t configured them.
When using the Form.io SaaS offering @ portal.form.io, you must set up your own Transport. The default transport service provided by Form.io is no longer available. Please see the documentation on Email Integrations for instructions on how to proceed.
From: Enter the from email address for the emails.
Reply-To: Email Address: Set a different address the recipient will reply to.
To: Enter the email addresses to send to.
You can use fields from the form by using {{ data.email }} where the field name is email.
Send a separate email to each recipient: Each recipient designated in the TO field will receive an individual email
Cc: Email Address: Send a copy of the email to the listed email addresses
Bcc: Email Address: Send a blind copy of the email to the listed email addresses. Recipients will not see the other email addresses listed.
Subject: The subject of the email. By default, the Subject will interpolate
You may use fields from the form using {{ data.fieldname }}
Email Template URL: The HTML template used to style and format your email content.
Message: The message in the email.
You may use fields from the form using {{ data.fieldname }}
Rendering Method: Determines how the email will render
Dynamic rendering utilizes formio.js to render the email.
Static rendering is considered deprecated and should not be used in most cases.
Attach Submission Files: Check this if you would like to attach uploaded files from the file component to the email.
Attach PDF Files: Check this if you would like to attach a PDF of the submission to the email. This will count toward your PDF Submission count for every email sent.
If you are remotely deployed, please set the BASE_URL=https://yourdomain.com to match the API server’s domain protocol and domain name for the formio-enterprise server
All of the email fields are sent through a templating engine called Nunjucks. It is recommended that you read through the documentation of this templating language to understand how it can be utilized to produce very complex templates for your emails using form data. This documentation can be found @ https://mozilla.github.io/nunjucks/templating.html. You can use the following variables which are provided to each template.
data
The submission data which maps to the data object of the submission. Example: {{ data.firstName }} would map to the data provided in the "First Name" field if one is provided in your form.
data
The submission data which maps to the data object of the submission. Example: {{ data.firstName }} would map to the data provided in the "First Name" field if one is provided in your form.
id
The ID of the submission being submitted.
{{ data.[RESOURCE]Obj }}
Because all of the nested resources will only show their "template" data, every nested resource also has an object property assigned to the data to give you access to the full resource object assigned to that submission. For example, if you have a Customer resource field assigned to an Order resource, and you sent an email from the order. {{ data.customer }} would only show the templated customer, however {{ data.customerObj }} would contain the full customer object. In this case, you could type {{ data.customerObj.data.email }} to get the customers email address within the template.
content
This is the content within the Mail message section that you wish to inject within a template. This is useful if you wish to have a common template that all your emails use, and then use the "message" portion to construct the content within that template using {{ content }}
form
The form object that this email is being sent from. {{ form.components }} would provide you with all the components within the form.
components
A flattened list of form components. Example, {{ components.firstName.label }} would print out the First Name component.
owner
The user who owns the form.
req
This is a stripped-down request object that contains the following parameters.
user
The currently logged in user object. Example: {{ req.user.data.email }} would print out the users email address.
params
The request parameters. For example, for url https://myproject.form.io/myform, {{ req.params.formId }} would be the Id of that form
token
The JWT token of the user submitting the form.
query
The request query. For example, for url https://myproject.form.io/myform?testparam=1, {{ req.query.testparam }} would be 1
res
A stripped down response object that contains the following parameters.
token
The decoded token object of the logged in user.
mail
The current mail object being sent. Example {{ mail.to }} would contain the email address who the message is being sent to, which contains the following parameters.
transport
The transport protocol used to send the email.
from
Who this email is being sent from.
emails
An array of emails that are set to receivie the email.
subjects
The subject of the email.
message
The message of the email.
Nunjucks Filters
In addition to the core filters provided by Nunjucks, the following additional filters are also included for use within Emails.
date
Prints out a date value as a readible date. See Nunjucks Date Filter for detailed documentation. Example {{ created | date("YYYY") }}
Nunjucks Macros
In addition to template variables, we also provide a number of macros that can be used to easily render form submission information into your emails. These are as follows.
{{ table(form.components, title) }}
Prints out a nested table of the form submission.
{{ submission(data, components) }}
Prints out a flat submission data table.
{{ value(key) }}
Prints out a readible value for a submission of a certain field. Example {{ value('birthday') }}
{{ label(key) }}
Prints out the configured label for a certain field. Example {{ label('birthday') }}

Template Service

Considering that the template rendering is processor intensive, it is also possible to deploy the template rendering system as a separate service.
The library that governs the template rendering system is called Form.io Workers. This library can be found by going to https://github.com/formio/formio-workers. Within this library, you have the ability to either run this as a stand-alone Node.js service, or you can also use a tool such as Claudia.js.
For example, if you wish to push this into your own AWS Lambda function using Claudia, you can run the following within the directory.
npm run deploy
If you wish to see the command that is executed within the NPM script, you can open up the package.json file and see the "deploy" script within the scripts section. This uses Claudia to push this into AWS Lambda as a live endpoint.
Endpoint
Once the template service has been deployed, the "nunjucks" service can then be accessed using the following url.
https://[TEMPLATE_SERVICE_URL]/worker/nunjucks?key=yourkey
Template Service Configuration
The template service can be configured with the following environment variables. These variables can be provided within the .env file included with the source code of this library.
Environment Variable
Description
Example
PORT
The port to bind to when running the service
3000
KEY
This is the secret key that is used to communicate to the template service via API. This key is used within the query parameter.
https://worker.yourdomain.com/worker/nunjucks?key=yourkey
LAMBDA
Tells the service if it is running within AWS Lambda or locally within a VM.
1 - To enable use lambda 2 - To use local install
Once you have the template service up and running, you can then tell the Form.io Enterprise Server to use this service with the TEMPLATE_SERVICE environment variable like so.
TEMPLATE_SERVICE=https://worker.yourdomain.com/worker/nunjucks?key=yourkey
  • Interpolate field data within your form to the To, From, Form Title, and Subject settings of the Email action. In the example below, the To setting is to dynamically interpolate the data of my email field within my form. In turn, the email will be sent to the address entered into the field when the form is submitted.
{{ data.email }}

Login

The Login Action is typically connected to a User-based resource (like the default User or Admin Resources that come with each project) and Email/Password fields from the Login form are then mapped to the Email/Password field from the connected Resource using the Login action settings.
When the Action is executed, the Email/Password data is then verified from the Resource Data Base. If a match is found, the user will then be authenticated into the application.
Login action mapped to the User Resource
Settings
Video
Resources: The Resource the action will reference for matching Email/Password information.
Username/Password Field: Map the fields from your form to the connected resource to validate a match for Login authentication.
Maximum Login Attempts: The number of times a User can fail a Login attempt before being locked out. Use 0 for an unlimited number of attempts.
Login Attempt Time Window: The window of time in seconds to count the login attempts. Once the User is outside of the time threshold, the Login Attempt number is reset, as long as they have not been locked.
Locked Account Wait Time: The amount of time in seconds a person needs to wait before they can try to log in again.

Role Assignment

The Role Assignment Action adds, modifies, or removes roles associated with the submission when an event occurs on a form. A common use case for the Role Assignment action is adding the action on a Registration form to grant users certain roles after they register. Those roles will then work in tandem with Form.io's authentication system.
Settings
Video
Resource Association: The resource association will determine if a new or existing resource will be modified.
Action Type: What type of role assignment action to take.
Add Role: Adds the given Role to the submission record.
Remove Role: Removes the given Role from the submission record.
Role: The role to use when performing the role assignment. Roles are managed from the Access section of the project found on the left-hand navigation bar.
The Role Assignment Action requires a Resource Form component with the API key, ‘submission’, to modify existing Resource submissions

Save Submission

This action dictates what Resource and related Resource fields the form data will save to. Every form or Resource created will carry a Save Submission action. When left unmodified, the action will save the data to itself by default.
Mapping the Save Submission action to other Resources allow Forms to feed a Resource database. The most common example is a Registration form. When a user Registers, the submitted data most likely will need to be saved to some sort of User Resource to build a User database collection.
Save Submission action mapped to the User Resource
Settings
Walkthrough
Video
Save Submission To: Select which Resource the submission data should map to. When left blank (default), the submission will save to itself.
Resource Property: Set a Property to the mapped Resource that will be assigned to.
Simple Mappings: When a Resource is selected, the available fields from that Resource will become available for mapping in the Simple Mappings section. Clicking a field will present a Dropdown of fields from the Form the action is attached to where fields from your Form are mapped to fields from the Resource.
Transform Data: Use the Transform Data if you are trying to map fields inside complex data structures like EditGrids, Containers, Nested Forms, etc. Available variables are Submission and Data.
In this example, we are going to configure a Save Submission action on a Registration form to map submission data to a User Resource. In turn, as the Registration form collects submissions, the Resource will build its database of Users within the project.
To start, create a Resource called Users and add the following fields:
Email - Email
Password - Password
Next, create a Form called Registration. Add the following fields:
First Name - Textfield
Last Name - Textfield
UserName - Textfield
Email - Email
Password - Password
Click the Action tab for the Registration form and add another Save Submission action. Within the Action settings, click the Save Submission To dropdown and select the User resource. Next, map the Email and Password fields from the form to the Resource fields presented in the Save Submission Action. Save your action.
To test the action, Use the Registration form and make a submission.
The submission should map to the User Resource, creating a submission record. To verify this, navigate to your User resource and click the Data tab. There should be a new submission entry from the Registration form.
Encrypted password data will not display when viewing a submission.

Webhook

The Webhook action allows you to integrate form submissions into other applications or databases by providing a means to call an external API with a payload containing your form submission data in real-time. In order for the Webhook action to function properly, make sure the API endpoint is accessible by the same network as your deployment.
Webhooks execute when using a form. They do not execute when you are building/editing a form within the Developer Portal Application. To test Webhooks, the form should be launched using the FormviewPro Application, or embedded within the application you are building.
Settings
Webhook Testing
Sample Payload
Request Method: This is the REST Verb that will be used to make the request. If set to Match (or blank) it will use the request method that came with the request. For example, a Create request will have the Post method. Below are the available request methods:
Get, Post, Put, Delete, Patch
Request URL: The URL of the external system that will handle the webhook. This should be accessible to the form.io server.
Forward Headers: If checked, all of the headers received by the form.io server will be forwarded to the webhook.
Authorize User: If you are using Basic Access Authentication for the webhook request, enter the username here.
Authorize Password: If you are using Basic Access Authentication for the webhook URL, enter the password here.
Additional Headers: You can add additional headers as needed by providing the Header and Value. These might include an Authorization header or Content-Type.
Request Payload: By default, the request payload will contain an object with the following information:
{
request: request, // an object containing request body to the form.io server.
submission: submission, // an object containing the submission object from the request.
params: params, // an object containing the params for the request such as query parameters or url parameters.
}
You can use the transform payload javascript to modify the contents of the payload that will be sent in this webhook. The following variables are also available: headers
Transform Payload: You can modify the request payload by writing custom javascript code. There are available variables that can be used to aggregate into a custom object as desired. Whatever is placed into the payload will be sent as the body of the request.
Wait for Webhook Response
By default, webhook actions will not wait until a response is received to continue to the next form action. If you check the box labeled "Wait for the webhook response before continuing actions," the form submission process will wait for a webhook response before continuing and return the results to the front end in the submission's metadata field. Any errors received from webhooks whose responses are being awaited will stop the form submission process and be displayed to the form user.
External Id Type and Path
If the webhook endpoint creates a data object in the external system, there is often an id created and returned in the response. If you want to save this id and associate it with the submission in Form.io, you can specify a type and id path here. The External Id Type is the reference key of the external service's database (e.g. "github"). The External Id Path is the path to the id field in the external service's response object. For example, in the response below (returned from AirTable), the path would read records[0].id. If you use the same External Id Type in multiple webhooks, any subsequent changes to the id field will be updated in the Form.io submission data.
{
“records”: [
{
“id”: “recZ37x123HWzDLaJ”,
“createdTime”: “2022-09-24T01:31:25.000Z”,
“fields”: {
“Customer”: “Joe Smith”
}
}
]
}
In order to ease development and testing around your webhooks, we've created an example application called Webhook Receiver. You can install this application on your local machine by executing the following commands in your terminal.
npm install
node index.js
This will run the receiver on your local machine. To easily connect services running on your local computer to the wider internet, we recommend using a tool (often called a "tunneler") such as ngrok. Once you have a ngrok account and the software installed, you will need to expose the Webhook Receiver application running on your local machine by running the following command in your terminal:
ngrok http 4001
You should now see the tunnel address that's been created:
Version 2.1.14
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://941a7c65.ngrok.io -> localhost:4001
Forwarding https://941a7c65.ngrok.io -> localhost:4001
This indicates that the address http://941a7c65.ngrok.io will tunnel to the Webhook Receiver application running on your local machine. Once the tunnel is running, configure a Webhook Action on your form with the following settings:
  • Webhook URL: http://941a7c65.ngrok.io
  • Authorize User: test
  • Authorize Password: password123
(The username and password can be changed in the config.json file of in the Webhook Reciever's root directory.)
You can now submit the form and see the data come through your local machine!

Sample Payload

Here's a sample of what the default request payload looks like on a form that has a text field named "textField" and a number field named "number":
{
request: {
data: { textField: 'Test value', number: 12345, submit: true },
owner: '61c5e59add38c4e4a356acb0',
access: [],
metadata: {
timezone: 'America/Chicago',
offset: -300,
origin: 'https://portal.form.io',
referrer: '',
browserName: 'Netscape',
userAgent: '<user agent value>',
pathName: '/',
onLine: true,
headers: [Object]
},
state: 'submitted',
form: '62a745944e836ccf1c0ba167',
project: '61d21695ecb3f85c774e8f09',
_fvid: 0
},
submission: {
owner: '61c5e59add38c4e4a356acb0',
deleted: null,
roles: [],
_id: '62e052a316f1ad4f786d4038',
_vid: 0,
_fvid: 0,
state: 'submitted',
data: { textField: 'Test value', number: 12345, submit: true },
access: [],
metadata: {
timezone: 'America/Chicago',
offset: -300,
origin: 'https://portal.form.io',
referrer: '',
browserName: 'Netscape',
userAgent: '<user agen value>',
pathName: '/',
onLine: true,
headers: [Object]
},
form: '62a745944e836ccf1c0ba167',
project: '61d21695ecb3f85c774e8f09',
externalIds: [],
externalTokens: [],
created: '2022-07-26T20:46:27.232Z',
modified: '2022-07-26T20:46:27.233Z',
__v: 0
},
params: { formId: '62a745944e836ccf1c0ba167' }
}

OAuth

The OAuth action allows you to perform user authentication within your application against an OAuth provider. When a user authenticates, a window prompt will request the user to log into the configured OAuth provider’s website. The user will authenticate the user into the application with a successful login from the OAuth provider. This allows users to register and log in to your application without having to have an account within your application Project.
Settings
OAuth Provider: The OAuth Provider to authenticate against. This is the service that users will log into when authenticating via OAuth. You will need to register your application with these providers before you can use OAuth. See the OAuth guide for more information. We currently support the following OAuth providers:
Action: The action to perform after the user has authenticated against the OAuth provider. The available Actions are listed below:
  • Remote Authentication: This will log a user in based on their remote user account. Unlike the rest of the actions, it does not require creating a user resource submission in form.io. All permissions and ownership still work.
  • Login Existing Resource: This will attempt to authenticate an existing resource via OAuth. Use this action for forms like Login forms. This will search for a user account that is linked to the authenticated OAuth provider account, and log them in.
  • Register New Resource This will create a new submission and perform authentication against the new resource. Use this action for forms like Registration forms. This will create the user account, link the authenticated OAuth provider account, and log them in.
  • Link Current User: This will link an OAuth provider account to the currently logged-in user. Use this to allow users who have authenticated via the Authentication Action with an email and password to also log in to their account via OAuth.
Role: The selected role will be added to all new resources created by the form with this Authentication Action.
Sign-in with OAuth Button In order to use the OAuth Action in a form, you must choose a Button component with the action setting OAuth to start the OAuth sign-in process. When a user clicks the provided button, the OAuth authentication process will begin by opening a popup of the OAuth provider login page.
Please note - When embedding the form into the renderer, append "?live=1" parameter at the end of the form embed URL to allow for the OAuth action to trigger properly
Autofill Fields: Depending on which OAuth provider you select, and if you select the Register New Resource action, a number of Autofill Field options may appear. These settings allow you to automatically retrieve data from the OAuth provider account that is used to authenticate and fill in fields in your form before the new resource is created. For example, a GitHub OAuth Registration form may use the Autofill Email Field to assign the email of the GitHub account that was used to authenticate into a field of the new Resource that is created.
Autofill Fields will not always guarantee that they will find a value to fill, as the OAuth provider account may not have any information. For example, a Facebook account may not always fill the Autofill Email Field because some Facebook accounts are created with phone numbers.

LDAP Login

LDAP Authentication integration provides the ability to authenticate users directly against an LDAP service such as OpenLDAP or Active Directory. The LDAP Login action connects the Username and Password credentials from the Login form to the LDAP directory.
Settings
Walkthrough
Username Field: The Username field from the form mapped to the username field from the LDAP directory
Password Field: The Password field from the form mapped to the username field from the LDAP directory
Passthrough: If checked, any failures except for a failure to Bind the user account, will be ignored and the login information will be passed to the next form action. This allows using both LDAP and the Form.io Login action on the same form.
LDAP Property: Group name within the LDAP directory
Value: Given Role from the LDAP Directory
Role: Form.io role the Property group and Value will map to.
LDAP Integration must first be configured within your Project settings before the workflow can function.

LDAP Login Form

Create a new form that will be used to Login to LDAP. We can do this by clicking on New Form, and then building it as follows.
Click Create Form button to create the new form.

LDAP Login Form Access

You will now need to ensure that Anonymous users are able to "submit" this form, which will execute the actions assigned to the form. You can do this by clicking on the Access settings and adding the Anonymous role to the Create Own permission.

LDAP Login Action

Next, we will navigate to the Actions section of our form and first Remove the Save Submission Action.
After we have done, that we will add the LDAP Login action as follows.
Within the LDAP Login Action, you will then configure the following parameters.
If you choose the Passthrough option, any failures except for a failure to Bind the user account, will be ignored and the login information will be passed to the next form action. This allows using both LDAP and the Form.io Login action on the same form.

Assign Roles

Next map any LDAP properties to user roles. Select the property, the matching value and the role to assign it true. Leave LDAP Property and Value blank to assign the role to all LDAP accounts.
For example:
  • LDAP Property: group
  • Value: Admins
  • Role: Admin
Would assign the Admin role to any members of the Admins group.
The user’s DN is also mapped to the list of properties so if the DN is dn=myname,ou=admins,dc=example,dc=org you can do:
  • LDAP Property: ou
  • Value: admins
  • Role: Admin
After you have the Login action set, you can save this action to add this to the form.

Testing LDAP Login

If you provided the Test Credentials at the top of the page, then you should be able to perform the following API request within Postman to perform and test out an LDAP login.
Here you will see that the Authenticated role has been assigned to the user object.

SQL Connector

The SQL Connector Action allows you to integrate form submissions with your own SQL-based database and requires your project to be on the Team Pro plan or Above; The SQL Connector Action currently supports Microsoft SQL, MySQL, and PostgreSQL. When a submission is created, it will be created in your database for your consumption via formio-sql. To get started with the SQL Connector, the SQL Connector
To get started with the SQL Connector, the SQL Connector Data Connection is required in the corresponding project settings. Once the settings are configured, you can map your Form.io form to your Table Columns.
the formio-sql server must have access to your database and be configured with your settings, see formio-sql for more information. When you start the formio-sql server, it will authenticate to Form.io and grab the dynamically generated routes with SQL query strings
Settings
Walkthrough
Block request for SQL Connector feedback: Prevents potential timeout issues from SQL connector like blocking or holding requests.
Table Name: The SQL table name being referenced
Primary Key: The SQL table's Primary Key
Fields: Input the SQL field identifier in the left-hand column and then map that to a field from the Form using the dropdown found in the right column. Use the +Add Another button to create new field pairings.

Google Sheets

The Google Sheets action maps field data from a form to an external Google Sheet document. The User has control over what data is saved to which column within the document. This action can be very useful if an ongoing report is needed to track submission data from a form to a spreadsheet.
Before the Google Sheet action can be used, a Google Integration must first be established before the Action can connect with the user's Google Drive.
Settings
Walkthrough
Video
Sheet ID: The ID of the Google Sheet being used. The ID is the string of characters found in the URL endpoint of the Google Sheet document.
Worksheet Name: Name of the Worksheet, or tab, within the Google Sheet document. By default, the name will be Sheet1
Start Row: The row the data will start to merge into. By default, this is set to 2 accounting for row 1 is reserved for the field headers.
Google Sheet Fields: The setting fields here represent the fields on your form. Each field can be mapped to a column represented by the letter header within the Google Sheet document.
External ID Type: The name to store and reference the external Id for this action. This is useful when using several Google Sheets actions and should specify a unique External Id Type to each Google Sheet action to avoid undesirable results.
To set up integration between a form and a Google Sheet document, you will first need to establish the Google Drive integration. After the integration is complete, add a Google Sheets action to the form.
On the Actions tab, select “Google Sheets” from the Action list.
Open the Google Sheet you wish to use and copy the Spreadsheet ID (string of characters found in the Spreadsheet URL) and Sheet Name (name of the tab within the sheet).
Paste the Sheet ID and Sheet Name within the Action. Next, map the fields on your form to columns in the Sheet. You can find Spreadsheet keys at the top of Spreadsheet columns. For each field, specify the column key you wish to map the data to e.g. adding ‘A’ in [First Name] field will post the submitted data for that field in Column A of the spreadsheet.
Now it’s time to test our settings. Go to the view tab of your form and submit the form with relevant data in the fields.
You should see the field titles are automatically created in the Google Spreadsheet and the correct form data is added to the columns configured in the action form fields. Any additional form submissions will add data to the subsequent rows.

SQL Connector

The SQL Connector Action allows you to integrate form submissions with your own SQL based database and requires your project to be on the Team Pro plan or Above; The SQL Connector Action currently supports Microsoft SQL, MySQL, and PostgreSQL. When a submission is created, it will be created in your database for your consumption via formio-sql. To get started with the SQL Connector, the SQL Connector
To get started with the SQL Connector, the SQL Connector Data Connection is required in the corresponding project settings. Once the settings are configured, you can map your Form.io form to your Table Columns.
The formio-sql server must have access to your database and be configured with your settings, see formio-sql for more information. When you start the formio-sql server, it will authenticate to Form.io and grab the dynamically generated routes with SQL query strings
Settings
Block request for SQL Connector feedback
Table Name: The SQL table name being referenced
Primary Key: The SQL table's Primary Key
Fields: Input the SQL field identifier in the left-hand column and then map that to a field from the Form using the dropdown found in the right column. Use the +Add Another button to create new field pairings.

Group Assignment

The Group Assignment action grants access to certain users who belong to a certain "group" Resource within your project. A Group can be defined as a separate Resource that is then assigned to different users, thereby placing those users into different permission contexts. In order to establish a permission system based on these groups, follow the Walkthrough guide below.
Settings
Walkthrough
Group Resource: The Select Resource field on your form that maps to the Group Resource.
User Resource: The Select Resource field on your form that maps to the User Resource. Users will join the selected Group upon submission.
User Role: The Select Resource field on your form that maps to the Role Resource. Users will carry the User Role that was selected upon submission

Group Permissions

In addition to providing access based on Roles within a project, you can also grant access to certain users who belong to a certain "group". A Group can be defined as a separate Resource that is then assigned to users, thereby placing those users into different contexts. In order to establish a permission system based on these groups, we must first setup our project to enable Group structure. We will start by creating a Group resource.

Create a Group Resource

In order to take advantage of the group permission system, you must first create a "group" resource. A group can really be defined as any entity that is used to coalesce different sets of users into different groups. Here are some good examples of what would be defined as a Group.
  • Department - Used to place employees in their own departments.
  • Team - Could be used to place athletes into their teams.
  • Class - Could be used for education to collect teachers and students together into a "class" group.
For this generic example, however, we will just call our group "Group" which can be done by creating a new resource, and we will just add a single Text Field called "Name".
Once this group is created, we can now create a few example groups by simply using this resource and submitting a few records. We will just create two new groups called, "Teachers" and "Students"
Viewing the data of group to see our two "groups" called Teachers and Students.
We can now create our "join" resource to bring users and groups together.

Creating a Join Resource

To create a many-to-many relationship between Users and Groups (where users can be associated with many groups, and vice-versa) we will create another Resource that will serve the sole purpose of "joining" these two resources together. This is typically called a Join Resource and is very powerful in establishing a many-to-many relationship between two resources.
A one-to-many relationship is also possible by simply adding the "Group" resource as a field that belongs on the User resource, but for this example, we will cover the more common use case of using a join resource.
To create this Join Resource, we will do the following.
  1. 1.
    Create a new Resource and call it UserGroup
  2. 2.
    Drag and drop a Select component
  3. 3.
    Give the component a label of User
  4. 4.
    Click on Data tab, and then select Resource under Data Source Type.
  5. 5.
    Next, select User as the resource.
  6. 6.
    Scroll down and then type the following for Item Template. <span>{{ item.data.email }}</span>
  7. 7.
    Press Save to save the field on the form.
  8. 8.
    Repeat steps 2 - 7, but this time do it for the Group resource. Make the Item Template as <span>{{ item.data.name }}</span>
Now save this resource.
A Join Resource to bring Users and Groups together
Next, you will click on the Actions tab for this resource, add a new Action called Group Assignment and then click on Add Action button. Under the action settings, for Group Resource, select Group and for the User Resource, select User.
Make sure to add a Group Assignment action with the following settings.
Next click Save Action to add this action to the form.
UserGroup resource with Group Assignment action.
We can now create a few submissions in this resource (by clicking the Use tab) so that we can associate some users with some groups. Here is an example of the submission data after we have done this.
Adding some users to groups

Assigning Group Permissions

The next thing we need to do is to add a Group to a form (as a field), and then provide access to that form based on the group that the user belongs to. For example, we could create an Evaluation form, and then add the following Group as a field to that form.
Creating a form that contains the Group as a select field
Now that you have the field added to your form, we can now edit the Access tab and configure the following under the Field Based Resource Access section.
Giving groups "read" access to the form submissions.
This configuration basically says the following.
Any students who create evaluations can read other students evaluations, but not teachers evaluations. Any teachers who create evaluations can read other teachers evaluations, but not student evaluations.
This is how you can enable groups of users to have different access than other groups of users based on their associations with other resources within a Form.io project.
Group permissions function by assigning the Group ID (submission id) as a "role" that is added to the user's submission object. This can be seen by viewing the user's submission JSON and viewing the "roles" property which will contain any group IDs that the user has been assigned.

Group Roles

In addition to allowing Groups to be established, it is also possible to establish roles, where further categorization of users can be made within a single group. For example, if you wish to have a Group defined as a Classroom, the Group Roles system allows you to assign users to a Classroom, but then choose if they are a Teacher or a Student within that classroom, and then grant separate permissions based on their role within the Group.
This is configured exactly as you would configure the Group Permissions above, but with just a few differences.
  • When you create your Join Resource, you will need to create a field that will be used to establish the "Roles" within that group. This can simply be a Select dropdown with the Values of that select dropdown showing the roles you wish to provide.
Adding a Group role to the Join Resource
  • When you configure the Group Assignment action, you will now want to select this new field as the Role.
  • Finally, when you assign the permissions of the Group to the form, you will want to assign which role within the form can have which permission.

eSign

Form.io allows integration with eSignature providers to capture an eSignature, a digital signature, from one or many signers. This process is customizable and works for both PDF and API forms. The eSign action is required to complete the signature workflow process.
Settings
Walkthrough
Approvers: Recipients who need to approve a document sent for eSignature, but do not need to provide a signature. The values here can be a string email address or an interpolated value. Example values: [email protected] or {{data.approverEmailAddress}}
Final Signed Copy Recipients: Recipients who need to be sent a copy of the signed document once the signing has been completed. The values here can be a string email address or an interpolated value. Example values: [email protected] or {{data.finalCopyRecipientEmail}}
Automatically redirect to E-Sign provider on Form Submit: By checking this box, the form will automatically redirect to Box Sign's website upon form submission to allow the person submitting the form to provide a signature. Note that there is no redirect back to Form.io upon signature completion. You will have to navigate back to Form.io.
Email Subject: A custom email subject to be included in the signature request email. Valid values are string values. Example: Please eSign this form
Email Message: A custom email message to be included in the signature request email. Valid values are string values. Example: This is my test email message
Name of upload PDF File: The name you wish to customize for the file when uploaded to Box Sign. Valid values are string values. By default, if you leave this field blank, the name of the file when uploaded to the box will be the submission id. Example: My request form

Two-Factor Auth & Recovery

The 2FA Authentication action allows users to log in to your Portal base project or application using a one-time 6-digit code from an authentication provider.
Please note, the Portal Base project for deployed users will have Two-Factor Authentication preconfigured.
When utilizing 2FA for your own project (not Base Portal), provide read access permissions for your users to the Two-Factor Authentication Settings Form.
Settings
Walkthrough
Code: Field on the form (typically a Textfield) to provide the 6-digit authentication code.
Recovery Code: One-time recovery code to authenticate users.