This documentation is for Live Forms 7.3 Not for you? Earlier documentation is available too.
Getting Started with the Data API - Java Client Library Tutorial
What are we going to build?
We are going to build a simple contacts application using
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
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 Sey Fields. Searchable fields can be used for quick searches when using the API.
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;
}
}
...
}