Versions Compared

Old Version 34

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

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

...

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  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

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

...

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.The frevvo .NET API client library can be downloaded here

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

The download is a zipfile containing the following files:

  • 51<version>_dotNetApiRelease.zip - frevvo .NET client library
  • Help<version>_help_html.zip - HTML documentation
  • Frevvo.Forms.Client.Documentation.<version>_help.chm - chm formatted documentation

...

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

Logging In and Out of the Forms Server

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

Code Block
    FormsService service = new FormsService("http://localhost:8082", "yourappname");
    service.Login("myuser", "mypassword");

    // interact with frevvo

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

Browser URL API

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 before you start writing code.

This section describes the basic protocol used to interact with  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 the general idea of the format and protocol used by the  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 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 . The URIs return data from the  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 to include the URI of the resource feed you want to use. For example:

  • FormTypeFeed: ../frevvo/web/tn/{tenantId/api/formtypes?ownerId={appId}
  • FormTypeEntry: ../frevvo/web/tn/{tenantId}/api/formtype/{id}

The browser URL API provides:

  •  A useful tool for debugging
  •  An easy way to try out the API without having to write code
  •  A way to experiment with and learn the API

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

  1. After logging in, edit the  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.

The browser returns the page below.

Image Removed

If you click on the Address Book link and either open or save the XML file, you see the XML for the form, the first portion of which is shown below.

Warning

Depending on which browser you're using, the browser may return the XML rather than the page in the illustration above.

...

Browser URL API

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 before you start writing code.

This section describes the basic protocol used to interact with  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 the general idea of the format and protocol used by the  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 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 . The URIs return data from the  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 to include the URI of the resource feed you want to use. For example:

  • FormTypeFeed: ../frevvo/web/tn/{tenantId/api/formtypes?ownerId={appId}
  • FormTypeEntry: ../frevvo/web/tn/{tenantId}/api/formtype/{id}

The browser URL API provides:

  •  A useful tool for debugging
  •  An easy way to try out the API without having to write code
  •  A way to experiment with and learn the API

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

  1. After logging in, edit the  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.

The browser returns the page below.

Image Added

If you click on the Address Book link and either open or save the XML file, you see the XML for the form, the first portion of which is shown below.

Warning

Depending on which browser you're using, the browser may return the XML rather than the page in the illustration above.

Code Block
<entry xmlns:fd="http://schemas.frevvo.com/fdata/2008"
        xmlns="http://www.w3.org/2005/Atom"
        xml:lang="en"
        xml:base="http://localhost:8082">
    <id>_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david</id>
    <title type="text">Address Book</title>
    <summary type="text">David - July 2011</summary>
    <updated>2011-07-22T11:23:25.326</updated>
    <category scheme="http://schemas.frevvo.com/fdata/2008#kind" term="FORM"/>
    <link type="application/atom+xml"
        href="/frevvo/web/tn/monahan.com/api/formtype/_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"/>
    <link rel="self" type="application/atom+xml"
        xmlnshref="http://www.w3.org/2005/Atom"/frevvo/web/tn/monahan.com/api/formtype/_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"/> 
    <link    xml:lang="enrel="edit" type="application/atom+xml"
        xml:basehref="http:/frevvo//localhost:8082">
    <id>web/tn/monahan.com/api/formtype/_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david</id>
    <title type="text">Address Book</title>
    <summary type="text">David - July 2011</summary>
    <updated>2011-07-22T11:23:25.326</updated>
    <category scheme="http://schemas.frevvo.com/fdata/2008#kind" term="FORM"/>
    <link type="application/atom+xml"
        href="david"/>

This example shows how to use the controltypes feed to get a list of all the control types that belong to the currently logged-in user, regardless of which forms they're used in.

  1. After logging in, edit the  URL in the browser address bar to insert api/controltypes 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/

...

  1. controltypes, and press Enter.

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

Image Added

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 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/

...

  1. user/

...

  1. david/app
  2. to: http: //localhost:8082/frevvo/web/tn/monahan.com/api/controltypes?ownerId=_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david

...

This example shows how to use the controltypes feed to get a list of all the control types that belong to the currently logged-in user, regardless of which forms they're used in.

  1. After logging in, edit the  URL in the browser address bar to insert api/controltypes 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, and press Enter.

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

Image Removed

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 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 shown in the XML example above, including the ID (david) of the user who created the form.

The browser returns the page below.

Image Removed

If you click on the RequiredFieldPrompt link and either open or save the XML file, you see the XML for the control, which is shown below.

...

  1. , and press Enter.
Note

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

The browser returns the page below.

Image Added

If you click on the RequiredFieldPrompt link and either open or save the XML file, you see the XML for the control, which is shown below.

Code Block
<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:fd="http://schemas.frevvo.com/fdata/2008"
        xml:base="http://localhost:8082">
    <id>_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david</id>
    <title type="text">RequiredFieldPrompt_</title>
    <summary type="text">Message 39</summary>
    <category scheme="http://schemas.frevvo.com/fdata/2008#controltype"
            term="OutputControlType"/>
    <category scheme="http://schemas.frevvo.com/fdata/2008#displaytype" term="Message"/>
    <updated>2011-07-25T13:52:22.017-04:00</updated>
    <fd:required value="true"/>
    <fd:readonly value="false"/>
    <link rel="parent" type="application/atom+xml"
            xml:base="http://localhost:8082">
    <id>_bjLLYbIIEeClr-dcvjFaZghref="/frevvo/web/tn/monahan.com/api/controltype/_fQoD8a4rEeCMGZK99v93jw!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david</id>david"
     <title type="text">RequiredFieldPrompt_</title>     <summary typetitle="text">Message 39</summary>This entry's parent control type"/>
    <category<link schemetype="http://schemas.frevvo.com/fdata/2008#controltype"
     application/atom+xml"
      term="OutputControlType"/>     <category schemehref="http://schemas.frevvo.com/fdata/2008#displaytype" term="Message"/>
    <updated>2011-07-25T13:52:22.017-04:00</updated>/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
     <fd:required value="true"/>     <fd:readonly valuetitle="falseThis entry"/>
    <link rel="parentself" type="application/atom+xml"
            href="/frevvo/web/tn/monahan.com/api/controltype/_fQoD8a4rEeCMGZK99v93jwbjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry's parent control type"/>
    <link type="application/atom+xml"
</entry>

Logging In and Out of the Forms Server

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

Code Block
    FormsService service =      href="/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry"/>new FormsService("http://localhost:8082", "yourappname");
    <link rel="self" type="application/atom+xml"service.Login("myuser", "mypassword");

    // interact with frevvo

    href="/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry"/>
</entry>service.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  before logging out. Logging out ensures that  will release any unneeded resources and the user count will be decremented, as the number of users is affected by your  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 has reviewed a product order form on their task list and signed it and submitted it. This is the final form workflow step and the form is submitted to a document management system (ECM). All the form data as well as the PDF order form image is 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. The demo.war contains a api/resetTask.jsp that demonstrates how to use this API feature: 

  1. Copy <frevvo-home>/ext/demo.war to frevvo<frevvo-home>/tomcat/webapps. It will auto-extract.
  2. Edit frevvo/tomcat/webapps/demo/api/resetTask.jsp
    1. Set the host:port to your frevvo server
    2. Set the username and password and tenant to the designer user how is the owner of the workflow you want to reset
  3. Enable the flow's save property so the flow data is stored in frevvo's submission repository. This is critial as frevvo needs to access this data in order to reset the workflow back to a task list.
  4. restart Restart the frevvo server.
  5. Use the flow and complete/submit it.
    1. Save the frevvo.form.id POST parameter. It will be a GUID such as _udowHBy0EeCJpdjaAfsaSA  

To reset the completed/submitted flow back to a task list, send a POST from your system to the resetTask.jsp. You must pass the flowing Url parameters to resetTask.jsp:

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

...