Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...


Section


Column

The Data frevvo Data API provides a simple protocol for viewing and managing resources 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.

Note

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



Column
width240px

On this page:

Table of Contents
maxLevel2


...

There are various different types of  resources 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  UI, for instance frevvo UI such as users, projects, forms, styles, schemas, etc. So before 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.

...

  • 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 currently logged-in user.
  • SchemaFeed - The collection used to manage the XSDs uploaded to an a 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.

...

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 endpoints and can process XML documents, we provide a Java Client and a .Net Client that can be used to easily connect to  from 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.

...

Info

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  locallyfrevvo 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 IDEs let you view Javadocs.

Java Client API FAQ

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

Installing the Client Library and Dependencies

The  Java 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  Tomcat 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.

...

Note

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

Authentication & Session Management

When interacting with 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 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 especially 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 lifetime 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.

...

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  before frevvo before logging out. Logging out ensures that  will frevvo will release any unneeded resources and the user count will be decremented, as the number of users is affected by your  licensefrevvo license.

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 log in 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 log in to  using frevvo using the same user that is logged into your application without having to know their password.

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

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);
    ...

...

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

...

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

The download is a zipfile containing the following files:

...

For a list of Frequently Asked question about common tasks using the API with  serverfrevvo server, please see the API .Net Client FAQ topic.

...

The client libraries are built on top of the browser API. However since these URLs can be used directly from your browser, it is a great way to experiment with the  API frevvo API before you start writing code.

This section describes the basic protocol used to interact with  Data frevvo Data APIs including examples of what Atom requests may look like, what kind of responses to expect, and so on. It is intended for anyone wanting an understanding of the general idea of the format and protocol used by the  Data frevvo Data API and it assumes that you understand the basics of XML, namespaces, Atom feeds, and the main HTTP requests GET, POST, PUT and DELETE, as well as the RESTful concept of a resource. Using the API at this level your client application can interact with the  Server frevvo Server using any programming language that lets you issue HTTP requests and consume XML-based responses.

You can use the Resource URIs listed Browser API Reference Guide in the browser address bar when you're logged into frevvo. The URIs return data from the  server frevvo server as either web pages or XML files. To use the URIs, you edit the URL in the address bar when you're logged into a  tenant frevvo tenant to include the URI of the resource feed you want to use. For example:

...

This example shows how to use the formtypes feed to have the  server frevvo server return a list of all the forms belonging to the user who's currently logged in.

  1. After logging in, edit the  URL frevvo URL in the browser address bar to insert api/formtypes immediately after the tenant name - which in this example is monahan.com.
  2. So in this example, we change the URL from: http://localhost:8082/frevvo/web/tn/monahan.com user/david/app
  3. To:  http://localhost:8082/frevvo/web/tn/monahan.com/api/formtypes, and press Enter.

...

  1. After logging in, edit the  URL frevvo URL in the browser address bar to insert api/controltypes immediately after the tenant name - which in this example is monahan.com.
  2. In this example, we change the URL from: http://localhost:8082/frevvo/web/tn/monahan.com/user/david/app
  3. to: http://localhost:8082/frevvo/web/tn/monahan.com/api/controltypes, and press Enter.

The browser returns the page below. Scroll though through the page to see all the controls in all the user's forms.

...

This example shows how to use the controltypes?ownerId={formTypeId} feed to get a list of the control types in a specific form - in this case, the Address Book form in the example above.

  1. After logging in, edit the  URL frevvo URL in the browser address bar to insert api/controltypes?ownerId={formTypeId} immediately after the tenant name - which in this example is monahan.com.
  2. So in this example, we change the URL from: http://localhost:8082/frevvo/web/tn/monahan.com/user/david/app
  3. to: http://localhost:8082/frevvo/web/tn/monahan.com/api/controltypes?ownerId=_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david, and press Enter.
Note

Note that the value of the ownerId= parameter is the form type definition for the Address Book form is shown in the XML example above, including the ID (david) of the user who created the form.

...

Logging In and Out of the Forms Server

When interacting with with frevvo, an application first needs to establish a session using the Data API. See the C# code snipped below for an example.

...

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  before with frevvo before logging out. Logging out ensures that  will that frevvo will release any unneeded resources and the user count will be decremented, as the number of users is affected by your  licenseyour frevvo license.

Calling the API from a JSP Page

...

The reset task API makes it possible to restart a completed submitted workflow. For example, imagine a sales person salesperson has reviewed a product order form on their task list and signed it, and submitted it. This is the final workflow step and the form is submitted to a document management system (ECM). All of the form data and the PDF order form image are stored in the ECM. While the order is processed someone notices that a product is out of stock and wants to return the order form back to the sales person's form workflow task list. The reset task API feature makes this possible.

...

  • frevvo.form.id - The GUID sent in the workflow submission POST to your back-end system (ECM in the example above).
  • frevvo.reset.activity.name - The actually actual name of the activity you want to reset the task to. See workflow activity properties in the Workflow Designer. Note that is it is simpler to have no spaces in the activity name.

...

Code Block
http://localhost:8082/demo/api/resetTask.jsp?frevvo.form.id=_2U71ABwbEeC6avHeCMEeBw&frevvo.reset.activity.name=SalesReview

Here is the sample code for resetTask.jsp. You should modify this as needed.

...