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:

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

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

On your web applications login page, enter your designer user name and click Submit. You will see the formtypes.jsp page shown in the image:

Uploading the Tutorial Project

Now that you have displayed the formtypes.jsp page, let's look at the formtypes.jsp file to see how this is implemented:  

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

1. The formtypes.jsp checks if the HTTP session contains a FormService instance with a valid user login. If not, then it redirects to the login.jsp page to create a valid user login:

   FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );
   if (service == null) {
             response.sendRedirect("login.jsp");
             return;
   }   

2. It also gets the user information stored in the user.info attribute of the HTTP session. The ApplicationFeed and FormTypeFeed are available only for designer user logins. We will not retrieve the projects and forms if the current logged in user is not a designer, i.e. alui.designer is false:

   AutoLoginUserInfo alui = (AutoLoginUserInfo) session.getAttribute ( "user.info" );
      if(!(alui.designer)){
                ...

3. Next it gets the ApplicationFeed for the current logged in user:

   ApplicationFeed af = service.getFeed(service.getFeedURL(ApplicationFeed.class), 
   ApplicationFeed.class);

4. Now it will check if the Tutorial Project exists in the current logged in designer user account:

   ApplicationEntry TutorialApp = null;
       String TutorialAppName = "Tutorial Application"; 
    
   for (ApplicationEntry appEntry :af.getEntries()) {    
        if (TutorialAppName.equals(appEntry.getTitle().getPlainText())){ 
                 TutorialApp = appEntry;
                 break;        
        } else {
         continue;
        }
   }       

5. If the Tutorial Project does not exist then it will upload the project to the designer user account. The project zip file that we are uploading is <frevvo-home>\tomcat\webapps\api\apitutorial\Resources\TutorialApplication_v52_app.zip.

   String EmpInfoFromName = "Employee Information";
   if(TutorialApp == null){
        String 
   filepath=getServletContext().getRealPath("/apitutorial/Resources/TutorialApplication_v52_app.zip");     
        InputStream appZipStream = new FileInputStream(filepath);
    
        MediaStreamSource appMediaSource = new 
   MediaStreamSource(appZipStream,"application/zip");      
        ApplicationEntry appEntry = af.insert(appMediaSource); 

6. The default deployment state of the Employee Information form in this uploaded project is DEVELOPMENT. We changed the deploy state of the form to PRODUCTION with the code shown below:

        FormTypeFeed ftFeed = appEntry.getFormTypeFeed(); 
        for (FormTypeEntry empform : ftFeed.getEntries()) { 
             if (EmpInfoFromName.equals(empform.getTitle().getPlainText())){ 
                     empform.setDeployState(DeployState.PRODUCTION); 
                     empform = empform.update(); 
                     empform = empform.getSelf(); 
                     break; 
             } else { 
                     continue; 
             } 
        } 
   }  

    

List Projects / Forms and Workflows

Once the project is uploaded we now list all the Projects/Forms/Workflows in this user account.

1. We get the updated ApplicationFeed after the Tutorial Project is uploaded. The application feed contains all the projects in this user account: 

   af = service.getFeed(service.getFeedURL(ApplicationFeed.class), ApplicationFeed.class); 

2. Then we iterate over each ApplicationEntry in the ApplicationFeed and from each ApplicationEntry we get the FormTypeFeed which contains the forms and workflows in that project:

   String[] types = {"FORM", "FLOW"}; 
   for (ApplicationEntry ae : af.getEntries()) { 
    FormTypeFeed ftf = ae.getFormTypeFeed();  
    … 

3. We iterate over each FormTypeEntry in the FormTypeFeed twice using the types iterator defined above. Once to collect all the forms and the second time to collect all the workflows in that project:

   for (String mytype : types){
            for (FormTypeEntry fte : ftf.getEntries()) { 
            if(fte.getKind().contentEquals(mytype)){
            … 

4. Then we get the Raw Link, Popup Link and Edit link for the forms/workflows from the FormTypeEntry:

   //Get Raw Link
   String RawLink = fte.getFormTypeLink(null).getHref() + formAction;
   //Get Popup Link
   String PopUpLink = fte.getFormTypePopupLink(null).getHref() + formAction;
   //Get Form Edit Link to edit the form in design mode
   String EditorLink = fte.getFormTypeEditorLink(null).getHref() + formAction;

5. Next we check if there are any submissions associated with the form/workflow. If yes, then we get the FormTypeID for the form. Then this FormTypeID is appended as the URL parameter to the showSubmissions.jsp page link. The showSubmission.jsp page will use this FormTypeID to list all the form submissions (See SubmissionFeed):

   if(fte.getSubmissionFeed().getEntries().size() > 0) {  
            String formtypeid = fte.getId().split("!")[0];  
            String SubmissionsLink = "showSubmissions.jsp?formtypeId=" + formtypeid;
            ...

      

Initialize the Form with data

Click on the Initialize From XML link displayed against the Employee Information Form. You should see the form fields initialize with data from XML files. Similarly the upload control is initialized with an attachment file and the wet signature control is initialized with a signature image:

To initialize the Employee Information form with XML Data, Wet Signature and the Attachment, we use the FormEntryBuilder Class. You will find the XML files, upload control attachment and wet signature image that we are using in the <frevvo-home>\tomcat\webapps\api\apitutorial\Resources directory of the web application.  

if (EmpInfoFromName.equals(fte.getTitle().getPlainText())){
           FormTypeEntry employeeInfoForm = fte;

           FormEntryBuilder builder = employeeInfoForm.createInstanceBuilder();

 
           //XML for palette controls
           String xmlFile1=getServletContext().getRealPath("/apitutorial/Resources/TomCat.xml"); 

           InputStream is_xml = new FileInputStream(xmlFile1);
           builder.document("TomCat", is_xml);

           //XML for schema controls
           String xmlFile2=getServletContext().getRealPath("/apitutorial/Resources/TomCatAddress.xml"); 
           InputStream is_xml2 = new FileInputStream(xmlFile2);
           builder.document("TomCatAddress", is_xml2);    

 
           //Attachment File
           String 
           attachmentFile=getServletContext().getRealPath("/apitutorial/Resources/TomCatProfileAttachment.jpg"); 
           InputStream is_attachment = new FileInputStream(attachmentFile);
           builder.attachment("UploadAProfilePicture", "image/jpeg", "TomCatProfileAttachment.jpg", is_attachment);

 
           //Wet Signature File
           String 
           signatureFile=getServletContext().getRealPath("/apitutorial/Resources/TomCatSignature.png"); 
           InputStream is_wetSignature = new FileInputStream(signatureFile);
           builder.wetSignature("_kRnhsUGSEeO6ha2krvWZUA", "TomCatSignature.png", is_wetSignature);

 
           //Form Action
           builder.parameter("_formActionUrl", request.getRequestURL().toString().substring(0, request.getRequestURL().toString().lastIndexOf('/')) + "/index.html");
           builder.parameter("_formActionTarget","top");
           builder.parameter("_cancelUrl", request.getRequestURL().toString().substring(0, request.getRequestURL().toString().lastIndexOf('/')) + "/index.html");

 
           FormEntry fEntry = builder.createInstance();
           String XMLInitializeFormURL = fEntry.getFormUseLink().getHref(); 
}

Embed Task List

 On the XML initialized Employee Information form, click the Save button to create a saved task:

Click on the Tasks link from the left menu to open the task list. Clicking on the perform icon of the saved task will load the saved form.

 Edit the <frevvo-home>\tomcat\webapps\api\apitutorial\showTaskList.jsp file to see how the task list is embedded using the API. 

1.  First the showTaskList.jsp checks if the HTTP session contains a FormService instance with a valid user login. If not, then it redirects to login.jsp page to create a valid user login:

   FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );
   if (service == null) {
      response.sendRedirect("login.jsp?targeturl=showTaskList.jsp");
      return;
   }

2. Then it gets the TaskFeed for current logged in user:

   TaskFeed tFeed = service.getFeed(service.getFeedURL(TaskFeed.class), TaskFeed.class); 

3. Using the Taskfeed we then get the Link to embed the users Task List. We use the URL Parameters container, center, resize and width to fit the task list to the space available in the embedded page.

   Map<String, Object> params = new HashMap<String, Object>(); 
   params.put("container", true); 
   params.put("center", false); 
   params.put("resize", false); 
   params.put("width", "1500px"); 
   String taskListEmbedURL = tFeed.getTaskListEmbedLink(params).getHref(); 

List Form /Workflow Submissions

Perform and Submit the saved task in the task list to create a form submission. Click on the Forms/Workflows link in the left menu. You should now see a View Submissions link against the Employee Information form: 

Click on the View Submissions link to see the Employee Information form submissions:

Edit the <frevvo-home>\tomcat\webapps\api\apitutorial\showSubmissions.jsp file to see how we get the form submissions using the API. As explained in point 5 above, we pass the FormTypeID to the showSubmissions.jsp page in the View Submissions link.

1. The showSubmissions.jsp checks if the HTTP session contains a FormService instance with a valid user login. If not, then it redirects to login.jsp page to create a valid user login:

   FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );
   if (service == null) {     
             response.sendRedirect("login.jsp?targeturl=showSubmissions.jsp");   
             return;   
   }

2. It also gets the user information stored in the user.info attribute of the HTTP session. The SubmissionFeed is available only for designer user login. We will not retrieve the submissions if the current logged in user is not a designer, i.e. alui.designer equals false:

   AutoLoginUserInfo alui = (AutoLoginUserInfo) session.getAttribute ( "user.info" ); 
   if(!(alui.designer)){ 
             ...

3. Now we create SubmissionQuery q that will be used to retrieve the SubmissionFeed:

      SubmissionQuery q = new 
   SubmissionQuery(service.getFeedURL(SubmissionFeed.class)); 

4. We get the FormTypeID that is sent as the URL parameter using request.getParameter( "formtypeId" ) and add it to the SubmissionQuery filter:

   Note that if the formtypeId is not passed to the showSubmissions.jsp page (for example when you click on the Submissions link in the left menu) the filter will not be set and submissions for all the forms/workflows in the logged in users account will be listed.

   String ftId = request.getParameter( "formtypeId" );     
   if (ftId != null)       
             q.setFilter("$formTypeId eq " + ftId); 

5. Next we get the SubmissionFeed using the SubmissionQuery:

   SubmissionFeed sFeed = service.getFeed(q, SubmissionFeed.class); 

6.  We will iterate over all the SubmissionEntries in the SubmissionFeed:

   for (SubmissionEntry entry : sFeed.getEntries()) { 
           ...

7. We get these details from each SubmissionEntry:

   1. Link to Edit the submission:

      String SubmissionLink = entry.getFormTypePopupLink(null).getHref() + 
      formAction; 

   2. Submission Form Name:

      entry.getTitle().getPlainText()

   3. Submission Last Updated Date:

      entry.getUpdated()

8. We use the doctypes iterator to iterate over four types of documents in entry.getDocumentLinks(): 

   String[] doctypes = {"text/xml", "frevvo-snapshot", "frevvo-signature-image", "frevvo-attachment"};
   for (String doctype : doctypes){
     if(entry.getDocumentLinks().size() > 0) {
        if(entry.getDocumentLinks().get(i).getType().contains(doctype)){
                    ...

9.  The four iterations over all entry.getDocumentLinks() collect:

   1. Links to the Submission XMLs:

      if(doctype == "text/xml"){
                  String XmlName =
      entry.getDocumentLinks().get(i).getType().substring(entry.getDocumentLinks().get(i).getType().lastIndexOf("=") + 1);
                  String XmlLink = entry.getDocumentLinks().get(i).getHref();

   2. Link to the generated Submission PDF:

      }else if(doctype == "frevvo-snapshot"){
                 String PDFname = entry.getTitle().getPlainText() + ".PDF";
                 String PDFLink = entry.getDocumentLinks().get(i).getHref();

   3. Links to the Wet Signature images of the submission:

      }else if(doctype == "frevvo-signature-image"){
                 String SignatureImageName = entry.getDocumentLinks().get(i).getType().substring(entry.getDocumentLinks().get(i).getType().lastIndexOf("=") + 1);
                 String SignatureImageLink = entry.getDocumentLinks().get(i).getHref();

   4. Links to the uploaded attachments in the submission:

      }else if(doctype == "frevvo-attachment"){
                 String AttachmentName = 
      entry.getDocumentLinks().get(i).getType().substring(entry.getDocumentLinks().get(i).getType().indexOf("filename=")+10, 
      entry.getDocumentLinks().get(i).getType().indexOf(';', 
      entry.getDocumentLinks().get(i).getType().indexOf("filename="))-1);
              String AttachmentFileLink = entry.getDocumentLinks().get(i).getHref();
      
      }
      ...

Logout

 Click on the Logout link in the left menu. The users FormService session is destroyed and you will be redirected to the login.jsp page.

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

1. The logout.jsp will check if the service instance is not null, that is if a user login already exists for the service instance. If yes, then we logout that user from the FormsService session and remove the service instance from the HTTP session:  

   FormsService service = (FormsService) session.getAttribute ( "frevvo.forms.service" );    
   if (service != null) {     
             service.logout(); 
             session.removeAttribute ("frevvo.forms.service");      
   }

2. Then it will redirect the user to the login.jsp page of the web application:

   response.sendRedirect("login.jsp");