Database Configuration

MySQL database encoding utf8_general_ci

 v5 requires utf8_unicode_ci encoding. MySQL supports two types of utf8 encoding: general and unicode. If your  database is utf8_general_ci you must first switch the databases to utf8_unicode_ci and then proceed with the normal  migration instructions.

Business Rules

Rules in v4 forms may show validation errors after the migration to v5. It is recommended that you correct these errors but, if you do not, the rules in the upgraded forms will still work without the corrections. Refer to the Rules Validator documentation for more information.

Custom Themes

The v4 global themes called Clear and Professional Blue have been replaced by Nouveau and Nouveau Blue. Custom themes created in v4 require manual migration in order to use them in v5.

This manual migration is not difficult but will take advance planning on your part. You need to create new custom themes based on the new v5 global themes Nouveau or Nouveau Blue. Refer to Basic Steps for working with Themes for basic information on working with themes. Follow these upgrade steps:

1. Download & Unzip your existing v4 based themes from your designer accounts.
2. Download & Unzip one of the new v5 Global Themes: Nouveau or Nouveau Blue as the starting point for your upgraded v5 theme.
3. Open the v4 theme's form.css (or any other file where you had added the CSS customizations)
4. Open the v5 theme's common.css file. This is the recommended place for all your customizations. We highly recommend that you put all your custom css into the v5 theme file called common.css. This will make future migrations easier.
5. Copy your v4 css change into the v5 theme's common.css file.
6. Copy any custom JavaScript added to custom.js in your v4 theme into the custom.js file in your new v5 theme.
7. Zip the contents (not the entire folder) of your new theme directory to create your new v5 Custom theme.
8. Edit and replace the existing v4 Custom theme with your new v5 Custom theme.
9. Test that the new v5 custom themes applied to your forms look as expected.

Also see the migration considerations Styling Considerations topic below.

Spaces

A theme applied to a Space in v5, is propagated to all the forms in that space. If you want to use a different theme for a particular form or flow, you must override it by using the URL parameter, _themeId. You can use either syntax: themeId or themeId!userId!tenantId = "Name of Theme". For Example:  

http://demo4.frevvo.com:8082/frevvo/web/tn/{tn.id}/user/designer/app/_N4cF4ZuwEeCwk5wyBHqHrQ/flowtype/_BRD_MHxkEeKJS-B6PtnIKQ?_method=post&embed=true&_themeId=Nouveau

In  v4 the space theme did not override the form's theme.

Form Designer

Format As

The control property "format as" on controls from XSD schema has been renamed to "display as". The behavior is the same. Only the property name has changed.

Required Controls from XSD

The  v4 documentation described a work-around for Required Controls from XSD Data Source. This is a non standard approach to solving an issue that should be solved in the underlying XSD data source.  v5 contains many enhancements for creating forms from XSD data source and has standardized XSD support. This non standard use described in the v4 documentation is no longer supported.

Styling Considerations

Option Width

The v5 default font has changed. has identified the following areas that should be checked and adjusted manually by the designer, if necessary.

1. Places where you may have used the Option Width property to enable Multi-Line Options, may need to be adjusted
2. The new font may cause long labels to consume just enough additional width that it causes a carriage return and thus unwanted space between the label and the input control

Grid Layouts with Blank Message Controls

In this example the form needed labels in the first grid column. When styling grid layouts with panel controls this required the form designer to add a blank message control to any row that did not need a label. In the example below the 2nd row did not need a label.

This technique required he designer to enter something into the message control's Message property as shown below:

When this form is migrated to v5 it will continue to look correct in use mode but will not look correct in print view. Here is how the form looks printed to a PDF in the submission repository in v4 compared to v5.

You can solve this either by replacing the panel grid with a new table control or by changing the content of the message control from <div style="text-align: right"/> to <br/>.

Tab Control

Styles using em to set the width

Styles that used the HTML tag, em,  to set a width will be larger in v5 then in v4 due to the fact that the default font size is now larger. Em is based on the font size. So 10em for example in a larger font will take up more width then 10em on a smaller font. This will effect the space used by all labels where the designer used em. For example, trigger controls will start taking up more width.

You can go back to your form and reduce the <n>em

Controls in Panels with 100% width

In previous versions of , panels + a custom theme were used for grid layouts. Forms containing panels with controls that have the width set to 100% will overlap each other when the form is migrated to v5. In v4.x, the controls were sharp rectangles so the display looked as though the controls were placed one after the other.

The rounded rectangles in v5.1.1 make this overlapping behavior evident. Also the date control drops slightly downward. This causes a usability issue when data is entered into the field. If the user max fills the field, the last character will be partially hidden from view. 

Length of Asset Names

If  any of your 4.1.7+ forms/flows have assets that resolves to a resources path longer than 250 chars, edit the the forms/flows manually and re-add the image using a shorter name before performing the migration.

Here is an example of a resource path in a 4.1.7 application that would cause a problem:

/users/m/a/_zkO1MZ0EEeKyQOS3UVoZ4w/_6mXo8J0JEeKyQOS3UVoZ4w/_7QPsYp0JEeKyQOS3UVoZ4w/assets/_p6rSQZ0KEeKyQOS3UVoZ4w_IOExceptionInReplicationWorkerUnableToDrainChannel_ProbableCauseKeepAliveSocketClosedAnEstablishedConnectionWasAbortedByTheSoftwareInYourHostMachine_.png

Change to Form Name Attribute in Submisson XML

There is a change in the form submission XML in  v5.1.1 in terms of the form name. The submission xml, in previous versions, included the name attribute in the root element. Here is an example of the submisson xml for a form named MyTestForm in v4x:

<ns:form xmlns:ns="http://www.frevvo.com/schemas/_cUipsAwZEeOBRuTQ9KKS8w" name="MyTestForm">
  <FirstName>Tom</FirstName>
</ns:form> 

The name attribute has been removed in version 5. One way to add a specific attribute to the root element of the XML, is to enter a unique value in the element name property field on the form properties panel in the  designer. 

The value in the Element Name field will reflect in the root element of the form’s submission XML. Here is an example of submisson xml for a form that has My Test Form as a value in the Element Name field in v5.1.1:

<p0:MyTestForm xmlns:p0="http://www.frevvo.com/schemas/_r3Pq8AwLEeOZFu_wpeK3Ag">
  <FirstName>Tom</FirstName>
</p0:MyTestForm>

If you see this error message, when using a flow, the Element Name field on the Flow Properties Panel is most likely empty. You must edit your form/flow, explicitly set the flow 'Element name' in the properties panel back to the default value 'form' or to the value that was set to before. This value must match what is in your database or loading the flow from an old submission will not work. The error in the image occurred when the manager tried to access a task from the Task List in a flow with an empty element name field:

If you have been using the name attribute in v4 forms, it will not be available when creating v5 forms post-migration. Code which uses the submission xml in your integrations will need to be modified to use the root element name instead of the name attribute in the root element.

Internationalization

New Strings in Default Locale Properties File

There are new strings present in the default locale properties file for forms/flows in v5. For example.: strings for mobile devices. You will need to manually add these new strings to your uploaded locale files for forms created in v4. New strings can be found by downloading the v5 default properties file for your form. Server wide customizations can be done by unzipping the <frevvo-home>/tomcat/webapps/frevvo.war. See this documentation for the details.

Data API

The browser doc feature in  v4 is no longer supported. It introduced a new doc action that can be enabled by the API and where, on submission, the XML document would be sent back to the browser with the HTTP response. This enabled the capture of updated XML and make sure it updated their own systems in a single db transaction.

 In 5.x, we have a new mechanism. It is possible now to submit forms using the API and receive back a DataSource? with multiple parts (multipart/form-data) one for each submission document: XML, snapshot, attachments, etc. This is above and beyond what the browser docs provide, but much simpler. See API's submitInstance() and Data Source documentation (coming soon...). 

Time and Date/Time Control Initialization in a form.load Rule

Rules initializing Time and Date/Time controls will not work in a form.load rule unless you specify a timezone on the form's Url via the _formTz Url parameter. This is because the form server needs to know the timezone in which to return the date and time. If you do not specify a _formTz the methods will return null and the control values will remain blank. Timezone strings you can use in the parameter can be found here. For example, to specify Eastern time append &_formTz=America/NewYork to the form Url. This parameter is not needed if your form/flow only contains date controls.

Date Controls in a Migrated Flow

If you see a lightbox with the message "initializing form" and it never goes away when using a migrated flow that contains Date controls, edit the flow, then edit each activity and simply click "finish" (no changes needed). Finish the flow. This updates the formtype files and the flow will work properly in the updated version of .