WFFM Conversion Tool
The WFFM Conversion Tool is a console application that provides an automated solution to convert and migrate Sitecore Web Forms For Marketers (WFFM) forms items and their data to Sitecore Forms.
The tool provides the ability to analyze the source items in the source Sitecore instance, before executing the actual conversion and migration of items to the destination Sitecore instance.
The tool offers the users the choice to migrate saved WFFM forms data from a SQL database or from a MongoDB database source to the destination Sitecore Experience Forms SQL database.
The tool has been designed to support the migration of sitecore items from any version of Sitecore to Sitecore 9.1+. The tool has been tested migrating WFFM forms items and data starting from Sitecore version 6.5.
- .NET Framework 4.7.1+
- Windows OS
- No particular hardware requirement
How to Install the Tool
The tool is distributed in a ZIP archive. The latest release can be downloaded here: https://github.com/afaniuolo/WFFM-Conversion-Tool/releases/latest.
The tool can be installed in any server or local machine that has access to the databases involved in the conversion and migration process. The tool doesn't require the source and destination Sitecore instances to run in IIS while the conversion process occurs, because the tool connects directly to the Sitecore databases, without using Sitecore APIs or other Sitecore modules.
- Download the latest release of the tool.
- Extract the ZIP archive in a folder on the machine where the tool will be executed.
- Assign read-write permissions to the folder and its subitems for the user that will execute the tool.
How to Configure the Tool
The tool needs to be configured before using it. The following steps describe the configuration options.
WFFM.ConversionTool.exe.configfile and populate the following connection strings:
SourceMasterDb- The connection string to the source Sitecore Master database.
DestMasterDb- The connection string to the destination Sitecore Master database.
SitecoreForms- The connection string to the destination Sitecore Experience Forms database.
WFFM- The connection string to the source Sitecore WFFM database (if applicable).
mongodb_analytics- The connection string to the source Sitecore Analytics MongoDB database (if applicable)
NOTE: Only one between the WFFM and the mongodb_analytics connection string is required, and it depends on the type of data source used in the source Sitecore instance to save WFFM forms data.
AppSettings.jsonfile and modify the following settings, if needed:
formsDataProvider- This setting is used to configure the data provider used to read the stored forms data to migrate. Available values:
sqlFormsDataProvider- Used to select the SQL Sitecore WFFM database source (default value).
analyticsFormsDataProvider- Used to select the MongoDB Analytics database source.
invalidItemNameChars- This settings is used to configure the list of invalid characters to be excluded when creating a new item's name.
enableReferencedItemCheck- This setting is used to enable or disable the check existence of a referenced item in any form fields value. When enabled, the tool will not populate fields that refers an item that doesn't exist in the destination Sitecore master database.
analysis_ExcludeBaseStandardFields- This setting is used to exclude base standard fields of Sitecore items from the list of fields that are reported about in the conversion analysis report output. The exclusion of the base standard fields from the analysis reporting process doesn't exclude them from the conversion process.
How to Use the Tool
The tool should be executed in a Command Prompt window application in order to control its input parameters and visualize the execution progress.
In the context of a Sitecore upgrade project, if all Sitecore content items have already been migrated to the destination Sitecore master database (for example using the Sitecore Express Migration tool), then the WFFM forms content items should be deleted from the destination Sitecore instance before running the WFFM Conversion Tool.
- Launch a Command Prompt window application.
- Browse to the root folder where the tool has been extracted to.
- The tool is executed running the
WFFM.ConversionTool.exeexecutable file. Available options are:
WFFM.ConversionTool.exe(no input parameters) - Use this option to execute a dry run of the forms item conversion process, without writing any data in the destination databases. The conversion analysis report will be generated and stored in the
WFFM.ConversionTool.exe ?- Use this option to get a list of available input parameters.
WFFM.ConversionTool.exe -convert- Use this option to execute the conversion and migration of both forms items and their stored data to the destination databases.
WFFM.ConversionTool.exe -convert -nodata- Use this option to execute the conversion and migration of forms items only. Stored forms data will not be converted and migrated.
- After the tool execution is finished successfully, if the destination Sitecore instance was running in IIS while the tool was executed, recycle the app pool of the destination Sitecore web application to clear the Sitecore Items cache.
- Once you login in the destination Sitecore instance, the migrated forms will not be listed in the Forms section (accessible from the Sitecore Desktop) until the
sitecore_master_indexindex is rebuilt. Use the Indexing Manager in the Sitecore Control Panel to rebuild it.
NOTE: The conversion analysis report is always generated, independently if it is a dry run or a real conversion being executed.
The tool enforces some specific behaviors during the conversion process, following best practices. Some of them are:
- Page Creation - For each form, the tool creates a new Page item under the parent Form item.
- Text Fields Creation - Any decorator fields, like for example the form title, the form introduction or the form footer, are converted in Text fields and positioned in the form in the correct location.
- Success Message Creation in Second Page - For each form that shows a success message when a submit action is successful, the tool creates a second Page item with a Text field that contains the success message. The full approach has been implemented following the answer in this Sitecore StackExchange question.
The tool uses mapping configuration rules for each destination form item entity (form, fields, buttons, text,...) to control the conversion of form items and their fields. These mapping rules are defined and stored in Metadata Template files in JSON format, all stored under the
Metadata folder. All Metadata Template files are validated using the
metadata-schema.json file stored in the
Metadata Template objects can inherit some properties from other metadata files, avoiding the repetition of mapping rules across multiple Metadata Template objects. The base metadata file that doesn't inherit from any other metadata file is the
baseTemplate.json metadata file.
The valid properties available in the Metadata Template files are the following:
sourceTemplateId- Template Id of the source item.
sourceTemplateName- Template Name of the source item.
destTemplateId- Template Id of the destination item.
destTemplateName- Template Name of the destination item.
baseTemplateMetadataFileName- Filename of the inherited base Metadata Template.
sourceMappingFieldId- Id of the field of the source item used to map the Form Field type (applicable to field items only).
sourceMappingFieldValue- Value of the field of the source item used to map the Form Field type (applicable to field items only).
dataValueType- Value type of the data stored for a particular form field type. The value type is stored in the records of the
FieldDatatable of the Sitecore Experience Forms destination database.
dataValueConverter- Name of converter used to convert the data value of a particular form field type. All converters are defined in the
AppSettings.jsonconfiguration file and referred by name.
fields- This properties contains the conversion mappings for the fields of a specific item. The fields are organized in three categories:
newFields- Array of fields that don't exist in the source Sitecore item, but are required in the Sitecore destination item. Each newField object can have the following properties:
fieldType- Type of Sitecore field (shared, versioned, unversioned).
destFieldId- Id of the field of the destination Sitecore item.
value- Default value to assign to the new field when created.
valueType- Used to create a dynamic value of a specific type for the new field.
existingFields- Array of fields that exist in both the source Sitecore item and the destination Sitecore item and that don't require any convertion. These are Sitecore base fields, usually named using a double underscore (
fieldId- Id of the existing field to migrate.
convertedField- Array of fields of the source Sitecore item that are converted and mapped to different fields in the destination Sitecore item.
fieldConverter- Name of the converter used to convert the value of the source field.
sourceFieldId- Id of the field of the source Sitecore item.
destFieldId- Id of the field of the destination Sitecore item.
destFields- Array of destinaton fields used to map values stored in a single source field that are converted in multiple different destination fields. The values in the source field are organized in a pseudo XML document object. Each destField object can have the following properties:
sourceElementName- The name of the XML element stored in the source field value.
destFieldId- Id of the field of the destination Sitecore item.
fieldConverter- Name of the converter used to convert the value of the XML element.
Analysis Conversion Report
WFFM form items and Sitecore Forms items are very different and even if the tool is capable of converting most of the entites, there are some item fields that cannot be converted and migrated. The analysis conversion report is a report in CSV format generated by the tool, that lists the Sitecore item fields that the tool cannot convert, because they are not mapped or not supported.
The analysis convertion report contains the following columns for each record:
ItemId- Id of the source item.
ItemName- Name of the source item.
ItemPath- Path of the source item.
ItemVersion- Version of the source item.
ItemLanguage- Language of the source item.
ItemTemplateId- Template Id of the source item.
ItemTemplateName- Template Name of the source item.
FieldId- Id of the field of the souce item.
FieldName- Name of the field of the source item.
FieldType- Type of the field of the source item.
FieldValueElementName- Name of the XML element stored in the field of the source item.
FieldValueReferencedItemId- Id of the item referenced as value of the XML value element.
FieldValueReferencedItemName- Name of the item referenced as value of the XML value element.
Message- Analysis result message. Possible values are:
- Source Field Not Mapped - The source field is not mapped in the Metadata Template file or a conversion for that particular field is not possible.
- Form Save Action Not Mapped - The form save action is not mapped.
- Source Field Element Value Not Mapped - The source field XML element value is not mapped.
- Form Field Item Not Mapped - Form Field Type Name = field-type-name - The form field type is not mapped, because the field is a custom field type. Form fields that are not mapped are still migrated and converted using the default destination Input form field type.
How to Expand the WFFM Conversion Tool to Convert Custom Entities
Some of the items or fields that cannot be mapped could be custom items created to expand the out-of-the-box functionality of the Sitecore WFFM module. For example, custom entities could be custom form field types or custom save actions. To help developers to automate the conversion and migration of custom entities, the tool allows to expand its default mapping capabilities, as described in the next three sections.
How to Map a Custom Form Field Type
Any metadata .json file stored under the
Metadata folder is parsed and validated by the tool when its execution starts. A custom form field type will requires its own Metadata Template file to describe its conversion fields mappings.
Usually custom field types are customization of a default WFFM form field type. The customization adds additional parameters in the Parameters field or in the Localized Parameters field of the form field item. An easy way to create a new metadata file for the custom form field is copying the metadata file of the default WFFM form field type that the custom form field is based on and modifying its properties.
baseTemplateMetadataFileName property should contain the name of the metadata file of the inherited default WFFM form field type.
How to Customize the Conversion of a Field Value
The fieldConverter property of convertedField mapping objects in metadata files allows to specify the name of a converter to process the source value of a field. Converters are defined in the
AppSettings.json configuratio file in the converters property. This property is an array of converter objects that have the following properties:
name- Name of the converter, used as value in the fieldConverter property in metadata files.
converterType- Type of the class object that defines the converter.
The tool allows the loading of converter types defined in external libraries at runtime. The converter class needs to be created inheriting the
BaseFieldConverted class defined in the
WFFM.ConversionTool.Library.dll (that should be referenced in the custom class library project), and overriding the
ConvertValue method. This method takes a string as input and return a string. The base method just returns the input, without applying any conversion.
The new custom converter will need to be added in the list of converters in the
AppSettings.json configuration file. Its library dll file should be copied in the
libs folder of the tool.
How to Map a Custom Submit Action
Custom submit actions can be defined and mapped in the
AppSettings.json file in the
submitActions property. This property contains an array of
submitAction objects, that have the following properties:
sourceSaveActionId- The Id of the source save action item.
destSubmitActionItemName- The name of the destination submit action item.
destSubmitActionFieldValue- The value to store in the destination Submit Action field value.
destParametersConverterType- The name of the field converter to use to convert the save action parameters.
The custom field converter should be created as described in the previous section, overriding the
ConvertValue method defined in the inherited
Bugs and Feature Requests
Please open new Issue here to report any bug that you might encounter in the execution of the tool or to suggest a modification or a new feature for the tool.