What are we going to build?

This tutorial will cover the following functions: 

1. LoginAs and session management using API.

2. Upload of a sample Tutorial Project into a frevvo designer account. 

3. FormTypeFeed:Initialization of a form with XML data, Attachment and Wet Signature 

   1. List Projects, Forms and Workflows 

   2. Raw and Pop-Up links to use Forms/Workflows 

   3. Edit link to edit Forms/Workflows in design mode 

   4. View Submissions link to list all Form/Workflow Submissions

4. TaskFeed: embed task list

5. SubmissionFeed: Logout of user account using API

   1. List of all Form/Workflow submissions

   2. Link to Edit each submission 

   3. Links to submission XMLs 

   4. Link to submission print PDF 

   5. Links to wet signatures in each submission

   6. Links to uploaded attachments in each submission

What are we going to need?

You will need to do the following to complete this tutorial:

1. Install and start up frevvo.  (e.g.http://localhost:8082)

2. Create a tenant  (e.g. apitutorial) with a tenant admin user (e.g. admin).

3. Add a designer user account (e.g. designer) to your tenant.

4. Follow these steps to install the Java API tutorial web application.

   1. Download the Java API Tutorial v5.2 zipfile.

   2. Extract the web-application api.war file to the <frevvo-home>\tomcat\webapps directory.
      We are using the tomcat servlet which is included in the frevvo bundle.

   3. Re-start frevvo. This will expand the war to the <frevvo-home>\tomcat\webapps\api directory.

Installing the Client Libraries and Dependencies

 The frevvo Java Client Library has the following dependencies:

• com.frevvo.forms.java-5.2.jar　

• com.frevvo.forms.java-5.2-javadoc.jar

• commons-io-2.0.1.jar

• activation-1.1.1.jar

• mail-1.4.4.jar

• json-1.0.0.jar

• commons-httpclient-3.1.jar

• commons-codec-1.2.jar

• commons-logging-1.0.4.jar

These client libraries are already added in <frevvo-home>\tomcat\webapps\api\WEB-INF\lib directory of the web application that we are using. However, the actual jar versions may be different depending on the version of frevvo being used. To ensure that you have the latest versions of these files, it is recommended that you replace the client libraries that come with the Java API Tutorial Project with the .jar files located in the <frevvo-home>\ext\client directory of your frevvo build.

Follow these steps to perform the replacement:

1. Stop frevvo.

2. Copy the latest jar files from <frevvo-home>\ext\client directory of your frevvo build.

3. Replace the files in the <frevvo-home>\tomcat\webapps\api\WEB-INF\lib directory with the client libraries copied in Step 2 .

Configure and Execute the Web Application

You must update the frevvo server and tenant information in the doLogin.jsp file for the web application to work. Follow the steps below:

1. Edit the <frevvo-home>\tomcat\webapps\api \apitutorial\doLogin.jsp file. 
   
   

   1. On line number 14, replace the default values with your frevvo server and port number:

      service = new FormsService("http", "localhost", 8082, null); to service = new FormsService("http", "<your-frevvo-server-host>", <your-frevvo-server-port>, null);

      
      
      

   2. On line number 20, replace the default values with the admin username, tenant and admin user password previously created for this tutorial: 

      "admin@apitutorial", "admin" to "<your-tenant-admin-user>@<your-tenant>", "< your-tenant-admin-user-password>"

2. Save the file and re-start frevvo (tomcat).

To check if your web application is working, browse http://<your frevvo server host>:<port>/api/apitutorial/index.html. E.g. http://192.168.1.71:8082/api/apitutorial/index.html. You should see a login page like this one:

Open

LoginAs

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.

Edit the <frevvo-home>\tomcat\webapps\api\apitutorial\login.jsp file.

1. This JSP page contains a small HTML form with a username field which accepts the frevvo username to be logged in.

2. It also accepts a URL parameter targeturl which is used to redirect the user after login. If a targeturl is not passed to the login.jsp page it will use formtypes.jsp as the default targeturl: 

   String url = request.getParameter("targeturl"); if (url == null) url = "formtypes.jsp"; url = "doLogin.jsp?targeturl=" + url;

     3.  Clicking the Submit button on the login.jsp page calls the doLogin.jsp page.

Edit the <frevvo-home>\tomcat\webapps\api\apitutorial\doLogin.jsp file.

1. In the doLogin.jsp page, we create a FormService instance:

   FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );

2. If the service instance is not null, that is if a user login already exists for the service instance, we logout that user from the FormsService session and remove the service instance from the HTTP session:

   if (service != null) {  service.logout();  session.removeAttribute ("frevvo.forms.service"); } else {  service = new FormsService("http", "localhost", 8082, null); }

3. Then we use the LoginAs method to login to the account whose username was entered on the login.jsp page. This method allows you to login to 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 to frevvo using the same user that is logged into your project without having to know their password.

   The request.getParameter( "username" ) gets the username value which was passed from the login.jsp page.

   The LoginAs method also returns the logged in user information in AutoLoginUserInfo object.

   Map<String, String> customParams = new HashMap<String, String>(1); customParams.put("autoLogin", "true"); customParams.put("checkUserCount", "false"); AutoLoginUserInfo alui = service.loginAs (request.getParameter( "username" ), admin@apitutorial, "admin", true, null, request.getParameter( "firstname" ), request.getParameter( "lastname" ), request.getParameter( "email" ), customParams);

4. Then we add the service instance to the HTTP session: 

   session.setAttribute ("frevvo.forms.service", service);

5. We also save the user information returned in AutoLoginUserInfo object alui to the HTTP session: 

   session.setAttribute ("user.info", alui);

6. Lastly we redirect user to the next JSP page of the web application based on the targeturl parameter: 

   String url = request.getParameter("targeturl"); response.sendRedirect(url);