V4 Data Sources and Schemas

frevvo Live Forms™ v4

Data Sources and Schemas

Overview

frevvo forms can be created:

1. By dragging frevvo palette control onto the form canvas
2. By adding controls from a data source

From Palette

frevvo forms can be created by dragging and dropping controls from frevvo's control palette to the form canvas. As you do this frevvo automatically creates an XSD description of your form's controls. You can download this XSD from the forms home page.

From Data Source

frevvo also allows you to generate forms automatically based on one or more pre-existing XML schemas. This enables you to quickly can create forms that align with your databases, web services, BPM system, and key business applications. For practical examples of this approach please refer to creating a form to work with your database

From Palette & Data Source

You can mix and match these two approaches of form creation. You can create all the controls in your form from XML schema elements. You can create all the controls in your form from frevvo's palette. Or you can create part of the form from schema elements and part from palette controls that have no relation to the elements in your schema.

When users submit a form that was created wholly or in part from schemas, you will see in the Submissions repository one XML instance document for each global schema element. You also will see one XML document for the form itself, which references any controls you dragged in from the palette. All XML documents are automatically validated against their schemas.

When you upload a schema to frevvo, you can use any and all global elements in the schema. If you want items from the schema that are not global elements, edit the schema and make the items global elements before uploading the schema to frevvo.

At a high level, when you work with schemas you do the following:

• Upload your schema to one of your frevvo applications
• Choose the global elements you want and add them to your form’s Data Sources
• Generate form controls from the global elements you’ve added
• Modify the controls (if necessary) to suit your form

These steps are discussed in detail below. Note that this functionality is available in the Professional Edition only.

frevvo Generated Schema

This schema will contain all the controls added to your form from the frevvo palette. This will not contain controls added to your form from your own schemas.

frevvo automatically generates an XSD schema representation of your form as you drop controls from the frevvo palette to the form designer canvas. You can download this XSD using the schema button on the forms home page. The XSD elements are named after the control names. The types are based on which control you selected from the palette. For example a Quantity control will appear as an xsd:integer. A dropdown will be an xsd:simpleType restriction. Controls with patterns such as the Zip will have an auto-generated type with your pattern. Etc... Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://www.frevvo.com/schemas/_pYKVwGqtEeCkdqfqF-QciA"
            xmlns:types="http://www.frevvo.com/types"
            targetNamespace="http://www.frevvo.com/schemas/_pYKVwGqtEeCkdqfqF-QciA">
   <xsd:import namespace="http://www.frevvo.com/types"
               schemaLocation="http://test.frevvo.com/frevvo/web/types.xsd"/>
   <xsd:element name="form">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:element minOccurs="0" name="CustomerInformation">
               <xsd:complexType>
                  <xsd:sequence>
                     <xsd:element minOccurs="0" name="Revenue" type="types:money"/>
                     <xsd:element minOccurs="0" name="Employees" type="xsd:integer"/>
                     <xsd:element minOccurs="0" name="LastDate" type="xsd:date"/>
                     <xsd:element name="CompanyName" type="xsd:string"/>
                     <xsd:element name="Zip" type="_qW_VpGqtEeCkdqfqF-QciA_type"/>
                     <xsd:element name="State">
                        <xsd:simpleType>
                           <xsd:restriction base="xsd:string">
                              <xsd:enumeration value="CT"/>
                              <xsd:enumeration value="MA"/>
                              <xsd:enumeration value="NY"/>
                           </xsd:restriction>
                        </xsd:simpleType>
                     </xsd:element>
                     <xsd:element minOccurs="0" name="Phone" type="types:phoneType"/>
                  </xsd:sequence>
               </xsd:complexType>
            </xsd:element>
         </xsd:sequence>
         <xsd:attribute name="name" type="xsd:string"/>
      </xsd:complexType>
   </xsd:element>
   <xsd:simpleType name="_qW_VpGqtEeCkdqfqF-QciA_type">
      <xsd:restriction base="xsd:string">
         <xsd:pattern value="\d{5}"/>
      </xsd:restriction>
   </xsd:simpleType>
</xsd:schema>

As of Live Forms v4.1.7 frevvo can add annotations that contain each control's display type and the actual user visible control label. To add annotations add the following parameter to frevvo's web.xml:

<context-param> 
    <param-name>frevvo.xsd.schema.annotation</param-name>
    <param-value>true</param-value>
</context-param>

This is what the Employees element looks like with annotations turned on:

<xsd:element minOccurs="0" name="Employees" type="xsd:integer">
  <xsd:annotation>
     <xsd:appinfo>
         <frevvo:displaytype xmlns:frevvo="http://www.frevvo.com/appinfo">
             Quantity</frevvo:displaytype>
         <frevvo:label xmlns:frevvo="http://www.frevvo.com/appinfo">
             Number of Employees working at this company?</frevvo:label>
     </xsd:appinfo>
  </xsd:annotation>
</xsd:element>

Using Your Schema

Before you can use global elements from a schema in a form, you must upload the schema XSD file into one of your frevvo applications.

To upload a schema:

1. From the Applications page, click the Edit icon underneath the name of the application with the forms that will use the schema.

2. Click Schemas from the left-hand menu

3. From the Schemas page, click the New icon

4. On the Upload Schema Page, type a meaningful name for your schema and provide a description. (These are optional but highly recommended.)

5. Click Browse, locate the schema XSD file on disk and click Upload.

If your schema is valid, its name now will appear on the Schemas page. If you tried to upload an invalid schema, frevvo will not allow the upload and display an error message.

Important notes about uploading schemas:

• You may add as many schemas as you require
• You may use global elements from uploaded schemas in any and all forms in the application
• If you want to use the same schema elements in multiple applications, upload the schema to each application separately.
• If your schema references another schema, you must upload the included schema before you upload the parent schema

Adding Schema Elements to a Form’s Data Sources

Once you’ve uploaded your schema, the next step is to choose the global elements you want for a particular form. The elements you choose will be displayed in the form’s Data Sources area on the lower left portion of the Forms Designer. You may add the elements to as many forms as you wish, but you must work with one form at a time.

To add the elements to a form’s Data Sources:

1. Open the form in the Forms Designer (by clicking the form name from the Forms Page).

2. In the Data Sources area on the left side of the Forms Designer, click New from XSD icon.

3. You’ll see all available schemas; click the plus sign to expand the schema folders and display the global elements from each.

4. Click the icon next to each global element you want. If the element is a complex type, you will see the parent element only, but the child elements will be added automatically to your form’s Data Sources. You may add as many elements as you like.

After you close the page, you’ll see in the Data Sources area each element you chose. (We added the Address Book and Policy Information global elements in this example.) For each element you added to your form’s Data Sources, frevvo will generate an XML instance document that you will see in the Submissions repository each time users submit your form, even if you do not end up generating a control from the element. Therefore, if you add an element to your form but later determine you don’t need to generate a control from it, make sure to delete the element from the form’s Data Sources.

Generating Controls from Schema Elements

Once the global elements are part of your form’s Data Sources you can generate controls for any or all of them. As shown below complex types are represented by a folder icon; simple types by a document icon.

To generate a group control that automatically includes controls for all of a parent element’s children, click the icon to the right of the complex type’s folder icon. The controls for the children elements will be inside a section control as shown below. If the complex type has repeating items, the section will be inside a repeat control.

To create individual controls for specific children of a complex type, click the icon to expand the complex type and click the icon next to each desired child element. For example, in the above example we could generate controls for First Name and Last Name but not for the phone number or email address.

Note that you do not drag the elements into your form; instead when you click the icon the generated controls are automatically added to the top of your form. You can then place the controls where you want them by following the normal drag and drop rules, with one additional restriction: you cannot drag any control into or out of a repeat control generated from a schema element. (If you need to do this, you will have to edit the schema.) Rearranging the controls will not affect the structure of the form’s XML submission documents or how submission data is captured.

Controls generated from schema elements will appear initially as text controls unless the schema specifies element restrictions. In this case, the control will be a dropdown if there are four or more valid choices and a radio button if there are fewer than four valid values. All validation for the controls will be based on the schema. See below.

Managing Controls Generated from Schema Elements

There are two ways to modify controls that you generated from schema elements. You can:

• Make changes to the controls in the Forms Designer
• Make changes to the schema, and then update the schema in frevvo by uploading the revised schema

Changes You Can Make in the Forms Designer

For controls generated from schema elements, you can make some but not all of the changes that you can for controls you drag in from the palette. Here are the changes you can make in the Forms Designer:

• Change the control Name — although this does not change the underlying XSD element name.
• Create rules that rely on the controls.
• Set default value for the controls.
• Rearrange the location of controls in your form. This includes moving sections into tabs or panels. As noted above, in addition to the normal drag and drop restrictions, you may not drag any control into or out of a repeat control generated from a schema element.
• Modify the control’s “Format As” property to change how the control looks on the form. This Format As property appears only for controls created from schema elements and appears instead of the Control Type property that you see for controls you have dragged in from the palette.
• Change the control’s label. You’ll see the new label name in the Submissions Repository Data Tab and in Excel if you download the submission results. However, the Submissions XML document for the schema will reflect the original element name.

Note that you cannot change a control’s validation behavior in the Forms Designer as you can for controls you drag in from the palette. You must do this by changing the schema. This is discussed below.

In general, the Forms Designer prevents you from making changes that will violate the integrity of the schema and cause issues when users submit your form. One exception is if you inadvertently generate two controls from the same element—in this case, users would see two controls on the form and could submit two different values, but the Submissions XML document would not be able to capture both values since the element exists only once in the schema.

You also must be careful when deleting elements from the Data Sources area, especially if you have previously created controls from these elements. This is discussed in detail below.

Changes You Cannot Make in the Forms Designer

One of the most important differences between controls generated from schema elements and controls you drag in from the palette is validation behavior. You’ll notice for example that you can’t check or uncheck the control’s Required checkbox in the Form Designer Properties area, nor can you access the control’s Pattern property.

Validation for controls you generate from schema elements is based on the element’s XSD type and other schema-specific information, such as whether the control is required based on the minOccurs value. If you generate a control from an element that is an integer and another from an element that is a string, the two controls initially will be generated as text controls but the first control will require users to enter integers and the second control will not.

You can see an element’s XSD type by clicking the control in your form and hovering over the Properties area of the Forms Designer--the XSD type will be displayed as a tooltip. The only way to change the validation for a control generated from a schema element is to revise the schema and update the schema in frevvo with the new version. The same is true for other changes you wish to make that you cannot accomplish in the Forms Designer.

You also cannot change the number of repeat items on the form. This is because the number is dictated by the minOccur in the schema. If minOccur=2 then there will by default be two repeat items displayed in the form designer, for example. Thus if you click the displayed in the form designer on a repeat from schema, it will display a message indicating that this operation is not permitted. To change the number of items on the form, edit the schema and change minOccurs.

Required Controls

The required property is disabled for controls from XSD. This is because validation is based on the XSD and currently cannot be overridden via the form designer or via business rules. This may be possible in a future release of Live Forms.

Whether the control is required is based on the minOccurs value. If minOccurs="0" then the control is not required. If minOccurs="1" then the control is required. If minOccurs is great than 1 then it will be rendered in the form as as a repeat control with the minimum number of items set to the minOccurs value.

If you want to change whether or not the controls is required, edit the XSD and update it in the schema's tab for that application.

There are times when you have several fields that you want hidden and then only want to make visible depending on the value entered into another field. Thus only when the fields are visible do you want them to be required. Currently hidden required fields are still required and will causes the submit button to remain disabled. Automatically making hidden fields not-required may be added in a future release of Live Forms.

Imagine a form asks if a student speak Spanish. If the answer is yes you want to make additional fields visible and required. But when the student doesn't speak Spanish the controls should remain hidden and not be required. Here is a solution for this use case:

1. For each control that needs to be required only when visible, edit the XSD and set minOccurs="1". The control must default to required in the XSD
2. Drag/Drop a Section control from the frevvo palette into the form
3. Uncheck the visible and required properties on the section control
4. Drag all of the from XSD controls that need to be required only when visible into the section control
5. Add a form.load rule that sets <section>.required=false. It is not enough to set the required checkbox in the section's properties panel. It must also be done in a form.load rule
6. Add a 2nd rule that sets <section>.required=true when you make the fields visible, with an else clause to hide the fields that clears all values from those hidden controls AND set <section>.required=false

Here is an example form.load rule where SpanishOnly is the name of the section control.

if (form.load) {
  SpanishOnly.required = false;
}

Here is an example show/hide rule where name and age are required fields only for Spanish speaking students.

if (spanish.value == 'yes') {
  SpanishOnly.required = true;
  SpanishOnly.visible = true;
}
else {
  // Must clear values in hidden fields
  // Must be done BEFORE setting <section>.required=false
  name.value = null;
  age.value = null;

  SpanishOnly.required = false;
  SpanishOnly.visible = false;
}

Updating a Schema

If you need to make changes beyond those allowed in the Forms Designer, make the changes in your XSD file and replace the old schema with the new one in frevvo.

To update a schema:

1. Click Schemas from the left-hand menu. (Remember, schemas are application-specific, so if you don’t see your schema, it may be in another application.)

2. You’ll see all a list of all uploaded schemas. Click the icon underneath the name of the schema you are updating.

3. On the Update Schema page, click Browse and locate the new XSD file. You may change the schema name and description but this is optional.

4. Click Update.

When you open (edit) any form that used the schema, the Data Sources area will be refreshed automatically. Do not delete the updated elements from the Data Sources area unless you are absolutely sure no controls in your form were generated from the elements in the previous version of the schema. Also, do not delete the elements and try to re-add them. This will cause any controls that relied on the schema to become unbounded and moved out of the schema XML document into the form's default XML document.

Adjusting Your Form after Updating the Schema

Although frevvo automatically refreshes the elements in the Data Sources area, this does not necessarily mean your form is up to date. You must edit your form, save it, and test it again to make sure the changes to the schema have produced the results you expected.

Depending on how you revised your schema, you may have to adjust the controls in your form. In most cases, you’ll need to delete the control from your form, and then re-generate a replacement control from the refreshed element in the Data Sources area. You’ll have to do this for the following schema changes:

• Changing the name of an element
• Changing an element’s type from a simple type to a complex type and vice versa.
• Moving a child element to a different parent
• Deleting an element
• Adding or removing data type restrictions
• Changing an element from non-repeating to repeating or vice versa
• Increasing maxOccurs from n to n+1 or more where n>0.

For example, if you add restrictions to limit the possible values in a dropdown control, you will not see the new values until you delete the old control and generate a new one.

The list above is not exhaustive. Generally speaking, the more extensive your schema changes are, the higher the likelihood that you will have to delete the original controls and generate new ones. (Obviously if your schema has changed drastically, you may want to consider creating entirely new forms instead of trying to edit the old ones.)

Some minor schema changes frevvo handles automatically and does not require you to replace the control in the form. For example:

• If you change an element from one simple type to another (e.g., a string to an integer), the corresponding control will change validation accordingly
• If you make an un-required element required by changing the minOccurs from 0 to 1, the corresponding control automatically will be required and marked with a red asterisk—and vice versa if you change the minOccurs from 1 to 0.

The Forms Designer alerts you to any controls for which the schema elements were deleted by displaying them with (placeholder: a brown border) after you have updated your schema. However, deleted elements are not the only reason a control can become unbounded from its corresponding schema element. Elements you update to make repeating are a good example—the “old” controls in your form will not be automatically updated to be a repeat control. You must delete the old control and generate a new one by clicking the icon next to the element name in the Data Sources area.

Although we do not recommend leaving unbounded controls in your form, you are not explicitly prevented from doing so. If you save your form with unbounded controls, data submitted in these controls will be included in the default XML Submission document for the form itself as opposed to being captured in the XML document for the schema.

Repeats

One exception is repeating elements. If you edit your schema and delete elements from within a repeating complex type, frevvo will automatically remove those deleted elements from your form. This is because a from schema repeating complex type is not allowed to contain any controls from the palette. Once the deleted elements automatically become unbound from the schema frevvo automatically deletes them from the form.

Also elements added to the form from the Data Source that are repeating elements are automatically added into the associated repeat control(s) if any already exist on your form. While all non-repeating controls are simply added to the top of the form when added from the Data Source.

Deleting Unused Data Source Elements

You do not have to generate a control from every element in the Data Sources area. The Submissions Data tab will show labels only for the controls on your form, and the Submissions XML document will capture only those data elements that users actually entered on your form.

However, keep in mind that a separate XML document is created for each global element you've added to your form, so if you don't need a global element, delete it from the form's Data Sources. Do this by clicking the icon next to the element's name. As the illustration below shows, you cannot delete child elements of a global element; you must delete the entire parent. If you have created controls for any child element, do not delete the global (parent) element.

Deleting a Schema

If you upload a schema you do not need, you can delete it. Choose Schemas from the left-hand menu and click the icon next to the name of the schema you wish to delete. (If you are working in the Forms Designer, you must finish or cancel your form to access frevvo's left-hand menu.)

If you choose to do this, be certain that none of your forms rely on elements from this schema. Any forms that use elements from the deleted elements will be adversely affected.

If you leave unused data sources in your form they are still part of your form's document even if you have removed all associated controls from the form designer canvas. You will see that xml documents are created for these unused schemas in form submissions and are visible in the doc action manually set doc Uris. If you do not want them there then delete them from the data source panel.

Unsupported Types

Schemas with repeating model groups are not yet supported. While repeating elements are supported, xsd constructs like the following currently are not. Do not use elements with repeating model groups in your forms.

<sequence minOccurs="2" maxOccurs="3"/>

Schemas choice groups are not yet supported. The 1st choice appear on the form as required even though only one is. Do not use elements of type Choice in your forms.

<xs:element name="promotion">
  <complexType>
    <choice>
       <element name="Discount" /> 
       <element name="None" />
     </choice>
   </complexType>

</xs:element>

Schemas with mixed content are not yet supported.

<xs:element name="letter">
  <xs:complexType mixed="true">
    <xs:sequence>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="orderid" type="xs:positiveInteger"/>
      <xs:element name="shipdate" type="xs:date"/>
    </xs:sequence>
    <xs:attribute name="type" type="xsd:string"/>
  </xs:complexType>
</xs:element>

If you are able to edit the schema, extract the text into new child elements.

Initialization from XML

Schema controls can be initialized from an xml document using the form's doc action and manually set document URIs. See the integration chapter with details on initializing forms with XML documents.