This documentation is for Live Forms 7.3 Not for you? Earlier documentation is available too.

Skip to end of metadata
  • Created by Former user, last modified by Former user on Jul 13, 2018
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Current »

Saving submission data from an automated frevvo form or workflow to your box account, is easily done with the Box connector and the Save to box.com wizard. Once the connector is installed (in-house) and configured, simply run the Save to box.com wizard to connect your form/flow to box. Submissions from  are posted to the Box Connector using the Doc Action Save to box.com wizard.

You can also choose which documents get saved including generated files e.g. a Government W-4 for an Employee On-Boarding workflow.

When the form or flow is submitted, the selected documents, such as Student Registrations, Purchase Orders, mapped PDFS like a W-4, Patient Referrals etc, are uploaded to your box account to the specified folder. Once in box, you can use all their features to collaborate, share and manage the documents.

Signatures are not saved as they are a different content type than attachments.

The Box Connector is available for cloud and in-house  customers. All customers will need a valid Box account.

frevvo only supports/certifies the Box Connector running in the Apache Tomcat container.

In-house customers must perform a few additional configuration steps as described below

On This Page:

Installing the Box Connector

Cloud Customers

If you use the Live Forms Cloud hosted server, the connector is already installed and configured. You can immediately begin to Connect your Forms/Flows using the Save to Box.com wizard.

In-house Customers using the frevvo Tomcat bundle

The Box connector can be installed behind your firewall where it can connect to your back end system in order to read/write data. These instructions assume you have an in-house installation of  up and running and you are using the frevvo Tomcat bundle:

To install the Box connector in the same tomcat as :

  1. Stop .
  2. Download the box connector zipflile from here. 
  3. Extract the box.war file to your <frevvo-home>\tomcat\webapps directory.
  4. Create a Box.com Application for Live Forms
  5. Configure the Box Connector - (In-house only)

Create a Box.com Application for Live Forms

You must create a content API application for . A tutorial that will walk you through the basics is available on this  website.

 Click here for information specific to the box application for Live Forms

Follow these steps;

  1. Navigate to https://developer.box.com/ and signup for an account.
  2. Navigate to the same link and login. Click Getting Started on the My Applications screen.



  3. You are prompted to create an box application. Give the application a unique name (name has to be unique across entire ecosystem of developer applications (both private and public)).



  4. On the General Information section of the screen, the application name and support email will be prefilled. Verify that the Content API Access Only button is checked.



  5. On the OAuth2 Parameters section of the screen,
    1. Copy the client_id and save it somewhere. You will need this to configure the frevvo.xml file in .
    2. Copy the client_secret and save it somewhere. You will need this to configure the frevvo.xml file in .
    3. Enter the base uri for your installation in the redirect_uri field. Change the <your server name> and <port #> shown in the image to your information:
    4. Verify that Read and Write all files and folders stored in box is checked in the Scope section. This is the only scope required by .



  6.  Save the box application.

Configure the Box connector (in-house only)

The Box connector is configured using context parameters in the file, frevvo.xml.

Follow these steps:

  1. Navigate to <frevvo-home>\frevvo\tomcat\conf\Catalina\localhost directory.

  2. Edit the frevvo.xml file.

  3. Locate the Box Connector section of the file.

  4. Add the client id that you copied and saved earlier as the value of the frevvo.box.connector.client.id parameter. Paste the client id for the box application that you created for in between the quotes.

  5. Add the client secret that you copied and saved earlier as the value of the frevvo.box.connector.client.secret parameter. Paste the client secret for the box application that you created for in between the quotes.

  6. Save the changes to the frevvo.xml file.



  7. Start . If you are running v7.1+, remember to  start the Insight server first.

  8. Browse http://<your server:port>/box/health (replace <your server:port> with your frevvo server:port) to check the status of the connector. If the connector is up and running, you will see { "status" : "UP" }.
  9. Proceed to Connect Forms/Flows with the Save to Box.com wizard

Connect Forms and Flows with the Save to Box.com wizard

  1. Login to your box account and create a folder for your form/flow. Let's say you have an Employee On-boarding workflow and you want to store all of the submissions in a folder named Employee On-Boarding.

    To ensure interoperability across file systems, it is recommended that you follow a good naming standard such as POSIX when creating files and folders. For example, folder names can't contain slashes so a folder named '1/2/15' would not be valid.

  2. Create your form or flow as usual. Generate a frevvo-PDF,map to your custom PDFs, upload attachments if required.
  3. Login as a  designer user.

  4. Click the Edit icon to open your form/flow.

  5. Click on the what happens to my data? icon on the designer toolbar.

  6. Select the Save to box.com option.



  7. In the wizard that pops up, provide your credentials. You’ll be redirected to login to box if you are logging into your account for the first time.
    1. On successful login, you are asked to either grant or deny permission to the scopes specified in the box application that you created earlier. Click the Grant Access to Box button to continue.



    2. When granted permission, the Oauth token is generated and stored in . The wizard will login to your box account, browse to find available folders and display them.

  8. Select a parent folder (e.g. Employee On-boarding) and a submission folder. Let's say you want the name of the submission folder that contains the documents to be the new employee's First Name and Last Name,. Use a template that’s dynamically generated e.g. {FirstName} {LastName}. You can select the fields in your form/flow by clicking on the dropdown to the right of the Submission folder field.



    Select the types of documents you want to send to box as part of the submission. The choices are:

    • 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 Send Data checkbox. This checkbox is checked by default. Uncheck it to exclude the XML data document in the submission.
    • Attachments uploaded to your form/flow are included if the Send Files 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/flows, choose  the action you want to take from the Send Gen Forms control:

      • Check All to send all the Pixel Perfect PDFs. This is the default value.
      • Check None to send none of the PDFs
      • Check Select to display a list of all the PDFs associated with your form/flow. Click the ones you want to be part of the submission. Hold down the Shift key then click the files in the list to select all PDFs or hold the control key and click specific PDFs.
  9. Click Finish.

  10. Save your form or flow by clicking the save and exit icon.

  • If you do not select a parent and submission folder, submission files are stored under the box account root folder
  • When the parent folder field is specified and the submission folder is not ,submission files are stored under the parent folder.
  • When the submission folder field is specified and the parent folder is not,  a submission folder is created under account root folder.
  • Folder names should not contain a / or \

Check Submissions on box.com

When the form or flow is submitted, the documents will be uploaded to your box account in the specified subfolder. All subfolders reside in the parent folder (Employee On-Boarding in our example).

Once in box, you can use all their features to collaborate, share and manage the submission documents.

Follow these steps to verify your stored submissions on box:

  1. Test your form/flow, fill in data, add attachments, sign the form etc. and submit it.
  2. Login to your box account and navigate to the folder you created earlier. See that it now contains a subfolder. The subfolder is dynamically named based on form data e.g. FirstName and LastName fields in the flow. Every time a workflow is submitted a new subfolder is created in this parent folder.
  3. Inside the subfolder, you’ll see the uploaded files e.g. the frevvo generated PDF, a Federal W-4 and I - 9 and the form xml document. You can click on the PDF to preview it directly in the box UI.



Box will not open files without a file extension. Be sure to include the file extension in the name of any acroforms uploaded to for mapping Pixel Perfect PDFs.

Same Named Files show Revision Number on Box

Typically, a new subfolder is created on Box for each submission. Let's say you decide to send a submission to an existing subfolder and in the submission there are file(s) with the same name as file(s) that are already stored in the existing subfolder, It is reasonable to expect that the existing file will be overwritten by the new file with the same name or there will be 2 files with the same name in the existing subfolder .

Box handles this situation by:

  • Creating a new version of the file and assigning it a revision number
  • If you are using a free box acocunt, you will only have access to the latest version. For a developer/premium accounts, users can see the version history and download the previous versions of a file if necessary.

For example, an Employee On-boarding for Max Jones stores mapped PDFs of the I-9, W - 4, Connecticut W - 4 and the workflow after the first submission. Max runs through the  Employee On-boarding a second time resulting in files with the same name as those generated from the first submission. Viewing the subfolder for Max Jones shows revision numbers for version 2 of each file

Troubleshooting

The Box Connector generates it's own logfile. Typically, the log is first place to look for information when an issue is encountered. Information about the logfile and some common issues with solutions are listed below.

Box Connector Logfile

The Box Connector log is located in <frevvo-home>\tomcat\logs in the tomcat bundle. The logfile is named box.YYYY-MM-DD.log. Searching a separate logfile makes it much easier to search for errors when troubleshooting connector issues. The connector is designed to use the frevvo-config.properties file.

The default loglevel for the Box logfile is INFO. To configure DEBUG level logging for the Box Connector log:

  1. Stop
  2. Create/edit a frevvo-config.properties file in <frevvo-home>\tomcat\conf
  3. Add the logging.level.com.frevvo.connectors.box=DEBUG property to the file. NOTE: the syntax of the property is logging(dot)level(dot)com(dot)frevvo(dot)connectors(dot)<connector name>=DEBUG
  4. Save the file
  5. Restart 

logging.level.com.frevvo.connector.box=DEBUG

Property to turn on JSON logging

To create a JSON version of the Box Connector logfile, follow these steps:

  1. Stop
  2. Create/edit a frevvo-config.properties file in <frevvo-home>\tomcat\conf

  3. Add the spring.profiles.include=logging-json property to the file.

  4. Save the file
  5. Restart 

spring.profiles.include=logging-json

Doc Post Failure

If the submission doesn't reach box.com, all tenant administrators or flow admins (if configured)  will receive a Doc Post Failure notification email reporting information about the error.

Determine the version of the Box Connector you are using:

To determine the version of the Box connector you are using:

  1. Browse http://<your server:port>/box/info  - the version information is returned as shown in the image.

Monitor Box connector Activity

To monitor Box connector activity:

  1. Browse http://<your server:port>/box/trace  - trace information is returned as shown in the image.

Max file size

In versions 1.0.2+ of the Box connector there is no longer a restriction due to file size. The maximum permitted file size is set to unlimited by default.

 

 







 

 

 

 

  • No labels