This tutorial will walk you through a few API scenarios focusing on the design-time integration such as creating new forms, listing and managing projects, launching the designer for a workflow, downloading schemas, projects, forms and workflows, download the XSD for a form/workflow, uploading custom XSDs, using forms and workflows.

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:

What are we going to build?

Nothing. We have pre-created a simple application that shows the different usages of the API using an interactive command-line approach. Think of this app as the command-line version of the web-based frevvo UI but stripped of all the irrelevant details, libraries, etc., so you can inspect the different API usages as simply as possible using live code with sources included.

Although this approach makes it a bit harder to piece together a given API usage since it will be comprised of a set of different paths through the sources, we believe it will provide a better learning tool since you will be able to inspect the sources, which will be running sources, or even debug the app if needed, after all this is an API we are talking about. We have also chosen an interactive command-line application format so that we would be able to reduce the code footprint to a bare minimum increasing the clarity needed to understand it. Besides, this tutorial should be the guide through the different API usages that may not be obvious by simply inspecting the source code.

Downloading the command-line client

The client is packaged as an executable Java JAR that includes all of the required dependencies and you can download the binaries from here and the sources from here.

Running the command-line client

Assuming that you have a Java Runtime Environment (JRE (update 21+) or JDK versions 1.6, 1.7), you can run the client as follows, replacing 'com.frevvo.forms.cli.jar' with the current jar filename, e.g. 'forms-cli-10.1.2.jar'.

java -jar com.frevvo.forms.cli.jar

This should show you usage information:

usage: com.frevvo.forms.cli.Main
-s,--server <arg> serverl url (e.g. http://localhost:8082)
-t,--tenant <arg> tenant (optional, e.g. doe.com)

If you want to connect to a frevvo install running on localhost you can do as follows, replacing 'forms-cli.jar' with the current jar filename.

java -jar forms-cli.jar com.frevvo.forms.cli.Main -s http://localhost:8082

And you should see the command line prompt:

localhost:8082>

This means that you are up and running, but not yet connected. First, you need to log in to a frevvo account. Be sure to create at least one tenant and one user for the tenant before you try to log in. See Connect to a Server and Log In below for instructions.

How are the sources organized?

The key concept you need to know to understand the sources is the Shell. Each feed and entry described in the previous diagram will have a corresponding Shell class (with the exception of FormTypeTemplateFeed/Entry) that is used to plug into the command line interface the different commands available. The commands available in the app at any given point in time are defined based on what Shell is active. When you issue commands in the prompt, you may remain in the same Shell or navigate the Shell tree and change the active Shell. Changing the active Shell changes the available commands at the prompt.

Some commands are not specific to a given shell but are common across all shells. They are:

?list - This command will print out a list of all the currently available commands with a brief description and the number of arguments it expects if it expects any.
exit - This is how exit the current shell and 'back up' and return to the previous one (some commands you execute may activate a new shell). Exiting from the last shell will exit the app.

Here are the shells you can find in this app (all located in the '''com.frevvo.forms.cli.shell.*''' package):

com.frevvo.forms.cli.shell.ApplicationEntryShell
com.frevvo.forms.cli.shell.ApplicationFeedShell
com.frevvo.forms.cli.shell.ControlTypeEntryShell
com.frevvo.forms.cli.shell.ControlTypeFeedShell
com.frevvo.forms.cli.shell.DocumentTypeFeedShell
com.frevvo.forms.cli.shell.DocumentTypeEntryShell
com.frevvo.forms.cli.shell.FormTypeEntryShell
com.frevvo.forms.cli.shell.FormTypeFeedShell
com.frevvo.forms.cli.shell.SchemaEntryShell
com.frevvo.forms.cli.shell.SchemaFeedShell
com.frevvo.forms.cli.shell.SubmissionEntryShell
com.frevvo.forms.cli.shell.SubmissionFeedShell
com.frevvo.forms.cli.shell.TaskEntryShell
com.frevvo.forms.cli.shell.TaskFeedShell
com.frevvo.forms.cli.shell.ThemeEntryShell
com.frevvo.forms.cli.shell.ThemeFeedShell
com.frevvo.forms.cli.shell.UserEntryShell
com.frevvo.forms.cli.shell.UserFeedShell
com.frevvo.forms.cli.shell.FormInstanceShell

The FormInstanceShell has no corresponding feed/entry in the Data API. It is used to provide a context for commands that interact with a form instance (e.g. submitting a form, resetting a form, etc)

If you inspect the sources for each of these classes you will notice some methods are annotated with a special Command metadata: this is where we specify what is the command's name in the command prompt and its description (used by ?print described above).

Now let's move on to some usage scenarios.

Usage Scenarios

The following topics show how to log in to the frevvo server and use the command line API to interact with the server, projects, forms and workflows.

Connect to a Server and Log In

The example below shows how to log in to a local frevvo server. In this example, the login user name is david, the name of the tenant is monahan.com, and the user password is david (e.g., login david@monahan.com david).

To login, you must first create a tenant on the server (other than the default d tenant). You should also create a user with the role frevvo.Designer who can create projects.

Directory of D:\frevvo v4.1.4

08/05/2011 08:59a <DIR> .
08/05/2011 08:59a <DIR> ..
08/05/2011 08:59a 3,044,609 com.frevvo.forms.cli.jar
07/12/2011 09:20a <DIR> frevvo
        1 File(s) 3,044,609 bytes
        3 Dir(s) 7,803,990,016 bytes free

D:\frevvo v4.1.4>java -jar com.frevvo.forms.cli.jar

usage: com.frevvo.forms.cli.Main
-s,--server <arg> serverl url (e.g. http://localhost:8082)
-t,--tenant tenant (optional, e.g. doe.com)

D:\frevvo v4.1.4>java -jar com.frevvo.forms.cli.jar -s http://localhost:8082

localhost:8082> ?list
Name     Abbr     ArgNum     Descr
login     l         1        login(username:String) : String
login     l         2        login(username:String, password:String) : String
login-as  la        2        loginAs(username:String, tenantAdmin:String) : String
login-as  la        3        loginAs(username:String, tenantAdmin:String, tenantAdminPassword:String) : String
print     p         0         print() : String
localhost:8082> login david@monahan.com david
----------------------------------------------------------------------------------------
        ID  | david
        URL | http://localhost:8082/frevvo/web/tn/monahan.com/api/user/david
    UPDATED | 2011-08-05T09:52:45.510-04:00
       NAME | david
DESCRIPTION | null
----------------------------------------------------------------------------------------

After you've logged in, use ?list to display commands you can use in the server. For example, you can use apps to work with the projects on the server.

localhost:8082/david@monahan.com> ?list

Name     Abbr     ArgNum     Descr
apps                0        SELECT apps for this user (e.g. 'apps')
subs                0        SELECT subs for this user (e.g. 'subs') you
tasks               0        SELECT tasks for this user (e.g. 'tasks')
themes              0        SELECT themes for this user (e.g. 'themes')
link      l         1        OPEN a link in the browser (e.g. 'link {link#}')
descr     d         1        UPDATE this entry's description (e.g. 'descr {newDescription}')
links     l         0        SHOW all entry links (e.g. 'links')
links     li        1        SHOW feed links for given rel attr (e.g. 'links {relAttr}')
name      n         1        UPDATE this entry's name (e.g. 'name {newName}')
print     p         0        PRINT this entry (e.g. 'print')
delete    d         0        DELETE this entry (e.g. 'delete')
refresh   r         0        REFRESH this entry (e.g. 'refresh')

The frevvo UI displays the projects belonging to the user david@monahan.com on the projects home page.

The apps command displays a list of the projects in the tenant on the server — DTM July 2011'and DTM August 2011 in this example.

localhost:8082/david@monahan.com> apps
----------------------------------------------------------------------------------------
URL ! http://localhost:8082/frevvo/web/tn/monahan.com/api/apps
    # | NAME                                   | DESCRIPTION
1 | DTM July 2011                              | Group of test forms created by DTM.
2 | DTM August 2011                            | Forms started in August.
----------------------------------------------------------------------------------------

Now that you're in apps (../monahan.com/api/apps), use the ?list command to see what you can do.

localhost:8082/david@monahan.com/apps> ?list
Name    Abbr     ArgNum     Descr
up                 1        UPLOAD an application (e.g. 'up /var/contacts_apps.zip')
down               0        DOWNLOAD ALL applications into temp folder (e.g.: 'download')
link     l         1        OPEN a link in the browser (e.g. 'openLink {link#}')
links    li        1        SHOW feed links for given rel attr (e.g. 'links {relAttr}')
links    l         0        SHOW all feed links (e.g. 'links')
next     n         0        NEXT feed page (e.g. 'next')
prev     p         0        PREVIOUS feed page (e.g. 'previous')
print    pr        0        PRINT current feed (e.g.: 'print')
delete   d         1        DELETE an entry (e.g. 'delete {entry#}')
create   c         1        CREATE a new entry (e.g.: 'create {name}')
refresh  r         0        REFRESH current feed (e.g.: 'refresh')
select   s         1        SELECT an entry (e.g.: 'entry {entry#}')

Downloading and Uploading Projects

You can use the apps > down and up commands to download projects to a local drive and upload them to the frevvo server.

Download

In the frevvo UI, you can download projects individually, and select the destination directory.

In this example, down downloads all the projects in the tenant to a directory on the local machine. Since down takes no arguments, the target directory depends on your local machine settings.

Design Time Integration with the Data API