Form Connector - The Form Submission Step
The Form Submission Step is a feature of the Form Connector Extension (v1.1+) which allows Gravity Flow administrators to add steps to workflows which wait for the submission of a different form.
For example, a workflow which takes a customer through the entire process of a project from initial requirements to final delivery may require payment steps at the beginning, middle and end. The Form Submission step will wait until the payment has been received before allowing the workflow to continue to the next step.
Any number of Form Submissions steps can be added to the workflow.
How it Works
When a workflow is on a Form Submission Step, the assignee or assignees can open the form from the workflow entry detail page like this:
The form can also be opened from the assignee email using the {workflow_form_submission_link} merge tag.
IMPORTANT: The assignee must use either the link in the workflow detail page or the {workflow_form_submission_link} merge tag, otherwise the submission will be ignored by the step. This is because the link includes a security hash to make sure the field mappings are not altered by the user.
When the assignee or assignees have submitted the form, then the step is complete and the workflow is permitted to continue.
Secure Default Field Values
The field mapping setting in the Form Submission step defines the default values for the fields in the target form so that when the form is opened by the assignee, values are already set based on the source entry. All values for mapped hidden fields will be saved immediately after the form submission to ensure that they are not tampered with. A special security token is added to the URL to guarantee that the source entry ID cannot be changed. If the ID is changed in the URL, then the default values will not be displayed.
Multiple Assignees
The Form Submission step can have more than one assignee and it also supports conditional
Support for Payment Add-Ons
By default, the Form Submission step will allow the workflow to continue as soon as the assignee or assignees have submitted the form specified in the step settings. However, if the form has a payment feed configured then the form submission step will wait until the payment has been processed. If the payment was unsuccessful, then
All payment add-ons that are built on top of the Gravity Forms Payment Add-On Framework are supported.
Supported Payment Add-Ons:
If you use a different payment add-on not listed here please contact Gravity Flow support to discuss.
As any number of Form Submission steps can be added to a workflow, it means that multiple payments can be received and associated to a single entry.
The Step Settings
The step settings contain settings which are common to other interactive steps such as the User Input and Approval steps as well as settings that are specific to the Form Submission Step.
Standard Settings
Step Type: Select the "Form Submission" step type and then set the conditional logic and schedule if needed.
Assign to: Assign the step to one or more assignees or define conditional routing.
Instructions: Add instructions to be added to the page above the list of field values.
Display Fields: Select the fields that should appear while the step is pending submissions.
Emails: Send an email to the assignee with the {workflow_form_submission_link} merge tag.
Expiration: Set an expiration for this step if needed.
Form Submission Step-Specific Settings
Form: The step will wait for a submission from the form selected in this setting.
Submission Page: Select the page where the form is embedded. This page will be used to generate the links to the page.
Field Mappings: This setting defines the default values for the target form. You can map simple fields such as the Single Line Text field and email fields, complex fields such as Name and Address fields or you can specify custom values. Custom values support Gravity Forms field merge tags.
Merge Tags
The {workflow_form_submission_link} and {workflow_form_submission_url} merge tags are available for the assignee email.
You can specify multiple values with these merge tags:
- Custom text for the {workflow_form_submission_link} as {workflow_form_submission_link: text="Open the payment form"}
- Custom Step/Assignee for either merge tag. Very useful for sending the user directly to the submission form from the initial form confirmation. Basically however your Form Submission Step Assignee is defined can also be used in the merge tags:
- By assignee field: {workflow_form_submission_url: assignee=assignee_field|5 step=3}
- By user field: {workflow_form_submission_url: assignee=assignee_user_field|4 step=3}
- By email field: {workflow_form_submission_url: assignee="email_field|2" step="3"}
- By individual user: {workflow_form_submission_url: assignee=user_id|15 step=3}
Note that the link will only be active/correct if the entry is on the Form Submission step at the time the user clicks it.
Updating the original entry
If you need to update the original entry with the values from fields in the form submissions, then you can add an Update Entry step to the target form. Ensure that the field mappings in the form submission step include the entry ID of the original entry so you can select it in "Entry ID field" setting of the Update Entry step. This can be a great alternative to the User Input step for forms with a lot of conditional logic, or forms with custom or third-party code which might be causing issues.
Configure the Form Submission + Update an Entry steps together
This intermediate/advanced configuration tutorial also covers the use of workflow form submission merge tags in the confirmation message to create a seamless user experience as the appropriate parts of their data move between forms.
Integration with the Parent-Child Forms Extension
If you'd like to access the entries submitted in the Form Submission step easily from the source entry, then you can use the Parent-Child Forms Extension.
One of the security features of the Form Submission step is the security token which prevents tampering with the source entry ID. This makes the Form Submission step very useful for the Parent-Child Forms Extension in situations where the parent entry ID sent to the child form needs to be secured.
Other considerations
The Form Submission step only listens for submissions from forms from pages with URLs that contain the security token. If the form is submitted without the security token, then the Form Submission step will ignore it.
The Form Submission Step only listens for submissions of forms on the same site. If you need to listen for form submissions on different sites, please contact Gravity Flow support and add your vote for the feature.
Limitations
The Form Submission step cannot map file upload fields.
Troubleshooting
When the Form Submission step is assigned to an email assignee a warning may be displayed when the assignee accesses the submission link from email: 'The link to this form is no longer valid'. The issue can be resolved by excluding the submission page from caching. Some hosting services (e.g. WP Engine) cache aggressively. You may need to ask your host to remove the page from the cache.