/
Getting Started with the Data API - Java Client Library Tutorial

frevvo v9 is no longer supported. Please visit Live Forms Latest for our current Cloud Release. Earlier documentation is available too.

Getting Started with the Data API - Java Client Library Tutorial

So you've decided to use the Data Java client library to have a deeper integration between your application and . Our aim with this tutorial is to quickly get you started in using the Java client library by guiding you through the implementation of a simple application.

We will first help you configure your development environment and then jump straight into the Java code. This tutorial assumes that you have already installed a recent version of the Java JDK (5.0 or 6.0) and that you have already downloaded Tomcat bundle from LiveForms web site. The Tomcat bundle contains all the required Java Client jars.

On this page:

 

What are we going to build?

We are going to build a simple contacts application using  and the Data API Java Client Library.

This application will be composed on a single contact form that will be used to add new contacts, view and edit existing ones. For the sake of simplicity and the focus on the APIs, the application will be provided as an interactive command-line executable and contacts will be stored in 's internal submission repository. The command-line executable will automatically open forms using the system's browser (e.g. when editing, viewing or creating a new contact).

This tutorial will help demonstrate how to:

  • Login/logout and session management
  • Upload a sample application into
  • List the existing submissions for a sample form
  • Create a new submission
  • View a submission
  • Edit a submission
  • Query submissions & pagination
  • Delete a submission

Installing the Client Library and Dependencies

The  Java Client Library has the following dependencies:

  • com.frevvo.forms.java-4.1.1.jar
  • com.google.gdata.media-1.40.3.jar
  • com.google.gdata.core-1.40.3.jar
  • com.google.gdata.client.meta-1.40.3.jar
  • com.google.gdata.client-1.40.3.jar
  • commons-codec-1.2.jar
  • commons-httpclient-3.1.jar
  • commons-logging-1.0.4.jar
  • google-collections-1.0.jar
  • mail-1.4.1.jar
  • activation-1.1.jar
  • json-1.0.0.jar

For your convenience all these required jars can be found in the Tomcat bundle in the /frevvo/ext/client folder. Make sure you include all of them in your classpath when adding them to your application's classpath. 

The actual jar versions may be different depending on the version of being used.

Contacts application

We have created a simple Contacts command-line application and we'll use it to demonstrate some of the API features. The idea is so that the user will start the command-line Contacts application and issue interactive commands to perform the main functions mentioned earlier: create new contact, edit or view a contact, delete contact, list contacts, etc. At times, the Contacts application will need to render a form and will then launch a browser window so the user can see or fill in the Contact form.

The Contacts application described here is comprised of a single .jar file that contains all the required dependencies including the Contacts  application .zip (more details about this below).

You can download the command line binaries and the sources.

Assuming that you have an installation of  up and running (e.g. http://localhost:8082) and a user account (e.g. admin) in a given tenant (e.g. tutorial), you can run the command-line app here:

java -cp com.frevvo.forms.cli-4.1.3.jar com.frevvo.forms.cli.Tutorial -s http://localhost:8082 -t tutorial -u admin -p {adminpwd}

If you are running this for the first time you should see:

Using embedded Contacts application ...
Connecting to tenant demo at localhost:8080 ...
Contacts application doesnt exist. Uploading ... 
Application uploaded!

And then the command prompt:

http://admin@localhost:8082/tutorial>

You are now logged into tenant tutorial as user admin connected to server http://admin@localhost:8082.

Enter the list command to list all the submissions for the Contact Form (the first time you should have none):

http://admin@localhost:8080/tutorial> list
List all existing contacts...
URL ! http://localhost:8080/frevvo/web/tn/tutorial/api/submissions?filter=%24formTypeId+eq+%27_pkMVwBH8EeCl2et9BuDRPg%27
    # | ID           | CREATED           | UPDATED           | KIND           | STATE           | PDF?
 

For the curious among you, you can see the list of commands available by entering the ?list command. We will cover each one of them in the following sections.

But first, let's go over the Contact form and how to get it's API ID...

The Contact Form

Once you are logged in to , create an application named Contacts and then create a Contact form with a set of contact controls such as first name, last name, address, zip code, etc.

If you have run the command line .jar as instructed above you will already have this and won't need to create them.

In the Contact form you just created, make sure that you also check the Save PDF in the form properties pane. This will make sure that a PDF snapshot will be automatically saved when the form is submitted (this will be used to show how to get the PDF snapshot using the API).

Also make sure that your configure Searchable Fields. Searchable fields can be used for quick searches when using the API.

 Click here for information about Searchable Fields

 Searchable fields configured for a form or flow are the fields that may be used to filter submissions in the submissions view. By default, all your data is saved as an XML document. This is the most efficient way to store/access your data both in terms of speed as well as storage. However, if you prefer to view your data via the submissions user interface, you can choose which fields are available to the user as search criteria in addition to the XML data.

Considerations when deciding which types of fields to configure are listed below.

  • Searchable fields are indexed for easy search of form/flow Submissions. They can also be used when searching Tasks on a user's Task List. You will see columns for the controls in your form/flow designated as Searchable fields in the Submissions table. This is helpful when trying to locate a particular submission from a long list. Searchable Fields are downloaded into the Submissions Download to a CSV file along with the submission default columns.

    • Cloud customers can configure up to 20 Searchable Fields.

    • In-house customers can change change the default value by adding the frevvo.max.searchable.fields configuration parameter to the <frevvo-home>\tomcat\conf\Catalina\localhost\frevvo.xml file.

  • Saved fields do affect performance as they are independently stored in addition to XML data. This can significantly reduce performance, especially for large forms and require additional storage in the repository. Saved fields are not rendered in the submission table and cannot be used as search criteria for submissions. The only reason to configure Saved fields is if you want to use the Export to Excel feature which is available on the Legacy Submissions view

    The Export of submissions to Excel feature has been replaced by the Download to CSV. If you have not used the Export to Excel feature in the past, we recommend that you become familiar with the Download to CSV .
    You can still use the Export to Excel feature by accessing it from the Submissions Legacy view. However, the Legacy Submissions view and the Export to Excel may be removed in a future release.

Designers should carefully consider which fields to designate as Searchable fields. The selection of the correct fields as search criteria can be very helpful with submission and Task List searches.

The wizard displays the fields from your form/flow. Only controls that are considered form data will be listed. For Example, the link, signature, image, upload, trigger, section, PageBreak, Message, Form Viewer and video controls will not show up in the Searchable field lists as there is no value to save or query against. Also, group controls (tabs, panels, repeats) will not show up on the list of Available Fields.

  • We do not recommend using columns from Tables or Repeats as Searchable fields. The data will be hard to interpret since there can be multiple data values for the same field.

  • Do not select a Textarea field as a Searchable Field if the amount of text stored in the field is greater than 32k.
  • Searching submissions using a Repeat control from schema is not supported.

  • If the value of a field contains the < sign, the data in the Submissions Table will be incomplete. For example, if the value = a<b only the "a" will show in the Submission Table.

Move the the fields listed in the Available Fields tab that you want to use as search criteria to the Searchable Fields tab. You can change the order of the fields when you move them into the Searchable Fields area. The order of the form fields will be reflected in the Submission Table and the export to a csv file once existing submissions are resubmitted or a new submission is created.

There are two ways to select/unselect or reorder Searchable fields :

  • Drag and Drop - You can drag the fields from the Available Fields list and drop them into the Searchable Fields list if you re using Firefox, Chrome or Safari browsers. Items may be dragged between lists and within the Searchable Fields list. Items may be dropped between existing items and before the top-most item and below the bottom item. Only a single item may be dragged. Currently, the drag and drop function will not work in the Internet Explorer browsers. This issue will be addressed in a future release.

  • Center arrow buttons

    • The > right arrow moves the selected field from the Available Fields list to the bottom of the Searchable Fields list.
    • The < left arrow moves the selected field from the Saved Fields list to the bottom of the Available Fields list.
    • The >> double right arrows move all the form fields in the Available Fields list to the Searchable Fields list.
    • The << double left arrow moves all the form fields in the Saved Fields list to the Available Fields list.

Click Finish to save. Selecting the X in the upper right corner cancels any changes. Remember to save your changes when you exit out of the designer.

Controls are listed in the Available and Searchable Lists using control names. If the name changes, it will unset the Searchable field. The newly renamed control will now show on the Available list and the designer must move it to the Searchable List again. Hover the cursor over any control name for a tooltip showing the section where it is located, which is helpful if multiple controls have the same name.


Maximum Number of Searchable Fields

Cloud customers can configure up to 20 Searchable fields. In-house customers can change the maximum number of Searchable Fields with a configuration parameter. 

When an attempt is made to add more than the maximum configured number of Searchable fields, an error message ("Maximum Number of Searchable Fields Exceeded!"). displays on the lower right of the screen and will disappear after a short time. Any fields in excess of the maximum configured number will not be allowed.



Adding/Removing Searchable Fields

If you make changes to Searchable Fields in a form or flow, the changes will take affect for new submissions. If you want to update existing submissions to reflect your changes, run the Refresh Searchable Fields process.

Searchable fields can be refreshed for:

If refreshing production forms or flows, run the job during a time period when the forms or flows are not being used.

In case you need to search across all controls in the form (not only the ones specified as Searchable fields) just keep in mind that searches across non-key fields are slower for larger data sets.

Now save your form.

Get the Contact Form API ID

When using the Data API, you can find this Contact Form you just created either by getting a list of existing forms and finding the right one by name. This approach works but is a bit error prone in case another form could be created with the same name. In addition, it is also slower than getting the form directly by id.

Here is how you would find a form by name:

public class Contacts {
	...
	protected FormTypeEntry getContactForm2(String formTypeName)
			throws IOException, ServiceException {
		FormsService s = getService();
		try {
			URL formsUrl = s.getFeedURL(FormTypeFeed.class);
			FormTypeFeed forms = s.getFeed(formsUrl, FormTypeFeed.class);
			for (FormTypeEntry form : forms.getEntries()) {
				if (formTypeName.equals(form.getTitle().getPlainText()))
					return form;
			}
			return null;
		} catch (ResourceNotFoundException e) {
			return null;
		}
	}
	...
}

A better approach is to use the FormTypeEntry ID for the form in question. In integrations where forms can be dynamically created using the API, this is just a matter of saving the id found in FormTypeEntry.getId() and then using it to find the form (code shown below).

For this tutorial, though, the Contacts form is known before hand and so we can get it's id manually. This can be done in two ways:

  • Manually constructing the entry's ID, i.e. {formtypeid}!{applicationId}!{ownerId} - When designing the form in question you can get all these three ids by looking at the url in the browser's address bar. It will look like something: .../frevvo/web/tn/tutorial/user/admin/app_lJ8_ERH8EeCl2et9BuDRPg/form/_pkMVwBH8EeCl2et9BuDRPg?typeId=_pkMVwBH8EeCl2et9BuDRPg&locale= (in bold, respectively, ownerId, applicationId and formtypeId). The final ID would be _pkMVwBH8EeCl2et9BuDRPg!_lJ8_ERH8EeCl2et9BuDRPg!admin.
  • Searching for the entry id in the forms feed. Go to the browser and access the formtype feed .../frevvo/web/tn/tutorial/user/admin api/formtypes. View the page source and search for the entry named "Contact Form". Copy the value of the <id/> element. You should see something like the following feed:
<feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://localhost:8080"
      xml:lang="en">
   <title><strong>Form Types<strong></title>
   <updated>2010-12-29T16:34:41.077-05:00</updated>
   <link rel="self" type="application/atom+xml"
         href="/frevvo/web/tn/tutorial/api/formtypes"/>
   <entry xmlns:fd="http://schemas.frevvo.com/fdata/2008" xml:lang="en">
      <id>_pkMVwBH8EeCl2et9BuDRPg!_lJ8_ERH8EeCl2et9BuDRPg!admin</id>
      <title type="text">Contact Form</title>
      <summary type="text">Edit the form to change this description.</summary>
      <updated>2010-12-27T16:02:44.062</updated>
      <category scheme="http://schemas.frevvo.com/fdata/2008#kind" term="FORM"/>
      <link type="application/atom+xml"
            href="/frevvo/web/tn/tutorial/api/formtype/_pkMVwBH8EeCl2et9BuDRPg!_lJ8_ERH8EeCl2et9BuDRPg!admin"/>

Now that we know the id of our Contact Form, here is how you can find a form by id using the API:

public class Contacts {
	...
	protected FormTypeEntry getContactForm(String formTypeId)
			throws IOException, ServiceException {
		FormsService s = getService();
		try {
			URL url = s.getEntryURL(FormTypeEntry.class, formTypeId);
			return s.getEntry(url, FormTypeEntry.class);
		} catch (ResourceNotFoundException e) {
			return null;
		}
	}
	...
}

Note that we plan to make this a bit more straightforward in future releases.

Download/Upload the Contacts application

Now that we have already created the Contact Form, we will manually download it from the UI, by going to the applications page and clicking the download button, and then use the application .zip to automatically upload it to aForms install the first time our command line app is executed. This simplifies the deployment since you only need to download command-line .jar and run it, i.e. no other configuration steps, and it also shows how you can use the API to upload an application (the same applies to forms, flows, schemas and themes) programmatically.

I will not get into the details of how this .zip file will be packaged into the command-line .jar, since all the sources for this tutorial are available to be downloaded.

Authentication & Session Management

When interacting with , the Contacts application will first need to establish a session using the Data API. This is done by using the com.frevvo.forms.client.FormsService class and by providing proper credentials to authenticate.

The commandLoop() method in the Contacts class below shows how this is done in the Contacts application. Note that the FormsService instance is state-full and the same instance needs to be used throughout the session (this is specially the case when rendering form urls in the browser since an API key is automatically appended and bound to the FormsService session - as soon as you logout() the API key becomes invalid). In the case of this command-line application the session spans the life-time of the executable, but in the case of a web application the FormsService instance is usually stored in the HTTP session that the user has with the application.

 
public class Contacts {
	...
	private void commandLoop() throws IOException, ServiceException {
		// create the FormsService to hold the session with frevvo
		FormsService s = new FormsService(getProtocol(), getHost(), getPort(), null);
		try {
			// login to frevvo
			s.login(getUsername() + '@' + getTenant(), getPassword());
			// save the service to be used in subsequent interactions
			this.service = s;
			// Auto-upload the contact application, if not already there
			if (getContactForm() == null) {
				uploadContactApplication(s);
			}
			// start the interactive shell
			ShellFactory.createConsoleShell(getPrompt(), null, this).commandLoop();
		} finally {
			this.service = null;
			s.logout();
		}
	}
	...
}

When this command-line program is terminating we make sure that we properly logout from . This ensures that