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.

Adding an Action

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

Authentication Action

The authentication action allows you to do user authentication within your application against a User Resource. When a user authenticates, they will be issued a JSON Web Token (JWT) which will authorize access to parts of the system.

Resource Association

The resource association will determine how the authentication is handled with the submission. Use New Resource for forms like Registration forms. This will create a new submission and perform the authentication against the new resource. This will both create the user account and log them in. Use Existing Resource for forms like Login forms where users should be checked against existing submissions.

Role

The selected role will be added to all new resources created by the form with this Authentication Action.

Username Field

This is the field on the form that contains the username. If there are embedded resources within the form, you can authenticate against that embedded resource instead of the current form.

Password Field

This is the field on the form that contains the password.

Email Action

The email action allows sending an email when an event occurs on a form.

36 email settings pt 1

Handler

The handler determines when the email will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

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.

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 &#123;&#123; data.email &#125;&#125; where the field name is email.

Subject

The subject of the email. You may use fields from the form using &#123;&#123; data.fieldname &#125;&#125;

Message

The message in the email. You may use fields from the form using &#123;&#123; data.fieldname &#125;&#125;

Nunjucks Templating

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.
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 receive the email.
subject The subject of the email.
message The message of the email.

Nunjucks Filters

In addition to the core filters provided by Nunjucks, the following additional filters are also included for use within Emails.

date Prints out a date value as a readible date. See Nunjucks Date Filter for detailed documentation. Example {{ created | date("YYYY") }}

Nunjucks Macros

In addition to template variables, we also provide a number of macros that can be used to easily render form submission information into your emails. These are as follows.

{{ table(form.components, title) }} Prints out a nested table of the form submission.
{{ submission(data, components) }} Prints out a flat submission data table.
{{ value(key) }} Prints out a readible value for a submission of a certain field. Example {{ value('birthday') }}
{{ label(key) }} Prints out the configured label for a certain field. Example {{ label('birthday') }}

Webhook Action

The Webhook action allows you to integrate form submissions into your custom application, by providing a means to call your external API with the form submission data in real time. In order for the Webhook action to function properly, make sure the API endpoint can be accessed publicly.

Webhooks can not be performed within the “Form Editor”. However, you can see the action take place within the Preview section of your Project.

Handler

The handler determines when the webhook request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Webhook URL

The url of the external system that will handle the web hook.

Authorize User

If you are using Basic Access Authentication for the web hook url, enter the username here.

Authorize Password

If you are using Basic Access Authentication for the web hook url, enter the password here.

Webhook Reciever

In order to receive webhooks, we have created a library that serves to provide a reciever for them. You can download this library at https://github.com/formio/formio-webhook-receiver. Please read the README documents on how to utilize this library.

Testing Webhooks

In order to test webhooks, it is beneficial to point them to your local computer so that you can see them in action. We recommend installing the Webhook Receiver on your local machine and then install and run it using the following command.

npm install
node index.js

This will run the receiver on your Local machine. To connect your local computer to the internet, we recommend using a tool called NGROK. You can download and run the proxy by following the instructions @ https://ngrok.com/download. Once you have this running, you will want to expose the port from the local webhook reciever by typing the following.

ngrok http 4001

You will then see the following…

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 tells me that I can now go to http://941a7c65.ngrok.io and it will hit my local reciever. I can now configure the webhook settings 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 of the webhook reciever library.

You can now submit the form and see the data come through your local machine!

SQL Query Action

The email action allows sending an email when an event occurs on a form.

Handler

The handler determines when the query will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

SQL Server Type

Select the type of server the query will be sent to. Currently two types are supported. MySQL and Microsoft SQL Server. Each type will only be available for selection if you have configured the database credentials in your Project Settings. If you need another type, please contact us.

These are the credentials you may configure in Project Settings:

Server Host

The URL of the server host. This must be publically accessible.

Server Port

The port the server is listening on. This must be open to any firewalls.

Database Name

The name of the database the Query will be run on.

User

The database user name.

Password

The database user password.

Secure Connection (Azure)

If you are using Microsoft Azure and are using a secure connection, check this box.

Query

Enter the SQL query to run. You can use substitutes from the form submission using {{ data.fieldname }}

External ID Field

Many times external databases will generate and return an id when an item is inserted. If you’d like to store this in form.io to associate the two databases together, enter the field name here to store the external id in.

Role Assignment Action

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.

OAuth Action

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:

Action

The action to perform after the user has authenticated against the OAuth provider.

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.

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.

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.

Office 365 Contact

The Office 365 Contact action allows you to integrate form submissions into your Office 365 Contact list. When a new submission is made, this action will add a contact to your Office 365 Contact list. When a submission is updated/deleted, it will update/delete the corresponding Office 365 Contact.

Handler

The handler determines when the contact request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Authentication Method

The method of authentication to use with Office 365.

OAuth Delegated

This method will use the currently logged in user’s OAuth token to authenticate with Office 365. This effectively logs into Office 365 as the current user, and will store all contacts under their account. This is useful if your users will be logging in through Office 365, and you want them to manage their own contacts.

For more information on setting up Office 365 OAuth, see the OAuth guide.

OAuth Delegated requires that users log in via Office 365 OAuth.

Application Certificate

This method will use a client certificate to perform server-to-server authentication with Office 365. This effectively logs into Office 365 as an application, and will store all contacts in a single account. This is useful if you do not want to require that your users log into <form.io> via Office 365 OAuth, and you want to manage your contacts from a single location.

For more information on setting up Office 365 client certificates, see the Office365 guide.

Office 365 Fields

These are all the Office 365 Contact fields you may map your form components to. For example, mapping the Email Address field to an Email component in your form will set the contact’s Email Address field with the data submitted in the Email component.

Office 365 Calendar

The Office 365 Calendar action allows you to integrate form submissions into your Office 365 Calendar. When a new submission is made, this action will add a calendar event to your Office 365 Calendar. When a submission is updated/deleted, it will update/delete the corresponding calendar event.

Handler

The handler determines when the calendar event request will be sent. Currently there are two options. Before and After are the two options. If you select both, it will run twice, once before and once after the methods selected.

Method

When to run this action. Select which system events will trigger this action.

Authentication Method

The method of authentication to use with Office 365.

OAuth Delegated

This method will use the currently logged in user’s OAuth token to authenticate with Office 365. This effectively logs into Office 365 as the current user, and will store all calendar events under their account. This is useful if your users will be logging in through Office 365, and you want them to manage their own calendar events.

For more information on setting up Office 365 OAuth, see the OAuth guide.

OAuth Delegated requires that users log in via Office 365 OAuth.

Application Certificate

This method will use a client certificate to perform server-to-server authentication with Office 365. This effectively logs into Office 365 as an application, and will store all calendar events in a single account. This is useful if you do not want to require that your users log into <form.io> via Office 365 OAuth, and you want to manage your calendar events from a single location.

For more information on setting up Office 365 client certificates, see the Office365 guide.

Subject

The subject of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Body

The body of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Attendees

The attendees of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Time Zone

The time zone of the created event.

Start Time Field

The form field that contains the start date of the created event. This field must be a Date/Time Component.

End Time Field

The form field that contains the end date of the created event. This field must be a Date/Time Component.

Location Field

The form field that contains the location of the created event. This field must be an Address Component.

Categories

The categories of the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

The web link to provide for the created event. You can use substitutes from the form submission using {{ data.fieldname }}.

Atlassian Jira

The Jira Action allows you to integrate form submissions with Jira’s issue tracking. When a submission is made, this action will create a linked issue, in the Jira platform. When a submission is updated/deleted, this linked issue will also be updated/deleted. To get started with the Jira connection, the Atlassian Data Connection is required in the corresponding projects settings.

The Jira action configuration page has the following settings: Blocking: - Whether or not the submission request should block for a Jira response. Useful if you want to confirm a ticket was created. Project: - The Project within Jira that the issue will be associated with. Issue Type: - The type of issue that new issues will be created as, e.g. bug, story, etc. These are pulled from your Jira Project. Summary: - The input field on the form, that you want the issue text to be supplied with.


To use OAuth authentication with Jira, you must first configure your project settings in Form.io, and then in Jira itself. You can start by generating an RSA Keypair.

On OSX/Linux the following will generate a Keypair: Create a key pair openssl genrsa -out key.pem 2048

Extract the public key from the pair openssl rsa -in key.pem -pubout

Display the private key cat key.pem

Copy the contents of the private key, to the project settings for Atlassian. While editing the atlassian settings, add your host name and a random string of letters for your consumer key.

Now login to Jira to create an Application link:

Edit the contents of the connection, to update the Incoming Authentication:

With the application link created, you can now interact with Jira via the Jira Action from within Form.io, using OAuth!

SQL Connector

The SQL Connector Action allows you to integrate form submissions with your own SQL based database and requires your project to be on the Team Pro plan or Above; The SQL Connector Action currently supports Microsoft SQL, MySQL, and PostgreSQL. When a submission is created, it will be created in your database for your consumption via formio-sql. To get started with the SQL Connector, the SQL Connector 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