Actions
Actions are ways of extending <form.io> to do actions when a form is submitted. For example, you can authenticate a user account against your User Resource, send an email or fire off a webhook to send the data to an external system.
Form.io 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.
The email action allows sending an email when an event occurs on a form.
36 email settings pt 1
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
When to run this action. Select which system events will trigger this action.
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.
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.Subject
The subject of the email. You may use fields from the form using
{{ data.fieldname }}Message
The message in the email. You may use fields from the form using
{{ data.fieldname }}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. | ||||||||||
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.
| ||||||||||
res | A stripped down response object that contains the following parameters.
| ||||||||||
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.
|
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') }} |
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=yourkeyTemplate 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
The Webhook action allows you to integrate form submissions into other applications 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.
Handler
The handler determines whether the webhook request will be made "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 be made twice, once before your submission is saved and once after.
Method
When to run this action. Select which system events will trigger this action.
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.
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 with 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 web hook url, enter the password here.
Additional Headers
You can add additional headers as needed. These might include an Authorization header or Content-Type.
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," su 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.
An example response from the AirTable Create Record API
Here's a sample of what the default request payload looks like on a form that has a textfield 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' }
}
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 and 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 an 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!
The Role Assignment Action allows for the modification of a submissions roles, when an event occurs on a form.
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. The available options are Add Role and Remove Role.
Role
The role to use when performing the role assignment.
Note: The Role Assignment Action requires a Resource Form component with the API key, ‘submission’, to modify existing Resource submissions.
The OAuth action allows you to do user authentication within your application against an OAuth provider. When a user authenticates, a popup window will ask them to log into the configured OAuth provider’s website, and authenticates them into your application on successful login. This allows users to register and login to your application without having to create a new account.
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:
- More providers coming soon…
Action
The action to perform after the user has authenticated against the OAuth provider.
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.
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.
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.
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 login 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.
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 Data Connection is required in the corresponding projects settings. Once the settings are configured, you can map your Form.io form to your Table Columns.
Additionally 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
Last modified 2mo ago