...
...
| Section | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
We are going to build a simple contacts project using and frevvo and the Data API Java Client Library.
This project 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 frevvo'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).
...
- Login/logout and session management
- Upload a sample project into into frevvo
- 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 frevvo Java Client Library has the following dependencies:
...
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.
| Note |
|---|
The actual jar versions may be different depending on the version of being frevvo being used. |
Contacts application
...
The Contacts application described here is comprised of a single .jar file that contains all the required dependencies including the Contacts project frevvo project .zip (more details about this below).
...
Assuming that you have an installation of up of frevvo up and running (e.g. http://localhost:8082) and a user account (e.g. designer) in a given tenant (e.g. tutorial), you can run the command-line app here, replacing 'forms-cli.jar' with the current jar filename.
...
Once you are logged in to frevvo, create a project named Contacts and then create a Contact form with a set of contact controls such as first name, last name, address, zip code, etc.
...
In the Contact form you just created, make sure that you also check the Save PDF in the Settings tab. 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.
...
Authentication & Session Management
When interacting with frevvo, 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.
...
When this command-line program is terminating we make sure that we properly logout log out from frevvo. This ensures that will frevvo will release any unneeded resources and the user count will be decremented (licensing).
LoginAs
supports frevvo supports an additional way of logging into using frevvo using the Data API: the loginAs() method. This new method allows you to login to as frevvo as any of the existing tenant users provided you can pass in the tenant's admin user and password. This is quite convenient when you want login to using frevvo using the same user that is logged into your project without having to know their password.
...
When your tenant was configured with the DelegatingSecurityManager, you can use the overloaded loginAs() method to automatically create virtual users in frevvo. For instance:
| Code Block |
|---|
...
String tenantAdmin = getUsername() + '@' + getTenant();
String tenantAdminPwd = getPassword();
String username = getAsUsername();
FormsService s = new FormsService(getProtocol(), getHost(), getPort(), null);
s.loginAs(username, tenantAdmin, tenantAdminPwd, true, null, null, null, null, null);
... |
This will automatically create a new, non-designer user (i.e. will be able to participate in workflows but not create forms/workflows), if it doesnt doesn't yet exist. If you want to frevvo to auto create a new virtual user that is also a designer you need to pass in the frevvo.Designer role when calling loginAs(). For instance:
...
As described earlier, we have downloaded the frevvo Contacts application .zip file and embedded it in the command-line .jar. This .zip file is available from the JVM Classpath and will be automatically uploaded if it cannot be found in the frevvo server, i.e. usually the first time you connect to a frevvo/tenant install.
The following code snippet shows how we do this. We first try to find the Contact Form form by ID (as we described earlier) and if we cant find it, we will upload the project.zip file.
...
Now that we are logged in to and frevvo and have the Contact project uploaded, let's list the current contacts we have in the submission's repository. This is done by entering the list command:
...
Note also the null parameter in getFormTypePopupLink(null) call: it is here that we can customize the form link by passing in a map of name and value contants contents for things like:
- Rendering the form in readonly or print view
- Overriding the form action associate with the form (e.g. to redirect the page to one of your app's page when the form is submitted
- Initializing specific controls in the form using _data
- ...
...
Note that editing a contact here is nothing more than rendering a form and initializing it with the XML document(s) stored in frevvo's submission repository. Since this repository is embedded in frevvo, we have automated some of the work of instantiating a form and initializing it from an XML document(s). However, what if you are integrating with frevvo with your own application and have your own database of contacts? Not a problem. You can use the API to instantiate the form passing in a list of XML documents.
...
The delete command implementation is show shown next and is done by find finding the correct SubmissionEntry based on the provided index and then calling .delete():
...
By default the list command we have been using so far is a simple query that returns the first page of all Contact Form submissions. There are situations where you may want to customize this query to return a subset of the results. Although we dont don't provide an extensive query API there are a few things you can do.
...
One thing you can do is order the results by a certain criteria:
- $author - The id of the user that submitted the form/workflow
- $name - The name of the form/workflow
- $updated - the last time the submission was updated
- $revision - This is zero the first time you submit and is incremented everytime every time you edit the submission and submit it again
- $formTypeId - The form/workflow that generated this submissions submission (not so useful here)
- $key{N}Value - The key value for key 1, 2, 3, 4 or 5 (remember that you can select controls from your forms to be keys in your submission).
- {control.name} - If you configured your form to save the control values, you can then use the control value to order the submissions (use key fields in most cases and Export Fields as a last resort)
...
We have set the updated-min query parameter to 2010-12-30T19:16:24.000, which is 1 second after the contact #1 was submitted. As you can see, listing the submissions now show only the contact #2 which was submitted after that.
You can also set the updated-max query parameter to something like 2010-12-30T19:49:03.000, which is 1 second before the contact #2 was submitted:
...
- $author - The id of the user that submitted the form/workflow
- $name - The name of the form/workflow
- $updated - the last time the submission was updated
- $revision - This is zero the first time you submit and is incremented everytime every time you edit the submission and submit it again
- $formTypeId - The form/workflow that generated this submissions submission (not so useful)
- $key{N} - The key value for key 1, 2, 3, 4 or 5 (remember that you can select controls from your forms to be keys in your submission).
- {control.name} - If you configured your form to save the control values, you can then use the control value to order the submissions (use key fields in most cases and Export Fields as a last resort)
...