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 sales@form.io 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

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.

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

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.

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.

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 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.

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.

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 - COMING SOON

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.

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.

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.

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.

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.

Please follow this link for more information on the Google Drive integration.

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.

SQL Connector

The SQL Connector Action allows you to integrate form submissions with your own SQL based database. 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.

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

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.

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

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

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: approver@example.com 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: final_copy_recipient@example.com 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.

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

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

Last updated