Actions

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 {{ 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
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 receivie the email.
subjects
The subject of the email.
message
The message of the email.
Nunjucks Filters
In addition to the core filters provided by Nunjucks, the following additional filters are also included for use within Emails.
date
Prints out a date value as a readible date. See Nunjucks Date Filter for detailed documentation. Example {{ created | date("YYYY") }}
Nunjucks Macros
In addition to template variables, we also provide a number of macros that can be used to easily render form submission information into your emails. These are as follows.
{{ table(form.components, title) }}
Prints out a nested table of the form submission.
{{ submission(data, components) }}
Prints out a flat submission data table.
{{ value(key) }}
Prints out a readible value for a submission of a certain field. Example {{ value('birthday') }}
{{ label(key) }}
Prints out the configured label for a certain field. Example {{ label('birthday') }}
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.
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 web hook. 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 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.
Additional Headers
You can add additional headers as needed. These typically are adding 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 payload will be sent as the body of the request.
Wait for webhook
By default webhooks continue on to other actions before the request finishes. If you check this box it will wait for the webhook to finish before continuing and return the results to the frontend in the metadata field.
External Id Type and Path
If the webhook endpoint creates a data object in the external system there is often an id number created and returned in the response. If you want to save this and associate it with the submission in form.io you can specify a type and id path here. The type name is the key it is stored in the database (for example: github or alfresco). If you use the same type name in multiple webhooks it will associate with the same id. The id path is the location of the id in the response object from the webhook endpoint. This is used to get the id out of the data object.
Webhook Receiver
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.
1
npm install
2
node index.js
Copied!
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.
1
ngrok http 4001
Copied!
You will then see the following…
1
Version                       2.1.14
2
Region                        United States (us)
3
Web Interface                 http://127.0.0.1:4040
4
Forwarding                    http://941a7c65.ngrok.io -> localhost:4001
5
Forwarding                    https://941a7c65.ngrok.io -> localhost:4001
Copied!
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!
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:
​GitHub​
​Facebook​
​Office 365​
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.
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 }}.
Web Link
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 Connections required in the corresponding projects settings.
To get started go to Settings -> Data Connections -> Atlassian and input your Atlassian URL without protocol. Then add your Atlassian login credentials.
Once configured, create or edit any form which you intend on adding the Jira action to.
Once constructed click the Action tab.
In the dropdown find and select the Jira (Premium) option, then click Add Action.
If everything is configured correctly, the Jira action can now be configured and integrated into your form.
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.
User Summary:
The input field on the form, that you want the issue text to be supplied with.
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