The Data API Feeds

There are various different types of  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 application using the  UI, for instance users, applications, form, themes, 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.

...

Tutorial: Getting Started with the Java Client Library

Follow this tutorial to build a simple application to manage a contacts list. The tutorial shows you how to use the  submissions API to query the submissions repository, to filter submissions, sort, paginate, etc.

...

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

...

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.

...

For a list of Frequently Asked question about common tasks using the API with  servera  server, please see the Oracle Forms API FAQ - Java Client FAQAPI.

Installing the Client Library and Dependencies

...

For your convenience all these required jars can be found in the  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 that the

...

Authentication & Session Management

...

The example below is taken from the tutorial Getting Started with the Jave Data Client Library.

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

...

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

TBD

.Net Client API FAQ

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

Logging In and Out of the Oracle 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.

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

The download is a zipfile containing the following files:

• <version>_dotNetApiRelease.zip - frevvo .NET client library
• <version>_help_html.zip - HTML documentation
• <version>_help.chm - chm formatted documentation

.Net Client API FAQ

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

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.

...

<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"
            href="/frevvo/web/tn/monahan.com/api/controltype/_fQoD8a4rEeCMGZK99v93jw!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry's parent control type"/>
    <link type="application/atom+xml"
            href="/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry"/>
    <link rel="self" type="application/atom+xml"
            href="/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry"/>
</entry>

Calling the API from a JSP Page

An important thing to note about JSP pages is that the FormsService instance is state-full and the same instance needs to be used throughout the session - this is 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. Typically, in a web application context, the FormsService instance is stored in the HTTP session that the user has with your web application.

<%@ page import="java.util.*,com.frevvo.forms.client.*,com.frevvo.forms.client.util.*" %>
FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );
if (service == null) {
        service = new FormsService("http", "localhost", 8082, null);
        service.loginAs (request.getParameter( "username" ),
            tenantAdminUserId, tenantAdminPassword, true, null,
            request.getParameter( "firstname" ),
            request.getParameter( "lastname" ),
            request.getParameter( "email" ), null);
        }
session.setAttribute ("frevvo.forms.service", service);    href="/frevvo/web/tn/monahan.com/api/controltype/_bjLLYbIIEeClr-dcvjFaZg!_fNScEK4rEeCMGZK99v93jw!_W0jPga4rEeCMGZK99v93jw!david"
            title="This entry"/>
</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.

    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.

Calling the API from a JSP Page

An important thing to note about JSP pages is that the FormsService instance is state-full and the same instance needs to be used throughout the session - this is 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. Typically, in a web application context, the FormsService instance is stored in the HTTP session that the user has with your web application.

<%@ page import="java.util.*,com.frevvo.forms.client.*,com.frevvo.forms.client.util.*" %>
FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );
if (service == null) {
        service = new FormsService("http", "localhost", 8082, null);
        service.loginAs (request.getParameter( "username" ),
            tenantAdminUserId, tenantAdminPassword, true, null,
            request.getParameter( "firstname" ),
            request.getParameter( "lastname" ),
            request.getParameter( "email" ), null);
        }
session.setAttribute ("frevvo.forms.service", service);

ResetTask.jsp

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

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

Here is an example Url if the name of the activity that the sales person performed was "SalesReview" and the frevvo.form.id sent in the post to your back end system was _2U71ABwbEeC6avHeCMEeBw 

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

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

<%@ page import="java.util.*,com.frevvo.forms.client.*,com.frevvo.forms.client.util.*" %>
<html>
   <head>
   </head>
   <body>
<%
FormsService service = new FormsService("http", "localhost", 8082, null);
  service.login ("designer@nancy.com", "designer");

String formId = request.getParameter("frevvo.form.id");
TaskEntry entry = service.getEntry(service.getEntryURL(TaskEntry.class, formId), TaskEntry.class);
String stepName = request.getParameter("frevvo.reset.activity.name");
entry.setResetToStep(stepName);
entry.update();

service.logout();
%>
Your task was successfully reset.
   </body>
</html>
<pre>