home » Plugins » frevvo »

Howto: frevvo Live Forms v4 Integration with Confluence

Last Updated on Monday, 20 September 2010 22:06 Written by Pix Software Monday, 20 September 2010 21:39

Plugins - frevvo

User Rating: / 0
PoorBest 

< Prev		Next >

frevvo integration with Confluence and other tools

Email Integration

Form submissions can be emailed to a recipient when the user clicks the submit button. To configure the form to send an email upon submission, open the form designer and click the Form Action button in the toolbar. This will launch the wizard selector. Choose the Email Data to Specified Address wizard.

Each time the form is submitted, frevvo will send an email message with the form submission data, optionally an attachment snapshot of the form image, and optionally the data in XML format in an attachment named "form".

You can enter multiple comma separated addresses To, Cc, Bcc and a single Reply To address. The email address may either be a static address such as This e-mail address is being protected from spambots. You need JavaScript enabled to view it or a dynamic address by using template syntax such as ???@frevvo.com if you want the name dynamic and the domain static or ??? to make the full email address dynamic.

We suggest you uncheck "Send Data" if you don't need the xml attachment. Also leave the Send Snapshot dropdown blank if you do not need the form image attachment. Both options have small performance and memory overheads. So don't select them if you're not going to use these attachments.

Here is an example using the dynamic template ???. You must name one of your form controls emailAddress.

Step 1: First name one of your controls. You do this by entering a string into the control's Name property as shown below.

. Replace This e-mail address is being protected from spambots. You need JavaScript enabled to view it with the template: ???

Also you can specify an email address containing a template and static text such as: ???@frevvo.com. In this case the value in the form field named "customer" would replace ???. If the user enters "Joe" into the customer form field the submission would be emailed to This e-mail address is being protected from spambots. You need JavaScript enabled to view it .

The form image snapshot attachment can be Pdf, Png, Jpeg or Tiff. Live Forms In-house customers must install the Tiff generator in order to see the Tiff option.

Step 3: The email wizard lets you set your own email subject and message. The message body can contain html and css giving you the ability to generate very nicely formatted emails. Form data values can be added to the message subject and body using control template names. Two dropdowns in the wizard make it easy to add control templates. Or for customers preferring the Pdf attachment, the email message body can contain a very simple text message, which is the default.

Print View

All frevvo forms are printable. By selecting a form's printable checkbox a print icon will be displayed at the top of your form. When the form is used and the printer icon is clicked the form is rendered in a new browser tab in an HTML printable format.

PDF Integration

Forms submission can be converted to PDF documents. The PDF document can saved in frevvo's Submission Repository, sent as an attachment to a submission email, or as an attachment to a POST to a back-end system such as a document management system.

The Form and Doc action wizards for email and post submission control whether or not the form is converted to a PDF document and attached to the submission. You can control which form fields are added to the PDF via the printable property on each field in your form.

Document Service

frevvo's built-in document service can be used for processing your form data prior to submission.

The document service is accessed via the Url /service. It supports the following parameters:

• method=POST -- required and should be left POST
• target=[url] -- [url] is the path to your servlet

The target will be passed name/value pairs of all of the controls in your form with their current values. The target will also be passed the collection of xml documents comprising the form's current data. The collection will include at least one document in the namespace 'form' which contains all the data in controls added to the form from palette. The collection will also include one xml document for each data source added to the form.

Custom Print View

One example use of frevvo's document service is to provide a print preview different from frevvo's default print view.

All forms by default are printable. To make a form printable edit the form and check the printable property. Sometimes form designer required a highly customized print view. By calling frevvo's document service you can pass all the form's xml documents to another target servlet that transforms the data into exactly the format you need and then returns html to another browser window.

To do this:

• Add a message control to your form
• Add the following html to your message control

Print

Your transformation service should return html to the browser window. You can style the message control as a button by adding a border, background color and even dragging into a panel to size the "button".

Integrating with REST applications

From the point of view of the user interface, most web applications can be thought of simply as CRUD (Create, Retrieve, Update & Delete) operations on documents. In the diagram below, the form is being used to initially display a Customer and Order and then to update them. If you think in REST terms, the form is a View Resource that composes multiple Entity Resources (in this case a Customer Resource and an Order Resource), displays their current state and allows you to update them.

frevvo provides a very flexible and powerful mechanism for interacting with documents (and the web in general). You can download source code and forms for the discussion below. We strongly recommend that you download the example, study it and use it as a template for integrating with your own web applications.

Document URIs

For each Document Type that you add to your form, frevvo permits you to assign

• a document URI Template resolved either using query parameters or form fields.
• a Read method and
• a Write method.

This is best described using several examples. Consider the example above. Here are the interactions a Customer Resource supports:

Resource	Method	Description	Returns
Customer List	GET	List of customers (may be criteria based)	XML list of customers
Customer List	POST	Create new customer	URI of newly created customer
Customer	GET	Get customer data	XML representation of cutsomer
Customer	PUT	Update customer
Customer	DELETE	Remove customer

Updating a document

Consider the case where a form is used to update a particular customer. To create the form:

1. Upload your customer schema to the designer, add the customer element to the document types for the form and add the customer to the form (which automatically generates controls). See the section on Adding Controls from Schema for further details.
2. Drag/drop, change labels etc. directly in the browser
3. Specify URI template .../customers/???, choose Read Method GET and Write Method PUT
4. Specify a Form Action URI if desired (we'll get to this later).

That's it. As usual, you access the form using its URI. When the form is used (instantiated), you may specify one or more query parameters along with the URI. For this example, we might use a URI and query parameter: .../form/1234?customer=02. frevvo will resolve the URI template above to: .../customers/02, GET the customer, and display the initialized form. When the form is submitted, frevvo will automatically PUT the customer document to the same URI thereby updating the customer. The diagram below shows the interactions. Here's an example form that uses the Customer entity described above. In the example:

1. We instantiate the form with a parameter customer=02. This causes the form to resolve the URI template and GET the customer data from: http://[server]/customers/02. The resulting XML document provides the initial state of the Customer and is used to initialize the form.
2. Modify a value and click Submit. The form will automatically PUT to the correct resource and update the customer information.
3. Finally, frevvo will store the generated document set and assign it a unique URI. The document set and the documents therein can be accessed at this URI.

Creating a new document

Consider the case where a form is used to create a new customer. Follow the same steps above, except use the appropriate URI template .../customers and change the Read method to POST. That's it. As usual, you access the form using its URI. When the form is used (instantiated), frevvo will perform the POST and create the customer. It will then follow the server redirect (to the URI of the newly customer) and display the form. When the user enters customer information and submits the form, frevvo will automatically PUT the resulting XML document to the URI of the newly created customer resource thereby updating it. The diagram below shows the interactions:

Here is an example form that creates a new customer using this method.

Dynamic documents

A document URI template can also be linked to a form control. To do this, use the Control Name. Consider the Updating a document example above and the sample form therein.

The form has a Customer document and we have specified URI template .../customers/??? and Read method GET. In this form, there is a control which has Type ID 'customer' as shown in the figure below.

If you enter a value in this control, frevvo will automatically resolve the URI template using the new value and attempt to GET a new document. If it succeeds, the form will be initialized with the new document and all relevant control values will automatically update. In the example above, try changing the value to 03 or 04. Notice how the customer information fields change to reflect the new document that is being edited by the form.

If you enter an ID that does not exist, the GET will fail (return an empty document or a 404 HTTP status code). In this case, frevvo will automatically revert back to the default document with default values as specified by the designer.

In either case, if you modify/fill in fields and submit the form, it will PUT (since we chose PUT as the Write Method, the form will send an HTTP PUT) the resulting XML document to the resolved URI.

For example, if you enter ID 03, frevvo will GET .../customers/03, display the form with fields initialized from the returned XML document and PUT the modified XML document to the same URI when the form is submitted. This PUT will update the customer with ID 03.

If you enter ID 99 (which does not exist), frevvo will GET .../customers/99, which returns an empty document. The form will be displayed with default values (as entered originally by the designer). When submitted, the resulting XML document will be PUT to .../customers/99. This PUT will create a new customer with ID 99 (the behaviour depends on the implementation on the server - in our example, the PUT creates the customer).

Example

This example is a good way to understand frevvo's handling of document URIs and the powerful capabilities of composing multiple document resources into view resources. You can download the entire example including source code and forms by clicking here.

This example follows the principles of REST and uses the Restlet framework but you can use any framework or server-side model that you like. As mentioned earlier, frevvo forms can be thought of as View Resources that compose one or more Entity Resources (documents). In this example we have entities Customer and List of Customers. Reproduced here are the methods that they support.

Resource	Method	Description	Returns
Customer List	GET	List of customers (may be criteria based)	XML or JSON list of customers
Customer List	POST	Create new customer	URI of newly created customer
Customer	GET	Get customer data	XML representation of cutsomer
Customer	PUT	Update customer
Customer	DELETE	Remove customer

This is implemented in the two classes: com.frevvo.restlet.customer.CustomersResource and com.frevvo.restlet.customer.CustomerResource. These simply provide implementations of the above methods returning the desired representation of the resource for a GET, creating a new customer for a POST and updating an existing customer for a PUT. In general, the representation that is returned depends on content negotiation via the Accept headers.

Customer Information

This form is described in the Updating a document section above. It GETs the XML representation for a specific customer using the third method in the table above, initializes the form with that information and displays it to the user. When submitted, the updated customer information is automaticlly PUT to the same [resolved] URI using the fourth method in the table above.

Create Customer

This form is described in the Creating a new document section above. When instantiated, it does a POST to the Read URI using the second method in the table above. This causes the server to create a new customer and return the URI of that customer. frevvo will automatically follow this URI, GET the representation of the customer and display the form (presumably with empty values). When the user enters all required fields and submits the form, frevvo will automatically PUT the resulting XML document to the URI for the newly created customer thereby updating the customer.

In this manner, the combination of URI templates, read/write methods and form parameters provides a very powerful and flexible way to interact with the web.

You can find further discussion of this example on the frevvo blog. The relevant articles are: Part 1 and Part 2. Other articles that may be of interest are How do I use my brand new WOA? and Ajax+REST: the next killer app?.

PaperVision® / ImageSilo® Connector

frevvo Live Forms supports direct connectivity with Digitech Systems' PaperVision® and ImageSilo® document management products. This Connector allows you to save submissions to the PaperVision® and ImageSilo® document management repository as PDF, TIFF, .JPG and .GIF format.

Installation Instructions

If you are using Live Forms Online there is nothing to install. If you are using Live Forms In-house:

1. copy <frevvo install dir>\frevvo\ext\connectors\pve.war to <frevvo install dir>\frevvo\tomcat\webapps
2. If your are sending your form submissions to ImageSilo https://login.imagesilo.com then the connector requires no further configuration
3. If you are submitting to a local installation of PaperVision then edit the connector's web.xml to configure the local URL path. Replace login.imagesilo.com with the host:port of your PaperVison installation.

Edit <frevvo installdir>/frevvo/webapps/pve/WEB-INF/web.xml

        frevvo.pve.login.url
	https://login.imagesilo.com/HTTPInterface.asp

In your browser, go to: http://[:port]/pve/test. You should see a message "Your PVE Connector request was successfully handled." This means the connector is properly installed.

Live Forms V4

A Doc Action Wizard steps you thru the process of connecting your form to PaperVision.

1. Enter your PaperVision/ImageSilo entity, username and password and click the login button
2. The wizard connects to your account and now displays a dropdown with all your PaperVision/ImageSilo projects
3. Select the project where you want to save the form submission
4. Select the image type: PDF, TIFF, JPG, or PNG.
5. Select if you want to store the xml data document in addition to the form image document
6. Click Next

For Live Forms In-house users, if the TIFF option doesn't appear you have not yet installed the TIFF software into your frevvo installation.

1. The wizard connects to your selected project and retrieves the list of key index fields from PaperVision/ImageSilo
2. Map each PaperVision/ImageSilo key index field to a field on your frevvo form. The dropdown contains a list of all the form fields listed by field name (not field label).
3. Click Finish

Your form is now connected to PaperVision/ImageSilo. When you use your form and click the submit button the form image, any attachments and the xml document (if you selected that in the doc action wizard) will be saved into your PaperVision/ImageSilo project.

Google Connector

frevvo Live Forms supports direct connectivity with Google Documents and Google Spreadsheets. The Google Connector allows you to save submissions to Google Spreadsheets and format emails or confirmation receipts using an online Google Document.

Installation Instructions

If you are using Live Forms Online there is nothing to install. If you are using Live Forms In-house and have downloaded the Google Connector:

1. rename the download file named connector-google-apps.zip to google.war
2. copy google.war to c:\frevvo\tomcat\webapps

Tomcat will automatically expand the war file and start the connector running. If you are not using the frevvo tomcat-bundle or have not installed the bundle into c:\frevvo make the necessary path adjustments to step 2 above.

Google Documents

This feature is currently in alpha release. The syntax may change.

The Google Documents Connector can be used to format emailed form submissions and to echo a formated document back to the page that submitted the form. Here is a sample email formated using the Google Document template shown below.

To use the Google Connector Edit your form and use the Form Action Wizard to echo a formatted document back to the page and/or use Doc Action Wizard to format an email message.

 

Google Document Template Syntax

This feature is currently in alpha release. The syntax may change.

The Google Document Connector uses a template syntax to insert values from a submitted form into the document. The syntax is ${form.[Name]}. Where [Name] is the name you gave to the particular form field in the frevvo Form Designer. Read more about naming form fields.

Here is a Google document using the template syntax:

Repeats

Repeat controls have a special syntax. Assume that your form contains a repeating section named Expense. First you must add a Repeat As tag to the document. ${repeat form.[Name] as [alias]}. For example: ${repeat form.Expense as exp}. Then use the alias to reference the controls inside the repeat. The Connector's template processor will add a row to the table for each repeating item in the form submission.

Sections

Form controls nested inside sections must be referenced using a nesting notation. If two text controls named Firstname and LastName are nested inside of a section named PersonalInfo then the templates in your google document must be written as:

${form.PersonalInfo.FirstName} ${form.PersonalInfo.LastName}

If you add another section to your form and name it MedicalHistory and drag/drop PersonalInfo into that section, then the templates must be updated and written as:

${form.MedicalHistory.PersonalInfo.FirstName} ${form.MedicalHistory.PersonalInfo.LastName}

Limitations

The connector currently supports only form controls from palette. It does not yet support form controls from XSD data sources.

Templates are case sensitive. If your form field is named Hours then your template must be written as ${form.Hours}. Using lower case as in ${form.hours} will result in no field data in the document.

NOTE:

1. Do not try to change the font size, color, etc of the template strings in your document. See known issues.

Google Spreadsheets

Writing to a Google Spreadsheet

Forms submissions can be saved directly into your Google Spreadsheets. Edit your form and use the Doc Action Wizard to configure your form to save your submissions into a Google spreadsheet.

Each time someone uses and submits your form, a new row is added to your Google spreadsheet. See the Google spreadsheet tutorial for step by step instructions.

NOTE: Google will not automatically add a row to your spreadsheet. Make sure your spreadsheet has plenty of empty rows at the bottom for all your expected submissions. See known issues.

Multiple Documents

If your form contains multiple documents because one or more controls are from the palette while other controls are from one or more XSD data sources, you can write each document to a different Google Spreadsheet. To do this use the Google Connector Url Manual Doc URI wizard to configure each Uri to a different spreadsheet or workbook within the spreadsheet.

Reading from a Google Spreadsheet

frevvo forms can be initialized with data from a Google Spreadsheet. This is done by accessing the Google Spreadsheet via a [Rule].

Here is an form that contains controls for each column in a Google Spreadsheet, plus two extra fields. A dropdown for selecting which row to retrieve from the speadsheet and Rowid.

The rule does an http.get to the Google Connector and passes it two Url Parameters:

• cn=lastname
• cv=LN.value

cn is the column name that will be searched to find a matching row to return to your form and cv is the value that the match is looking for.
cv is the column value being searched form. In this example, LN.value is the option the user selects from the dropdown labeled "To view an existing friend choose their name here:" which is named LN in this form.

The http.get returns all the values from the matched row in your Google SS to a varable named "x". Set each field in the form to the values from the spreadsheet row: ex: firstname.value = x.firstname. The variable x contains a member for each column name for example "firstname", "lastname", etc.. plus one extra member called "rowid".

if (LN.value.length > 0) {

var baseUrl = 'http://www.frevvo.com/google/spreadsheets/u/
 This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 /p/joe01'

  eval ('x=' + http.get (baseUrl + '/key/pDQtQNgwug49pGw79kcCudw/w/Sheet1
                                            ?cn=lastname&cv=' + LN.value));

  if (x.firstname) {
    firstname.value = x.firstname;
    lastname.value = x.lastname;
    birthday.value = x.birthday;
    gift.value = x.gift;
    RI.value = x.rowid;
  }
}

NOTES:

1. Currently the dropdown cannot be dynamically populated with values from the Google Spreadsheet. The options must be set statically in your form's dropdown control.

Google Connector Known Issues

The frevvo Google Connector is an alpha release. These are the known issues we are working to solve. Please report any issues or feedback to us here.

Ticket	Description	Work-around
3931	Google Connector fails to replace templates with form field values	Text formatting of the templates can possibly corrupt the underlying html document structure. If your document fails to produce results for certain templates, delete the template and re-add it to your document. Copy and pasting template tags can have the same effect. Both problems are due to the fact that the Google Docs is inserting html font tags into the middle of your templates. You can also fix this by cleaning up the document in the html view. But better to avoid the problem initially.
7710	Google Connector fails to add row to google spreadsheet	The Connector will fail to add a submission to your google spreadsheet if the spreadsheet has no empty rows at the bottom. Make sure your spreadsheet has plenty of empty rows at the bottom for all expected form submissions.

Integrating with your database

frevvo provides a simple connector that integrates forms with your database. The connector is freely available for download and is licensed under an open source model. The documentation can be found at Connecting with your database.

Integrating with HTTP Servers

By setting your Form Action to Post Document, when the user submits the form the browser will POST the user’s data to the URL you specify in the form’s URL property field. The HTTP server (for example a servlet) that you specify via the URL, can access the user's data in two different ways. One is by using request.getParameter.

The HTTP parameters are named by your form control's names. See the Form Designer below has a control labeled Quantity and named 'Q' and a control label Email Address named EMmail2787 (not visible in the image below). Also imagine the form contains a repeat control containing a control named B.

• request.getParameter(Q) will return the value 20
• request.getParameter(EMail2787) will return the value This e-mail address is being protected from spambots. You need JavaScript enabled to view it
• request.getParameter(B) will return an array of two strings [one,two]

Integrating with web services

Initializing forms with XML documents

Forms can be initialized by an XML document. This is most commonly done when the form is created from an XSD data source but can also be used with forms create from frevvo's palette controls. The most common method is to connect the XML document to the form via the form's doc action manually set document URIs wizard.

XML document from Doc URI

The form designer ensure the XML document used to initialize the form conforms is valid for the XSD schema used to create the form. If the XML document is invalid your form will fail to initialize and will display the message "There were problems initializing form".

One example of an invalid XML document is when the XSD contains a repeating element. If minOccurs=3 and the XML document contains only 2 elements then the document is invalid and your form will display the standard error message.

XML document from Post payload

In addition chaining multipe forms together via the Form Action Post with common data sources from XSD as described above, it is also possible to write a servlet or other web code that does a Post request with a form Url to the frevvo Form Server. This request can also be coded to contain an XML document. If the XML document conforms to and is in the same namespace as one of the form's documents (either from-scratch palette controls or from XSD schema datasource), then the Form Server will use that XML document to initialize the form's fields.

Handling Attachments

tbd

Client Side Integration

It is possible to associate a javascript handler to a form's submit button, trigger or any other form event such as the value change in a form field like a radio button selection.