DocuPhase Forms latest - This documentation is for DocuPhase Forms v11.3. Not for you? Earlier documentation is available too.

Form and Doc Actions

Owned by Megan Ellis
Last updated: Jul 08, 2024
20 min read

Wizards make it easier to configure what happens to the data when a user submits your form and what the users see after submitting the form. Configure Form Actions (what the user sees) and Document Actions (what happens to my data) on the associated tabs in the Settings wizard. 

 

v11.3 Workflow Actions.PNG

 

  • Form and Document Actions functions for workflows are very similar to those for forms. The term "Form Actions" used on this page also refers to "Workflow Actions".

  • Forward to PayPal is not available in workflows, but can be configured following this documentation.

  • Document Actions that happen in between steps are known as Activity Doc Actions. See the Activity Doc Action documentation for details.

On this page

Form/Workflow Actions

The Form/Workflow Action wizards help set up what the user sees when the form/workflow is submitted. You can access the Form/Workflow Action tab in the Guided Designer Settings mode.

image-20240605-201021.png

The wizards help guide you through the configuration process. Many of the wizards allow you to use form controls as templates to dynamically personalize what the user sees. See the section on Using Templates for full details. Hover over any field in the wizards for a helpful hint.

You can configure one of the following actions for a form/workflow.

  • Display Message when user submits form

  • Forward users to a web page of your choice

  • Post data and forward users to your web page

  • Forward to Paypal to complete payment (Forms only)

Display Message when User Submits Form

After the user submits the form/workflow, the browser will display a standard DocuPhase Forms page with a text message. For example, the message might say, “Thank you for completing our form.” You supply the specific text in the Message field. This option works best for relatively brief messages. It can be tricky to enter or edit large amounts of text in the wizard's Message field, so for verbose messages consider creating a simple HTML page for your message and choosing the Forward User to your Web Page wizard.

The message can be customized, using the wizard's control dropdown, with values the user enters into the form. For example, if your form contains fields named firstName and lastName, you can set your message to "Thank you {firstName} {lastName}". Now when a user submits the form the controls templates {firstName} and {lastName} will automatically be replaced with field values "Thank you Joe Smith". See Using Templates for full details.

Another useful message is to display a link back to the form. For example the display message:

The display message would be written as follows. The URL back to the form is the share dialog Raw Form link.

Thank You!<br/><br/> {Company}'s account will be created within 24 hours.<br/> A "A New Account" email will be sent to {Email}.<br/><br/> <i>RedStone Customer Support</i><br/><br/> Click <a href="http://test.frevvo.com/frevvo/web/tn/redstone/user/designer/app/_OLlAYUouEd-0jOS-XMShUg/formtype/_YRsQYEyBEd-OltN4g8wchQ?_method=post &embed=true&locale=">here</a> to request another demo account

The form/workflow URL in the above HTML example can be constructed dynamically in a business rule. See this rule example.

Javascript is not allowed in the display message. Plain text, HTML, and control templates are allowed. Anything else will break the message and nothing will be displayed.

Some designers want to show a logo or other image in the Form Action Message. You can do this using HTML. If your logo is stored on a static site, you can point the HTML img tags to that image. However, if you prefer you can store the image right within the DocuPhase Forms form.

  1. Add an image control to your form. You can uncheck the Visible and Printable properties if you do not want to display them to users in the actual form.

  2. Upload your logo or another image.

  3. Right-click the image control and select "Copy image address".

  4. Paste the image address into the HTML img tags, as in this example.

    Thanks for completing your Employee OnBoarding, and welcome to the team! <br/><br/><img src="https://app.frevvo.com/frevvo/web/tn/frevvodocs/u/e1dd0efb-f368-4e60-937a-fe08849485d5/app/_WtkW4A9KEeOGyY8morCUKA/formtype/_BuFnUJW0EeyG_9ERIIwC7A/asset/_ESA8oZW0EeyG_9ERIIwC7A_languageballoons.png" style="width:200px;height:100px;"/>

  1. When the user completes the form, the image will display in the Form Action Success Message.

This method to use an image from your form in the form action message will also work for Workflow Step Pending Messages.

Show In

Both the display message wizard and the forward to web page wizard allow you to select where the message is displayed on the page using the "Show In" dropdown. There are three choices: Frame, Parent and Top. This tells the browser where to show the text (if you chose Display Message) or the new Web page (if you chose the Forward to Web Page).

  • Frame means inside the form's iframe

  • Parent means inside the form iframe’s immediate parent

  • Top means at the top of the page, regardless of how many parents are outside the iframe.

Forward Users to a web page of your choice

After the user submits the form/workflow, the browser will be redirected to another URL, which you supply in the  URL field. You must include the http:// prefix (e.g., http://myhost.com/thankyou.html). The project can have a Form Action Base URL which you set in the project properties. For example, you can have http://myhost.com/ in the project baseURL and simply “thankyou.html” in the Form Action URL field.

You can use a form/workflow field template in the URL field. Ex: http://localhost:8082/{URL!encode=false}. The encode=false template parameter is important to avoid mangling the URL. See Templatized String Parameters for details.

Show In

These are the same options as described under the display message wizard above. Unless you have created a special page that you know will fit correctly within the form’s iframe you should not choose iframe. Choose the Parent or Top option instead.

Forward to another Form

You can forward the user from one DocuPhase Forms form to another by specifying the raw URL of the second form in one of the Form Action wizards in the first form. When the user clicks Submit on the first form, you can choose to:

  • Display the second form with data passed from the first form - use the Post data and forward users to your web page wizard.

  • Display the next form without the data - use the Forward users to a web page of your choice wizard.

Suppose you have two forms in your project. One named ''formA'' and the other named ''formB''. When the user clicks the submit button on formA you want them to see formB next.

  1. Edit formA

  2. Select the Settings mode.

  3. Select the Form Actions tab.

  4. Select the Forward users to a web page of your choice

  5. Enter the raw form URL for formB in the URL property field.

  6. Click Submit then save the form.

  7. Browse the URL for formA, click Submit. formB displays.

The raw form link URL can be found by clicking Share for formB on the Forms and Workflows Home Page.

Here is an example of a formB's raw form URL:

https://<your server>:<your port>/frevvo/web/tn/<your tenant name>/u/60b97620-6e5b-4d97-a93e-6b81e803a671/app/_mzwYwGMrEeeemceeobqUCg/formtype/_6NZG8GMrEeeemceeobqUCg?_method=post&embed=true

For portability, we recommend you use relative URLs such as:

Post Data and forward users to your web page

After the user submits the form, the browser will POST the user’s data to the URL you specify in the wizard’s URL field and display whatever is returned—the next page to display.

Fill in the Post Submission to your Application wizard with the following information:

  • Enter the URL to the application where you want to post data:

    • Your URL field must include the http:// prefix (e.g., http://myhost.com/services/processPayment). The project can have a Form Action Base URL which you set in the project properties. For example, you can have http://myhost.com/services/ in the project baseURL and simply “processPayment” in the Form Action URL field.

    • The URL can also include control templates. This can be useful when you wish to specify a production versus a test server. For example: http://{serverURL}/services/processPayment/{customerId}. Using this form URL, you can specify serverURL using &_data=(serverURL:'testhost'). This makes switching from a test server to a production server a matter of setting the form URL parameter "serverURL" rather than editing the form itself. See Initializing Forms with Data for more details on _data usage.

    • You can use a form field template in the URL field. The encode=false template parameter is important to avoid mangling the URL. See Templatized String Parameters for details.

  • Send the data as a PDF attachment or other image type using the Send Snapshot dropdown. The image type options are PDF, PNG or JPG.  Select the blank option from the dropdown to exclude this attachment in the submission.

  • Attach an XML data document using the Data checkbox. This checkbox is checked by default. Uncheck it to exclude the XML data document in the submission.

  • Attachments uploaded to your form/workflow are included if the Attachments checkbox is checked. This checkbox is checked by default. Uncheck it to exclude attachments in the submission.

  • If you have Pixel Perfect mapped PDFs (ex: W-4, I-9 etc…) associated with your forms/workflows, choose  the action you want to take from the Send Generated PDF Forms control:
    • Check All to send all the mapped PDFs. This is the default value.
    • Check None to send none of the mapped PDFs.
    • Check Select to display a list of all the mapped PDFs associated with your form/workflow. Click the ones you want to be part of the submission. Click again to deselect.

  • POST responses must be displayed in the DocuPhase Forms form frame.

Passing Data from One Form to Another

If formA and formB both contain the same data source, and the Form Action in form A is set to '''Post''' to the raw form Url of form B, then form B's fields from schema will be initialized with the values entered into form 1. Follow these steps:

  1. Create formA and formB from the same schema.

  2. Edit formA

  3. Select the Settings mode.

  4. Select the Form Actions tab.

  5. Select the Post data and forward users to your web page wizard.

  6. Enter the raw form link for formB in the URL property of the wizard. Here is an example of the raw link share URL

    Remember, you can use a relative URL if you are concerned with portability.




  7. Test formA by filling in the fields and clicking Submit. formB displays with the fields populated with the data in formA.

Using Templates

Fields in form B can also be initialized with data from form A using Url Parameters. Imagine form A contains a from palette text control labeled 'Customer Name' with Name property set to 'custName'. And form B has a palette text control labeled 'Full Name' with Name property set to 'fname'. Using either Form Action Forward to Webpage or Post with the URL set to that of Form B, append &_data=(fname:'{custName}') and when form B loads it's 'Full Name' field will be set to the value entered into form A's 'Customer Name' field.

See initializing via _data Url Parameters in the Initializing Forms with Data section for more details on using _data.

Forward to Paypal to complete payment

When the form is submitted, users will be forwarded to Paypal to complete payment. This multi-step wizard guides you through configuration:

  • Paypal account login

  • Paypal invoice description based on form values

  • Paypal payment amount from form values

and more...

Paypal for Workflows

Workflows do not have a corresponding "Forward to PayPal to complete Payment" action. However, you can configure either the Workflow Action: Forward users to a webpage of your choice or a link control in an individual step to connect to PayPal from a workflow. 

Replace the values in the <> brackets in the examples with your values. (These parameters are explained below.) You can also substitute the value of a form control in the below URLs using templates, for example: to use a control named "amount" in the URL, configure it as:

PayPal Sandbox: https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_xclick&business=<Paypal business name>&amount=<Payment amount>&item_name=<Payment Description>&currency_code=<Currency Code>&return=<Return URL>&cancel_return=<Cancel URL>&custom=<Custom Value>&invoice=<Invoice Value>&notify_url=<Notification Url>

Production: https://www.paypal.com/webscr/webscr?cmd=_xclick&business=<Paypal business name>&amount=<Payment amount>&item_name=<Payment Description>&currency_code=<Currency Code>&return=<Return URL>&cancel_return=<Cancel URL>&custom=<Custom Value>&invoice=<Invoice Value>&notify_url=<Notification URL>

URL Parameters

  • Paypal business name: Paypal business name. Typically, this is the email address you use to sign in to Paypal.

  • Payment amount: The payment amount.

  • Payment Description: The payment description is what your users will see when paying.

  • Currency Code: The currency code used in payment. Example: USD, CAD, INR

  • Return URL: A user will be redirected to this page after payment is complete. If you leave this blank, users will be redirected to a standard platform URL. 

  • Cancel URL: A user will be redirected to this page if payment is canceled. If you leave this blank, users will be redirected to a standard platform URL.

  • Custom Value: PayPal will return this custom value in the IPN as well as the acknowledgment email.

  • Invoice Value: PayPal will return this invoice value (such as an Invoice Number) in the IPN as well as the acknowledgment email.

  • Notification URL: A notification URL. If you enter a URL here, PayPal will notify you using Instant Payment Notification. Please see the PayPal documentation for details.

Workflow Action: Forward Users to a Webpage of Your Choice

Open the workflow properties, and select the Workflow Actions tab. Click the Forward Users to a webpage of your choice radio button. Add the URL (configured like this example) to the URL field. After submitting the last step, the user will be redirected to PayPal for payment processing.

Example: https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_xclick&business=mycompany@gmail.com&amount=2&item_name={BMyDesc}&currency_code=USD&return=http://localhost:8080/frevvo/web/tn/t1/u/53f402db-5ef2-4052-95a0-a44a2d000832/app/_JuJjkWogEeq1EfoSPaFbFA/formtype/_6Vmn0G02EeqEf75e1_YeJg?_method=post&embed=true&cancel_return=http://localhost:8080/frevvo/web/tn/t1/u/53f402db-5ef2-4052-95a0-a44a2d000832/app/_JuJjkWogEeq1EfoSPaFbFA/formtype/_6Vmn0G02EeqEf75e1_YeJg?_method=post&embed=true&custom=123&invoice=123&notify_url=

Individual Step

If you need PayPal integration in specific step of a workflow, add a link control in that step with above URL and set return URL pointing back to current step of the workflow using built-in data. They can then submit the step and the workflow will continue as designed.

Example: https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_xclick&business=mycompany@gmail.com&amount=2&item_name={BMyDesc}&currency_code=USD&return=http://localhost:8080/frevvo/web/tn/{form.tenant.id}/u/{form.user.uuid}/app/{form.application.id}/flow/{flow.id}/current?typeId={flow.type.id}&cancel_return=http://localhost:8080/frevvo/web/tn/{form.tenant.id}/u/{form.user.uuid}/app/{form.application.id}/flow/{flow.id}/current?typeId={flow.type.id}&custom=123&invoice=123&notify_url

Document Actions

The document action wizards configure what happens to the entered data when a user submits your form/workflow. You can access the Document Actions tab in the Guided Designer Settings mode.

The wizards help guide you through the configuration process. Hover over any field in the wizards for a helpful hint.

This wizard has two tabs as shown in the screen image below:

  • Send Documents

  • Send Data

Send Documents

Using this wizard you can do up to five of the following actions

  • Email the data to an email address

  • Post the form data to your web application

  • Save the DocuPhase Forms submissions to a local or remote filesystem using the Filesystem connector.

  • Save submissions to an External System such as DocuPhase Pro, Google or SharePoint

Each action’s page will guide you through connecting your forms/workflows to the chosen destinations. Many properties allow you to use form controls as templates to dynamically configure wizard parameters. For example, you can dynamically set the email address to send the data to instead of hard coding an email address. See the section on Using Templates for full details.

Add Send Documents Action

If you designed your workflow using the Workflow Design Wizard, you’ll have a Send Email document action by default. To add your first document action, or an additional one, follow these steps.

On the Send Data tab, click ADD DOCUMENT ACTION.

A new section will appear with the warning NOT CONFIGURED, and a dropdown to select a Document Action. Notice there are two tabs, Action and Precondition.

From the Action dropdown, choose a Document Action.

Configure the Document Action (see paragraphs below for details about each).

Doc Action Precondition

Optionally, select the Precondition tab. Configure the Precondition just as you would for a step or mapped PDF.

As with step preconditions, only value-based conditions are available. The configured Doc Action will run only when the Precondition resolved to “true”.

Doc Actions List

Notice that when you return the list, the chosen Action and the Precondition description is displayed. Once you have chosen five Document Actions, the ADD DOCUMENT ACTION button disappears.

No Send Document Actions Configured

If you do not configure any Send Document actions, the data is simply stored in DocuPhase Forms' submissions repository. (The other options also store the data in the repository but provide additional functionality.)

You may not configure any Send Document action when you plan to do one or more of the following: 

Send Email

When the form/workflow is submitted, DocuPhase Forms will send an email message with the following selectable options attached. These include submission data,  an XML document, an image of the filled form/workflow, attachments uploaded to the form/workflow, and any, all, or none of the Generated Forms (mapped PDFs) associated with your form/workflow.

Fill in the Send Email wizard with the following information:

  • Enter destination email addresses in the To: Reply to: Cc;, Bcc: fields. The email can be sent to multiple addresses separated by a comma or a semicolon. The "To:" email address is required. All other email fields are optional.

  • Customize the email body and Subject text in the Message field. You can use HTML and templates.

  • Send the form/workflow data as a PDF attachment or other image type using the Send Snapshot dropdown. The image type options are PDF, PNG or JPG.  Select the blank option from the dropdown to exclude this attachment in the submission.

  • Attach an XML data document using the Data checkbox. This checkbox is checked by default. Uncheck it to exclude the XML data document in the email.

  • Files uploaded to your form/workflow are included if the Attachments checkbox is checked. This checkbox is checked by default. Uncheck it to exclude attachments in the submission.

  • If you have Pixel Perfect mapped PDFs (ex: W-4, I-9 etc…) associated with your forms/workflows, choose  the action you want to take from the Send Generated PDF Forms control,

    • Check All to send all the mapped PDFs. This is the default value.

    • Check None to send none of the mapped PDFs

    • Check Select to display a list of all the mapped PDFs associated with your form/workflow. Click the ones you want to be part of the submission. Click again to deselect. 

See Email Integration for further details.

POST data to your web application

When the form is submitted, DocuPhase Forms POSTs the document set to the specified URI and ignores any returned XHTML or redirect. This option may be used for the additional processing of data. Use Form Action: Post data and forward user to your webpage if you want to both submit data to your URI and forward to a web page or display returned XHTML.

Fill in the Post Data to your web application wizard with the following information:

  • Enter the URL to the application where you want to post data:

    • Your URL field must include the http:// prefix (e.g., http://myhost.com/services/processPayment). The project can have a Form Action Base URL which you set in the project properties. For example, you can have http://myhost.com/services/ in the project baseURL and simply “processPayment” in the Form Action URL field.

    • The URL can also include control templates. This can be useful when you wish to specify a production versus a test server. For example: http://{serverURL}/services/processPayment/{customerId}. Using this form URL, you can specify serverURL using &_data=(serverURL:'testhost'). This makes switching from a test server to a production server a matter of setting the form URL parameter "serverURL" rather than editing the form itself. See Initializing Forms with Data for more details on _data usage.

    • You can use a form field template in the URL field. The encode=false template parameter is important to avoid mangling the URL. See Templatized String Parameters for details.

  • Send the data as a PDF attachment or other image type using the Send Snapshot dropdown. The image choices are PDF, PNG and JPG. Select the blank option from the dropdown to exclude this attachment in the submission.

  • Attach an XML data document using the Data checkbox. This checkbox is checked by default. Uncheck it to exclude the XML data document in the submission.

  • Attachments uploaded to your form/workflow are included if the Attachment checkbox is checked. This checkbox is checked by default. Uncheck it to exclude attachments in the submission. 

    • If you have mapped PDFs (ex: W-4, I-9 etc…) associated with your forms/workflows, choose  the action you want to take from the Send Generated PDF Forms control :
      •Check All to send all the mapped PDFs. This is the default value.
      •Check None to send none of the mapped PDFs
      •Check Select to display a list of all the mapped PDFs associated with your form/workflow. Click the ones you want to be part of the submission. Click again to deselect.

Send to File System

The Save to Filesystem wizard is used to connect forms/workflows to the DocuPhase Forms Filesystem Connector. The connector saves submissions in a specified location and can be configured to create metadata files for importing your submissions into a document Management system.

Refer to the Filesystem Connector chapter for the installation and configuration details plus information about using the Save to File System wizard and generating metadata.

Send to External System

You can connect forms/workflows to a DocuPhase Forms-provided connector that your admin has configured in the Manage Connectors page using the Send to External System doc action. The connectors currently available are listed (follow links for configuration details.)

Legacy Connectors

Some customers may be utilizing the legacy Google Connector or the legacy SharePoint connector. These are deprecated, meaning they will not receive bug fixes or further enhancements, and will be removed in a future release. Please review the following documentation for legacy connector settings, and plan to migrate to our new Google and/or SharePoint connectors at your earliest convenience. See Migration Considerations for more details.

Send Data

Using these wizards you can:

  • Do Nothing

  • Post submissions to a Google Spreadsheet

  • Manually set document URIs - to connect to database and other back-end systems

The Send Data wizards enable you to manually set a URI to which the data will be sent when your form is submitted.

Do nothing

This is the default option. Selecting Do nothing will also clear the other options if they are set.

Post Submissions to a Google Sheet

DocuPhase Forms supports direct connectivity with Google Spreadsheets. This wizard allows you to save submissions directly into Google Spreadsheets. It also provides additional assistance in setting up the login to your Google account and in selecting the spreadsheet.

After the user submits the form, the data will be written into a new row in the Google spreadsheet. This wizards steps you through the process of logging into your google account and locating the spreadsheet you where you want to save the submissions.

See the DocuPhase Forms Save your Submissions to a Google Sheet for details.

Manually set document URIs

See  the chapter on connecting to your database for all the details.

Using Templates in Form and Doc Actions

The values in most form, workflow and doc action wizards can be customized with data entered in the form/workflow using templates.

For instance, in the display message, you may wish to display a customized message with the user's name. You can use templates in the display message to do this.

  • Make sure you have two controls in the form called FirstName and LastName.

  • Click on Form Action

  • Click on Display a Message.

  • In the Message area of the wizard, type: Thank You {FirstName} {LastName} for submitting my form.

  • As a shortcut, you can also select the appropriate control from the drop down by clicking the down arrow on the right side of the field.

  • Click Finish.

Use the form by clicking on the Test button. Enter something into the First Name and Last Name controls. When you click submit, the message will display with {FirstName} and {LastName} replaced by the values you entered, e.g. Thank You Jeff Smith for submitting my form.

When referring to repeat controls you must use a special template syntax. See templates for repeat control for details.

Form & Doc Action Failure Notifications

An email notification is sent to all tenant administrators or the workflow administrator(s) (if configured) when a Form Action post, Doc URI or Doc Action fails and the submission does not reach it's intended destination. This is not applicable to the email doc action since it is asynchronous and the notification would fail if the service were unavailable.

The email will have a subject line like Doc Post failure from <server> for <Form/Workflow>. For example, “Doc Post failure from app.frevvo.com for SharePoint Demo”. If you’re using DocuPhase Forms On Premise, your server name will be reflected instead of ‘app.frevvo.com’.

The email body will explain the error.

Could not POST data to <URL>. <Error Code> Form : <Form/Workflow name>Tenant :<Tenant name> Designer : <Form/Workflow owner ID> Application : <Project name>

Example:

Could not POST data to http://sharepoint-connector:8080/sharepoint/submission. HTTP status 500 Form : SharePoint Demo Tenant : frevvo Documentation Designer : designer Application : Sharepoint

The URL will help you know which connector/action the error refers to. For instance, SharePoint connector URLs include ‘sharepoint-connector’, Google connector URLs include ‘google-connector' and either the word ‘documents’ or 'spreadsheets’ to tell you which action failed.

To resolve these errors, follow these steps:

  1. Go to the Submissions View for the form/workflow that generated the error. (See Submission Errors documentation)

  2. Identify the connector/action that is the issue.

  3. Examine the target system to see if the documents/data were posted. Sometimes items will post, but the response takes too long to return to DocuPhase Forms and there is an error.

    1. If the documents/data are in the target system, you may disregard the error.

    2. If the documents/data are missing, continue to step 4.

  4. Check the following common issues:

    1. Are all submissions failing or only one?

      1. All:

        1. Is the connector/service running?

        2. Are the service credentials accurate and up to date?

      2. Only one/a few

        1. Are there any special characters in file or folder names that may not be allowed?

    2. View connector logs.

      1. Database and Filesystem logs are always on the customer’s server.

      2. Other connector logs are available if you are On Premise. Cloud customers contact support@frevvo.com and supply the exact error message you received and a screenshot of the submissions page with error and date/time of submission visible. Support can examine Cloud logs for more specific errors.

  5. Resolve the issue identified in Step 4.

  6. Optionally, resubmit errored flows. This will re-post documents/data, and will also re-run all document actions (including email).