Migrator for Notes to SharePoint 6.16 - User Guide

Generating InfoPath forms (pre version 5.2)

Generating InfoPath forms (pre version 5.2)

 

NOTE: This is the pre 5.2, way of generating InfoPath forms. While this method is still supported for backward compatibility, a new, easier InfoPath form generation is now available. For more information, see Generating InfoPath forms (post version 5.2)

A common use for this feature is generation of InfoPath forms for use in SharePoint applications. Customers who are trying to replace existing Notes applications often build new InfoPath form templates that reproduce the dynamic behavior of their Notes form, such as hide-when formulas, computed fields and validation logic. These InfoPath form templates can be integrated in a variety of ways with SharePoint to create powerful document management, workflow and other compelling solutions. Migrator for Notes to SharePoint can rapidly migrate complex Notes documents to InfoPath forms for use with such solutions.

To generate XML documents

1

Add a column of type “Document” to your Notes Source Data Definition. The DocumentTemplate property of the column definition should be a complete XML document that contains all the declarations and tags you want in your generated documents. Users would typically create a sample document in their target application and use that as the starting point for their Document Template.

NOTE: Applications such as InfoPath can be very sensitive to the schema version and other metadata such as form template location (that is, the information expressed in the mso-infoPathSolution tag). A common best practice, therefore, is to first develop your InfoPath form template, publish to SharePoint, and fully verify the integrated solution. Then create your sample XML document in the context of your working SharePoint application and use that as the basis for creating a Document Template in Migrator for Notes to SharePoint.

2

Add a namespace declaration for ‘ppm’ to map to the namespace “http://schemas.proposion.com/PortalMigrator/V4”. You can then add special <ppm:replace> tags to specify the parts of your XML document that you want to replace with data extracted from Notes documents. The ‘src’ attribute of the <ppm:replace> should refer to another column in the same Notes Source data definition.

3

To generate repeating entries (an array) based on the values in a Notes multi-valued item, add the multi=‘repeat’ attribute to your <ppm:replace> tag. This will cause the surrounding XML tag to be repeated once for each input value encountered. You can also specify multi='repeatparent' to repeat the surrounding XML tag and its parent once for every value encountered in the multi-valued item. This option is useful for encoding multiple attachments (see below) or other repeating group elements in InfoPath.

To avoid generating tags when the Notes values are null, missing or empty strings, use the ifempty='remove' or ifempty='removeparent' attribute. This will cause the surrounding XML tag (or its parent) to only be generated if there is actual data in the source Notes item.

4	To generate rich text entries, add the encode=’xhtml’ attribute to your <ppm:replace> tag. This will cause the HTML markup extracted from your Notes documents to be saved into your generated document as XML tags rather than as plain text.

When using encode='xhtml' you can also add an 'images' attribute. This is similar to the 'src' attribute in that it should be the name of another source data definition column. The images are encoded right into the XHTML and you go not need to migrate them separately.

When using encode='xhtml' any Notes DocLink icons that are encountered are converted to encoded icons in your XML document. To disable this behavior, add the attribute linkicons=’false’ to your <ppm:replace> tag.  This will cause Notes DocLink icons to be replaced with a simple text link instead.

Other possibilities for the encode attribute are 'commonname' and 'abbreviatedname' for formatting Notes names and 'datetime', 'dateonly' and 'timeonly' for formatting XML Date/Time values.

If you wish the source data column to copied “as is” into the XML document, you can use encode=’xml’ rather than encode=’xhtml’. This might be useful if, for example, you have a Notes item that contains pure XML or you have created a formula column in your source data definition that emits an XML fragment. If you omit the encode attribute completely, the source data will be encoded as a Text element by default and any special characters (such as XML angle brackets) will be escaped.

To encode your attachment as an InfoPath attachment (using InfoPath’s proprietary format), add the encode=‘attachment’ attribute to your <ppm:replace> tag. To encode your attachment using standard base64 encoding, add the encode=‘base64’ attribute to your <ppm:replace> tag. This later choice is useful in some XML applications, but not for InfoPath.

To substitute target information in your XML, use the tag, <ppm:replace target=’site’>. Currently, the only supported value is “site” which yields the complete site URL.

 

NOTE: To make sure InfoPath attachments display properly, include the <?mso-infoPath-file-attachment-present?> processing instruction at the top of the document.

 

NOTE: While this release only implements the <ppm:replace> tag, more advanced tags and attributes are planned for subsequent releases. As a workaround to most limitations you might encounter, consider using Formula columns to create XML fragments.

 

NOTE: In this release, a simple drop-down text editor is available for entering multi-line Document Templates. In practice, many users would prefer to use their favorite XML editor and copy/paste the results in Migrator for Notes to SharePoint. A more powerful editor/designer is planned for future releases which will assist with loading a sample XML document, merging source columns, generating PPM tags.

5

To save your generated XML documents into a Document Library or Forms Library in SharePoint, simply map your new “Document” column to a File field in SharePoint, just as you would when extracting attachments or embedded images. You can also map Document columns to List Item text fields or List Item attachment fields.

You can control the name of generated XML files by mapping a dynamic source column to a FileName field in your target data definition.

Generating InfoPath forms (post version 5.2)

Generating InfoPath forms (post version 5.2)

To generate InfoPath form documents from Lotus Notes documents that were created using Notes forms

1	Create an InfoPath form template from the Notes form. Migrator for Notes to SharePoint can do this automatically for you. See Generate InfoPath Form Template for detailed instructions on how to do this. You can also start with your company's existing InfoPath form template.

2	Use the InfoPath client itself to publish the form template to SharePoint. You do this using the InfoPath client's File/Publish… menu option. For more information, see your InfoPath help guide.

3

Copy the published form template from the SharePoint document library to your local drive. This template is what you will use in your Migrator for Notes to SharePoint migration job definition. If the template is the default template for the document library, you can copy it by changing the “Allitems.aspx” in the URL of the document library to “template.xsn”.

4	Save it from the pop-up that appears. Be sure to turn of your Pop-up Blocker before doing this. If the template is not your default, you can copy it by going to the Form Library Advanced Settings page.

5	Once you have the form template (.xsn file), you can then add it to the Migrator for Notes to SharePoint migration job using the Target Data Definition.

 

NOTE: You cannot use the template that was generated from the InfoPath Form Template generation tool. You must use the copy of the template that was published to the document library in your Migrator for Notes to SharePoint migration job.

6	In the Target Data Definition, add a target column of type InfoPathDocument. You must also specify a column Name (which is used in the field mapping process).

7	Specifying a Template is required for InfoPath documents. To specify a template, click the InfoPath Template property and click the Details button to launch the Map InfoPath template fields dialog.

8	In the Map InfoPath template fields dialog, import an InfoPath template (.xsn file) using the ‘Load XSN’ link. A complete copy of the imported template will be saved as part of your Target Data Definition and will be used as the basis for any documents that you generate with it.

With some form templates, the XSN importer cannot determine what the HREF (location of template) should be for a generated document. For instance, if a template was imported into Central Admin, approved by an administrator, then assigned to a site, where SharePoint automatically created a content type for it. In this case, the published XSN location is not in the XSN. For these unusual cases, you need to specify the template location in the Published XSN location field. This field will be automatically loaded with the location if the XSN importer can determine the HREF.

Once an XSN has been loaded using the ‘Load XSN’ link, the ‘Export XSN’ link is enabled. Clicking ‘Export XSN’ launches a file save dialog box, allowing you to save the previously-imported XSN back to a file on disk.

The Map InfoPath template fields dialog also includes a complete list of the available Mappable Fields, which are the parts of the generated InfoPath form documents that you might want to map Notes data to. If desired, you can customize how these Mappable Fields appear on the Mapping tab. Recall that Migrator for Notes to SharePoint maintains the distinction between the reusable Target Data Definitions that describe the schema of your SharePoint targets and the mapping of source columns to target fields in a specific migration job. You can clear certain Mappable Fields that you do not want to show on the Mapping tab. You can also override some of the Mappable Field properties such as the MappableName that is visible on the Mapping tab and the AutomapNames property that provides a hint as to which Notes source columns should automatically map to the target field.

If you import a form template (.xsn) with two leaf nodes having the same name, the MappableNames fields are pre-filled with a fully-qualified path to the node in the tree (that is, Customers/Customer/name). This prevents duplicates in the target documents.

If a field is inside a field that is repeating, it's Multi property will be auto-set to ‘RepeatParent’. All sibling fields must have this property set to ‘RepeatParent’. This prevents the parent element from being repeated in the generated XML.

You may wish to enable the "Migrate Attachment Icons" feature in your migrated InfoPath form documents. This will allow the original attachments icons in Notes to appear in SharePoint.

Once you save your Target Data Definition, the various parts of the InfoPath Document field you defined will be available on the Mapping tab. A special "Field.Part" notation is used here. In the example, we called the InfoPathDocument field "Doc" so the mappable parts are called "Doc.Body", "Doc.Title", "Doc.Status" and so on. There is also a special field called "Doc.FileName" that allows you to set the names of the generated InfoPath files from dynamic Notes data

When you run the job, Migrator for Notes to SharePoint will generate one InfoPath form document for each Notes document. You can inspect the migration log for any issues.

Generating raw HTML and XML

Generating raw HTML and XML

When using Migrator for Notes to SharePoint to migrate Notes rich text documents to SharePoint, the tool extracts your rich text "Body" item as HTML and map that to a SharePoint "Note" field (a multi-line text field supporting Enhanced HTML).

If you want to control how your HTML is encoded, Migrator for Notes to SharePoint supports the use of "pass through" HTML. If you want a string in your source data definition to be interpreted as pure HTML, set the Return Type to “HtmlString". For example, some custom Notes applications, especially web-enabled Domino applications, actually store raw HTML in text fields. Using the HtmlString return type can migrate those to SharePoint rich text fields "as is".

This is similar to the capability available when generating InfoPath XML documents from Notes documents. You can use the attribute encode="xml" inside your <ppm:replace> tags to indicate that you want the mapped source column to be treated as "pass through" XML.

Generating read-only HTML

Generating read-only HTML

When using Migrator for Notes to SharePoint to render Notes documents as HTML, the Notes fields for radio buttons and check boxes become editable in the output since the generated HTML documents are not read-only. To disable editing of radio buttons and check boxes, set the HTML output to read-only.

To generate read-only HTML:

•	Set the render Return Type to HTML.

•	Map it to a target field with the type File.

•	Set the Read-only field to True.