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 from the dropdown then click the Add Action button. You can add multiple actions to run on each form submission.

Click the Edit icon to open the action's configuration settings. 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 action 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.

Read more about Conditions here

Action Logs

Action Logs are part of the Security Module only. Please contact [e-mail] for more information on adding the Security Module to your current License Subscription.

Action Logs will display a log of triggered actions and relevant contextual information about those executions. This feature must first be enabled on a per form basis before the Action Logs are documented. Click the 3 dotted settings button, Action Logs, then select Enabled from the setting dropdown.

Once enabled, any executed action will be documented within the Logs. Each log provides the user with relavent information that can be searched and filtered like the Date/Time, Action type, or the Action status, which can be particularly helpful when finding a failed action.

Date/Time - Indicates when the log was recorded

Submission - Provides the Submission ID the Action is associated with.

Action - Details the type of action

Handler - Determines if the action was executed before or after the submission

Method - What Submission CRUD operation the action was executed

Action Logs will be automatically deleted after 30 days.

Clicking a line item in the Log will give you detailed information about the Action's execution process. This can be very helpful when tracking down any issues that might be occurring with the Action.

Email

Fire off an email when submission activity occurs on a form

Login

Verifies user credentials against a Resource when authenticating into an application

Role Assignment

Add, modify, or remove a role from a user when certain submission activity occurs

Save Submission

Map the form field data to other Resources within a project.

Webhook

Use a webhook to integrate your form submission into other applications or databases

OAuth

Authenticate users using a OAuth provider

LDAP Login

Authenticate users against a LDAP service provider.

Goolge Sheets

Map form data to a Google Sheet spreadsheet

SQL Connector

Deprecated

Group Assignment

Facilitates group based permissions assigned to users within the group

eSign

eSignature provider integration to provide digital signatures

TFA & Recovery

Authenticate or recover your application account using using a one-time code

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

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 email address the email will be sent from.

Reply-To: Email Address: Set a different address the recipient will reply to.

To: Enter the email addresses to send to.

You can use field data from the form by using {{ data.email }} where the field's property 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 the form title.

You may use other field data from the form using {{ data.fieldname }}

Email Template URL: The HTML template used to style and format your email content. By default, the email action will utilize the following HTML template to organize the content of the email:

https://pro.formview.io/assets/email.html

Message: The message in the email.

You may use field data 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 using the Nunjucks templating engine.

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

Nunjuck Templating

All of the form 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.

Click Here for the full Nunjuck Templating documentation

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 readable 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. The deployed Form.io platform is also capable of offloading all email template processing to this separate micro-service. 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

Template Examples

Email Template Examples

The Email action Message carries a default Nunjuck Macro to produce an output of all field data within the submission which is found in the Message setting field of the action.

{{ submission(data, form.components) }}

This Macro works in conjunction with the HTML template found within the HTML Email Template field:

https://pro.formview.io/assets/email.html

The following examples will demonstrate how to add Nunjuck and to your own custom template messages. These examples will use HTML to format the content of the email inside a readable table.

Each example utilizes the following form which can be Imported into your own project using the Form Embed URL.

https://khvenypsypifjpi.form.io/expensereporting

Expense Form Example

Extracting Field Submission Data

In this example, the email template will use Nunjuck Macros to interpolate the Employee Name, Employee ID, and Department field data from the submission and output the information into an HTML table inside the email message.

Add the following code to the Message field within the Email Action settings.

  <tr>
    <td><b></b></td>
    <td></td>
  </tr>
  <tr>
    <td><b></b></td>
    <td></td>
  </tr>
  <tr>
    <td><b></b></td>
    <td></td>
  </tr>
</table>

Using For Loop To Output Field Submission Data Inside Arrays

The for tag is a Nunjuck tag that iterates over arrays and dictionaries. This example demonstrates how to interpolate data from fields inside an array (Data Grid, Edit Grid, etc) and output that data into the email message. Array data is referenced differently than other types of data, because of this, we are unable to use the Nunjuck Macro provided in the previous example and must set up a For Loop inside the message template.

To reference array data:

1. Create a For Loop provided by the Nunjuck templating documentation.
2. Set the array data inside the loop. Data inside of Data Grids or Edit Grids is referenced using the row attribute.

3. Reference the Array property name within the loop. In this example our Data Grid property name is expense.

4. Now we can reference the individual fields within the array. Use the row variable and the API Property Name of the field

5. Close out the For Loop {% endfor %}

6. Here is an example of a For Loop being used within an HTML table and Nunjuck Macro. The Table will create columns for the Expense Data, Expense Type, and Amount. The Nunjuck Macro will interpolate the Label of these fields from the Form and present them as the column headers. The For Loop lists all the component row data inside the Expense Data Grid and presents the row data within the HTML table.

Add the following code to the Message field within the Email Action settings.

<center></center>

<th align="left"></th>
<th align="left"></th>
<th align="left"></th>

 <tr><td></td> </tr>
{% endfor %}
</table>

If tag for conditional data output inside the email content

The If tag tests a condition and lets you selectively display content inside the email. It behaves exactly as javascript's if behaves.

In this example, the Manager field data should be included in the email content when the field contains data.

1. Add an If tag inside your message template

2. Add the condition statement inside the tag

3. Add the output of the condition. If the Manager field has a value, the condition will output the Label and data Value of the field inside the HTML table

   <th align="left"></th>
   <tr>
   <td></td>
   </tr>

4. Close out the If tag

<center></center>


<th align="left"></th>
<tr>
<td></td>
</tr>

</table>

Using If tag inside a For Loop

In some cases, you may want to incorporate If tags where the condition is based on fields inside an array. In this case, the If tag must be set inside the For loop of the message template.

Within the form, there is a field inside the Expense DataGrid called Other Expense that will conditionally display when Other is selected from Expense Type dropdown. In this example, the Other Expense data should be included in the email content only if the Other Expense field is conditionally displayed on the form.

There are two If tags being used in the following example. The first will display the Other Expense Label within the header of the HTML table. The second will display the Other Expense submission value within the corresponding row of the table.

1. Add a For Loop {% for X in X %}

2. Within the For Loop, add the If tag inside the HTML table row (line 12)

3. Add the corresponding result inside the tag (line 15). The row variable is used here to reference data within an array. {{ row.otherExpense }}

4. Close out the If tags (line 14) {% endif %}

<center></center>

</th>
<th align="left"></th>
<th align="left"></th>
<th align="left">{{ label("amount") }}</th>

<tr>
<td>{{ row.date }}</td> 
<td>{{ row.expenseType }}</td>
<td>


</td> 
<td>{{ row.amount }}</td> 
</tr>
{% endfor %}
</table>

Final Example

The example below incorporates all of the previous examples using Nunjuck Macros, For loops, and If tags.

<h3><b><center>User Information</b></h3></center>
<table align="center" style="width:75%;">
  <tr>
    <td><b>{{ label("employeeName") }}</b></td>
    <td>{{ value("employeeName") }}</td>
  </tr>
  <tr>
    <td><b>{{ label("employeeId") }}</b></td>
    <td>{{ value("employeeId") }}</td>
  </tr>
  <tr>
    <td><b>{{ label("department") }}</b></td>
    <td>{{ value("department") }}</td>
</tr>
<tr>
   {% if data.manager !== "" %}
    <td><b>{{ label("manager")}}</td></b>
    <td>{{value("manager")}}</td>
    {% endif %}
</tr>
</table>
<br>
<br>
<center><h3><b>Expense Report</b></h3></center>
<table align="center" style="width:75%;">
<th align="left">{{ label("date") }}</th>
<th align="left">{{ label("expenseType") }}</th>
<th align="left">{{ label("otherExpense") }}</th>
<th align="left">{{ label("amount") }}</th>
{% for row in data.expense %}
<tr>
<td>{{ row.date }}</td> 
<td>{{ row.expenseType }}</td>
<td>
{% if row.expenseType === "other" %}
{{ row.otherExpense }}
{% endif %}</td> 
<td>{{ row.amount }}</td> 
</tr>
{% endfor %}
</table>

Video

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

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.

Video

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

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

Video

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

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.

Walkthrough

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.

Video

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

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”
			}
		}
	]
}

Retry Request

If the webhook fails the first time, it is possible to retry the request. To use a retry request, you need to set the type of repeat, the maximum number of attempts, and the initial delay in milliseconds.

Retry Type: If the initial request fails, the calculation of the delay between further attempts will be calculated based on the type of repeat.

• Constant - the delay between attempts is constant and equal to the initial delay (e.g., 200ms, 200ms, 200ms, etc.)

• Linear - the delay between attempts increases linearly (e.g., 100ms, 200ms, 300ms, etc.)

• Exponential - the delay between attempts increases exponentially (e.g., 100ms, 200ms, 400ms, 800ms, etc.)

• Jitter - mitigate correlations and improve the performance by adding randomness (e.g., 170ms, 275ms, 196ms, 511ms, etc.)

• Exponentially Jitter - mitigate any corrections, fewer spikes, and a smoother distribution than Jitter type (e.g., 196ms, 267ms, 595ms, 1132ms, etc.)

Number of attempts: The maximum number of additional request attempts if the request fails. If the request is successful, the retry request is stopped.

Initial Delay: The initial delay between the initial request and the first additional attempt. The delay is calculated based on the retry type.

Webhook Testing

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

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:

• GitHub
• Facebook
• Office 365

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

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.

Walkthrough

LDAP Integration must first be configured within your Project settings before the workflow can function.

Click Here for more information on integration setup.

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.

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.

Click Here to establish a Google Integration with a Form.io project.

Click Here to enable Google Drive

Settings

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.

Walkthrough

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.

Video

SQL Connector

The SQL Connector Action has been deprecated. For alternatives, refer to the feature deprecation notice.

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

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

Walkthrough

Click here for more information on Group Assignments workflows

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. Create a new Resource and call it UserGroup

2. Drag and drop a Select component

3. Give the component a label of User

4. Click on Data tab, and then select Resource under Data Source Type.

5. Next, select User as the resource.

6. Scroll down and then type the following for Item Template. <span>{{ item.data.email }}</span>

7. Press Save to save the field on the form.

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.

Click here for a full walkthrough on setting up the eSign workflow

The Form.io Box Sign Integration will soon be deprecated

Settings

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: [e-mail] 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: [e-mail] or {{data.finalCopyRecipientEmail}}

Automatically redirect to E-Sign provider on Form Submit: By checking this box, the form will automatically redirect to eSignature provider 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 the eSignature provider. Valid values are string values. By default, if you leave this field blank, the name of the file when uploaded 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

Code: Field on the form (typically a Textfield) to provide the 6-digit authentication code.

Recovery Code: One-time recovery code to authenticate users.

Walkthrough

Click Here for a full walkthrough of how to setup Two-Factor Authentication