This tutorial will walk you through a few API scenarios focusing on the design-time integration such as creating new forms, listing and managing applications, launching the designer for a flow, downloading schemas, applications, forms and flows, download the XSD for a form/flow, uploading custom XSDs, using forms and flows.
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-base 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 for 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
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:
This should show you usage information:
So you if you want to connect to a Live Forms install running on localhost you can do as follows:
And you should see the command line prompt:
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 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):
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 it's description (used by ?print described above).
Now let's move on to some usage scenarios.
The following topics show how to log in to the Live Forms server and use the command line API to interact with the server, applications, and forms and flows.
Connect to a Server and Log In
The example below shows how to log in to a local Live Forms 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 firstname.lastname@example.org david).
To login, you must first create a tenant on the server (other than the default d tenant). You should also create a user such as a frevvo.designer or an admin user.
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 applications on the server.
The Live Forms UI displays the applications belonging to the user email@example.com on the applications home page.
The apps command displays a list of the applications in the tenant on the server — DTM July 2011'and DTM August 2011 in this example.
Now that you're in apps (../monahan.com/api/apps), use the ?list command to see what you can do.
Downloading and Uploading Applications
You can use the apps > down and up commands to download applications to a local drive and upload them to the Live Forms server.
In the Live Forms UI, you can download applications individually, and select the destination directory.
In this example, down downloads all the applications in the tenant to a directory on the local machine. Since down takes no arguments, the target directory depends on your local machine settings.
To download a single application, you must first select it. See the Downloading and Uploading a Form/Flow topic for instructions for selecting and application.
In the Live Forms UI, you can upload applications from the applications page.
In this example, up uploads a single application into the tenant. Note that we moved the ZIP files we downloaded in the previous step to a different directory before using up.
After the upload, the command prompt now includes the name of the uploaded application (''../apps/DTM August 2011''). Use the ?list command to see what you can do with the application.
Downloading and Uploading a Form/Flow
You can use the forms > down and up commands to download forms and flows to a local drive and upload them to the frevvo server.
Before you can use the commands, you have to select the application whose forms you want to work with. In this example, we use the apps command to list the applications in the tenant, and then select to select the application we want (e.g., select 1 — select the first application in the list).
The command prompt now includes the selected application — DTM July 2011'. Use the forms command to see a list of the forms and flows in the application, and then use ?list to see what you can do with them.
As with downloading applications, in the Live Forms UI, you can download individual forms and flows and select the destination directory when you're editing an application on the applications home page.
In this example, down downloads all the forms and flows in the tenant to a directory on the local machine. You can't choose which forms to download, and since down takes no arguments, the target directory depends on your local machine settings. Since the command downloads
As with uploading applications, in the frevvo UI, you can upload forms and flows from the applications page when you're editing an application.
In this example, up uploads a single form — the ''TitleDepartment'' form — into the tenant. Note that we moved the ZIP files we downloaded in the previous step to a different directory before using '''up'''.
After the upload, the command prompt now includes the name of the uploaded form (''../forms/TitleDepartment'').
Creating a Form/Flow
You can use the forms> create command to create a new form or a flow. You first select the application to which you want to add the new form, list its forms, and then create the form.
The command prompt includes the new form name (''../forms/TestForm>''), so you can Downloading and Uploading a Form/Flow from the command line at this point.
Editing a Form/Flow
To edit a form, you first select the application the form belongs to, and then select the form you want. See Downloading and Uploading a Form/Flow for instructions on selecting an application.
Once you've gotten to the application you want, you can use the forms command to see what forms it contains and use ?list to see what you can do with them. In the example below, we use select 1 to select the first form in the list (Address Book).
If you want, use ?list to see what you can do with the form.
To edit the form, type edit and press Enter. The command line displays the response below, and frevvo launches the form designer and displays the form you selected.
You can edit the form in the designer as if you had logged in through the UI. Make any changes you want to the form, and then click Finish or Cancel to exit the designer. You return to the UI login page.
Using a Form/Flow
Once you've selected a form, you can use it; this is, you can run the form as an end-user would. See the Editing a Form/Flow topic above for instruction on selecting a form. Then simply type use at the command prompt and press Enter. Live Forms opens the form or flow in your browser.
Display a List of the Controls in a Form
After you select a form, you can display a list of all the controls in the form. See the Editing a Form/Flow topic above for instruction on selecting a form. Then simply type controls at the command prompt and press Enter. You see the list of controls.
Once you display the list, you can select a control and rename it, edit its description, or even delete it.
Downloading and Uploading an XSD
You can download and upload the schema (XSD file) for a form. In the frevvo UI, you download a form schema from the application page when you're editing an application; you upload a schema from the schema page.
To download a form schema, you first select the form you want and then use the [form name]> schema command.
Creating a Form Instance from XML
After you select a form in an application, you can use the [form-name]> newXml command to create an instance of the form and fill the form with data values from an XML file. You can then submit the form, or reset it to remove the XML data.
If you paste the form URL into your browser address bar, you can open the form instance and see the XML values in the form fields. You can Submit of Cancel the form from the browser, or you can use Instance #1> submit or Instance #1> reset from the command line.
Using a Custom XSD in a Form
You can use an XSD schema file to populate a form with controls. You can add the entire XSD schema to the form or individual controls. This example uses the API to upload a custom schema to an application, add one of the top-level XSD elements to a form and then shows the result in the designer UI.
Upload a custom XSD
The first step is to upload a custom XSD into an application. The following commands will list the existing schemas in the current application and then upload a new one (this assumes that there is an XSD named purchaseorder.xsd located in the /xsd folder):
Now, the purchaseorder.xsd has been upload and you can verify that this is the case by going directly to the Live Forms UI in Applications->Schemas.
Add an new XSD data source to a form
First, let's create a new form.
Now that we have a new form, we need to add a new XSD data source to the form using the API, which is the equivalent to adding a new data source in the designer by clicking the Data Sources panel and then clicking New from XSD as shown in the following screenshots.
Live Forms displays the available schemas in the current application. You can then click to select the XSD you want to use. Live Forms adds it to the Data Sources panel.
Here is how to add a new data source using the API.
There should be only one element in the docs feed for the default, from-palette schema. Now we need to add the purchaseOrder element from theXSD targetNamespace to the form:
Let's open the designer to see the result:
It is not possible to auto-generate controls from '''Data Sources''' schemas. So the form designer would still have to perform this step manually.
You can now use the new form from the command line.