==Introduction==
This Tutorial will show you how you can embed frevvo forms and workflows in your web site or web application. In some cases, you may wish to integrate authentication between your application and frevvo so that your users don't have to sign in twice yet are automatically authenticated to frevvo. You may want your users to be authenticated for access control, digital signatures, participating in workflows, viewing their task lists or for maintaining an audit trail.
==Embedding Forms & Workflows for Anonymous Use==
[[Image:Embedded_form_flow.png|frame|left|frevvo form/workflow embedded in your web site]]
<br style="clear: both" />
If you do not require access control or authentication for other purposes, i.e. your forms are public forms on your Extranet, you can simply use frevvo's built-in Share Dialog and copy and paste the code into your HTML, JSP, ASP, PHP or other web page. An example is frevvo's [http://www.frevvo.com/frevvo/web/static/contactUs own contact form]. No authentication is required and the form is completed and submitted anonymously.
You can find [[V4_Using_Forms#Sharing_Forms | instructions for embedding forms and flows here]].
==Integrating authentication with your web application (using the frevvo API)==
[[Image:Api_login_render_form.png|frame|left|frevvo form/workflow embedded in your web site]]
<br style="clear: both" />
The basic steps are shown in the above Figure. You'll need to be familiar with [[V4_Tenants_Page|creating and managing tenants] including creating a tenant using the Delegating Security Manager.
===Installing the Client Library and Dependencies===
The examples below use the API to authenticate to frevvo. Before using the API, you will need to install the client libraries for your language. frevvo offers Java and .NET client libraries. The examples below use the Java client libraries; the .NET versions are very similar.
[[Getting_Started_with_the_frevvo_Data_API_Java_Client_Library#Installing_the_Client_Library_and_Dependencies | Click here for instructions on installing the Java client library]].
=== Authentication & Session Management ===
In order to automatically integrate with frevvo, your web application will first need to establish a session using the frevvo API. This is done by using the '''com.frevvo.forms.client.FormsService''' class and by providing proper credentials to authenticate.
In most cases, you will want to use the loginAs() method available in V4.1.1 and higher. loginAs() allows you to login to frevvo as any existing tenant user provided you pass in the tenant admin's user and password credentials. This is convenient when you want login to frevvo using the same user that is logged into your application without having to know their password.
====Login as an existing user====
The following snippet shows how to login as a tenant user. This usage assumes that the user has already been created in the tenant.
<pre>
...
// tenantAdminUserId must be specified as adminUserId@tenantName
FormsService s = new FormsService(protocol, host, port, null);
s.loginAs(userId, tenantAdminUserId, tenantAdminPassword);
...
</pre>
* protocol is one of http or https
* host is the frevvo server host name
* port is the port on which frevvo is running
* userId is the tenant user's id
* tenantAdminUserId is the user id of the tenant admin user specified using the syntax adminUserId@tenantName
* tenantAdminPassword is the password of the tenant admin user
====Auto-create users in a tenant====
frevvo can also automatically create users in your tenant if you created it with [[V4_Tenants_Page#Delegating_Security_Manager | the Delegating Security Manager]].
<pre>
...
List<String> roles = Collections.singletonList("manager");
FormsService s = new FormsService(getProtocol(), getHost(), getPort(), null);
// tenantAdminUserId must be specified as adminUserId@tenantName
s.loginAs(userId, tenantAdminUserId, tenantAdminPassword, true, roles, firstName, lastName, email, null);
...
</pre>
This will log you in as the specified userId. If a user with that ID does not exist, the user will be automatically created. The user will have any existing roles as well as the role "manager". If you do not want to specify any roles, you may pass in null. Of course, you can pass in a List with as many roles as you want.
If you want frevvo to auto create a new user that can design forms, you need to pass in the '''frevvo.Designer''' role when calling loginAs().
<span style="font-weight:bold;background-color:#ffce7b">This is typically not required unless you are an OEM customer embedding the frevvo Designer in your product.</span>
For instance:
<pre>
...
List<String> roles = Collections.singletonList("frevvo.Designer");
FormsService s = new FormsService(protocol, host, port, null);
s.loginAs(userId, tenantAdminUserId, tenantAdminPassword, true, roles, firstName, lastName, email, null);
...
</pre>
====JSP Usage====
Your JSP page code will look very similar to the above. An important thing to note is 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). Typically, in a web application context, the FormsService instance is stored in the HTTP session that the user has with your web application.
<pre>
<%@ 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);
</pre>
==Embed a form or workflow with authentication==
<div style="font-weight:bold;background-color:#63ffc7">[[Image:Lightbulb.png]] Make sure you have read and understood the documentation on [[V4_Using_Forms#Making_a_Form_Public | making forms and flows public]].</div>
Now that you have logged in, you must use the FormsService created above to get an embed URL for the form/flow that you want to embed.
<pre>
FormTypeEntry ftEntry = (FormTypeEntry) service.getEntry(
service.getEntryURL(FormTypeEntry.class, "_iAMawOa4Ed-TkpzYF5hpcQ!_MOrvYeV9Ed-6Ft_YAwCXMQ!designer"),
FormTypeEntry.class);
String formUrl = ftEntry.getFormTypeEmbedLink(null).getHref();
</pre>
The ID is constructed using the syntax: formTypeId!applicationId!ownerId where:
* formTypeId is the ID of the form/flow.
* applicatioinId is the ID of the frevvo application containing the form/flow.
* ownerId is the ID of the designer user who owns the form/flow.
You can find the IDs using the Share dialog for the form or flow in question. In the Figure below, the Share URL contains:
* The formTypeId (in this case it is actually a flowTypeId) is _BgfQgAneEeCBmoiAt_ZHPg
* The application Id is _Eo5BUQndEeCBmoiAt_ZHPg
* The ownerId is designer
[[Image:Flow_Share_Dialog.png|frame|left|Share Flow Wizard]]
<br style="clear: both" />
Once you have the embed URL, embed it in your JSP as:
<pre>
<script src="<%= formUrl %>" type="text/javascript" language="Javascript"></script>
</pre>
===Finding an existing saved form/flow===
<div style="font-weight:bold;background-color:#63ffc7">[[Image:Lightbulb.png]] Make sure you have read and understood the documentation on [[V4_Using_Forms#Save.2FLoad | saving partially completed forms or flows]].</div>
<div style="font-weight:bold;background-color:#63ffc7">[[Image:Lightbulb.png]] Make sure you have read and understood the documentation on [[V4_Tasks_Home_Page | using the Task List]].</div>
If your user has a saved form/flow, you can find it and render the saved form/flow instead of creating a new one as described above.
<pre>
Map<String, Object> params = new HashMap<String, Object>();
params.put("container", true); // Creates a container (HTML table or div) around the form.
params.put("center", false); // Center the container on the page if desired.
params.put("resize", true); // Automatically resize the container as the form's height changes.
// First, check if there is a SAVED task for the formTypeId in question.
String formUrl = null;
TaskFeed sFeed = service.getFeed(service.getFeedURL(TaskFeed.class), TaskFeed.class);
for (TaskEntry sEntry : sFeed.getEntries()) {
if (!("SAVED".equals(sEntry.getState())))
continue;
if (!sEntry.getFormTypeEmbedLink(null).getHref().contains("_iAMawOa4Ed-TkpzYF5hpcQ"))
continue;
formUrl = sEntry.getFormTypeEmbedLink(params).getHref();
break;
}
if (formUrl == null) {
// No saved task found. Create a new form instance.
FormTypeEntry ftEntry = (FormTypeEntry) service.getEntry(
service.getEntryURL(FormTypeEntry.class, "_iAMawOa4Ed-TkpzYF5hpcQ!_MOrvYeV9Ed-6Ft_YAwCXMQ!designer"),
FormTypeEntry.class);
formUrl = ftEntry.getFormTypeEmbedLink(params).getHref();
}
<script src="<%= formUrl %>" type="text/javascript" language="Javascript"></script>
</pre>