The frevvo Data API provides a simple protocol for viewing and managing frevvo resources such as forms, projects, styles, schemas, etc. The API extends the Google Data API framework, is HTTP and XML-based, and uses the Atom Syndication Format with a few extensions following Atom's standard extension model. Java and .Net are the language-specific wrappers around the API.

Atom also provides the Atom Publishing Protocol (APP), an HTTP-based application protocol for publishing and editing resources on the web. The APP specification is an emerging standard being developed by the IETF that allows you to send an HTTP GET request to ask for a particular resource such as a form or schema; a representation of that resource is returned in the Atom Syndication format. You can also create, edit and delete resources using standard HTTP POST, PUT and DELETE methods, respectively. Atom provides a protocol in line with the REST approach to web service interfaces.

In v9.1 and later frevvo's "Applications" are known as "Projects." The API objects and methods still use the word Application.

On this page:

Data API Feeds

There are various different types of frevvo resources that can be viewed and manipulated by the Data API. Most of these resources are things that a designer sees when creating new forms and navigating the project using the frevvo UI, for instance users, projects, forms, styles, schemas, etc. So before delving into the API specifics it is a good idea to understand these different types of resources and how they relate to each other.

Here is a diagram showing all the available Data API feeds:

Here is a quick run-down of each one of them:

UserFeed - There is not much that can be done with this collection at this point except for being an optional entry point for projects, tasks and themes.
FormTypeTemplateFeed - The collection used to list and manage published forms or workflows.
SubmissionFeed - The collection used to query form or workflow submissions and get associated XML documents, PDF snapshots, attachments, etc.
StyleFeed - The collection used to list and manage styles in frevvo.
ProjectFeed - The collection used to list and manage projects in frevvo.
TaskFeed - The collection used to manage the tasks for the current logged-in user.
SchemaFeed - The collection used to manage the XSDs uploaded to an project.
DocumentType - The collection used to manage top-level XSD elements in frevvo, called DocumentTypes. An XSD has a feed containing all the DocumentTypes (top level elements) that can be added to forms and workflows and a form or workflow has a feed containing all the DocumentTypes added (in the designer's Data Sources pane).
FormTypeFeed - The collection used to manage forms AND workflows. This is the core collection in the API that is used to use, design, manage, instantiate, etc. forms and workflows.
ControlTypeFeed - The collection used to list the controls, and their metadata, contained in a form or workflow.

It is important to understand this diagram since the source code for the client application maps almost one-to-one to this structure.

Tutorials

You can try any one of several Data API Tutorials to get started.

Client Libraries

Although our APIs are based on the Atom Publishing Protocol and the Atom Syndication Protocol and can be accessed on any language/platform that can interact with HTTP end points and can process XML documents, we provide a Java Client and a .Net Client that can be used to easily connect to frevvo from Java and Windows or Mono, respectively.

You will need to install a client library in order to use the API. See Installing the Client Library and Dependencies below.

Java Client API

The Design-time Integration tutorial is a very good place to get a quick overview of how to use the Java API.

Javadocs

If you installed frevvo locally, the installation includes the Javadocs .jar file. The com.frevvo.forms javafiles are located in the <installdrive>:\frevvo\ext\client directory. Many IDE's let you view Javadocs.

Java Client API FAQ

For a list of Frequently Asked Questions about common tasks using the API with a frevvo server, please see FAQ - Java Client API.

Installing the Client Library and Dependencies

The frevvo Java Client Library has the following dependencies:

com.frevvo.forms.java-4.1.4.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 frevvo 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 frevvo being used.

Authentication & Session Management

When interacting with frevvo, an application first needs 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 example below is taken from the tutorial Getting Started with the Java Data Client Library.

The commandLoop() method in the Contacts''' class below shows how this is done in the Contacts project. 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();
         }
    }
    ...
}

Since there is some overhead associated with logging in and out, you need to keep the FormsService instance around for as long as you need to interact with frevvo before logging out. Logging out ensures that frevvo will release any unneeded resources and the user count will be decremented, as the number of users is affected by your frevvo license.

When using LDAP with SSO, SAML, or Azure security managers, logging in via API will only work for the built-in admin user.

LoginAs

frevvo supports an additional way of logging into frevvo using the Data API: the loginAs() method. This new method allows you to login to 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 frevvo using the same user that is logged into your application without having to know their password.

The following snippet shows how to login as a tenant user:

    ...
    String tenantAdmin = getUsername() + '@' + getTenant();
    String tenantAdminPwd = getPassword();
    String username = getAsUsername();
    FormsService s = new FormsService(getProtocol(), getHost(), getPort(), null);
    s.loginAs(username, tenantAdmin, tenantAdminPwd);
    ...

The loginAs(String, String, String) usage above assumes that you are logging in as a user that was previously created in the specific tenant.

When your tenant was configured with the DelegatingSecurityManager, you can use the overloaded loginAs() method to automatically create virtual users in frevvo. For instance:

    ...
    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 doesn't yet exist. If you want 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:

    ...
    String tenantAdmin = getUsername() + '@' + getTenant();
    String tenantAdminPwd = getPassword();
    String username = getAsUsername();
    List<String> roles = new ArrayList<String>();
    roles.add("frevvo.Designer");
    FormsService s = new FormsService(getProtocol(), getHost(), getPort(), null);
    s.loginAs(username, tenantAdmin, tenantAdminPwd, true, roles, null, null,null,null);
    ...

.Net Client API

The frevvo .NET API is a .NET language-specific wrapper around frevvo's core GData API framework. Refer to the browser URL APIs and java APIs discussed in this chapter for a list and explanation of the methods exposed in the frevvo data API framework.

Visit the Data API Client Libraries Releases compatibility matrix to download the proper library version for your installed frevvo server.

The download is a zipfile containing the following files: