Migrator for Notes to SharePoint 7.1 - User Guide

Migrating to SharePoint publishing pages

Many Notes applications were designed primarily to publish rich content to a wide audience. These often included some type of approval process, management of draft content, and version control. These are great examples of applications that may well to the “publishing” site templates available in SharePoint Server 2013/2016/2019. Here, for example, is a rich text Notes document (with embedded images, attachments and doc links) that has been migrated to a 2010 “Publishing Portal” using Migrator for Notes to SharePoint.

Figure 10. Document that has been migrated using Migrator for Notes to SharePoint

If we put this page into edit mode, we can see that a great deal of out-of the-box functionality is available with no development required.

Figure 11. Document that has been migrated using Migrator for Notes to SharePoint

Migrator for Notes to SharePoint supports migrating any Notes content to publishing pages. This is a little more complex than doing other wiki pages or basic pages and uses the tool’s unique capability to create pages using custom ASPX template code.

If you do not already have a publishing site, create one using SharePoint Central Administration and specify one of the “Publishing” templates

Next, you need to create a “template” for generating pages from your Notes documents. Go to your new SharePoint publishing site and create a sample page by selecting Create Page from the Site Actions menu.t

Select the page layout you want for your new pages. The list of layouts may vary depending on the site template you started with and may include custom layouts designed by your site owners. Populate the page with a little sample data and save it.

Feel free to experiment with checking the page in and out, versioning it, scheduling it’s release or submitting it for approval. These are all powerful features of the SharePoint publishing templates, but you actually do not need to use them for the task at hand.

For designing a migration job, you need to extract the page to a local file so you can get an example of the ASPX layout. Select View All Site Content from the Site Actions menu and then go to the “Pages” document library.

In the Pages library, locate the test page you just created and pick Send To –> Download a Copy from the drop down menu for that page. y

Save the ASPX file to your computer and edit in any text editor. Keep this ASPX file handy, because you will be using it later.

Digression: ASPX developer’s may be interested in how this page is constructed. It inherits from a class in the Microsoft.SharePoint.Publishing namespace, but does not actually specify any HTML markup. Instead the code behind the pages uses the data in an XML data island to render the page. Notice that the XML parts specify not only content properties such as PublishingPageContent but also the page layout in the PublishingPageLayout property.

Now you have what you need to create your Migrator for Notes to SharePoint migration job. You can start from scratch or customize an existing job.

If you are starting with an existing job, first change the source Notes database to refer to your database and you may need to customize the source data definition to extract different Notes data items than the default ones specified (“Subject”, “Body”).

You should also change and target SharePoint URL to point to your publishing site. The pre-existing jobs are already configured to create new pages in the “Pages” library, place any embedded objects in the “Images” library, and place any attachments or embedded objects in the “Documents” library. This is consistent with the way things work normally when a SharePoint user created content in a publishing site, so you probably do not need to change those parts.

If you open the target data definition in the migration job, you will notice that there is a target field of type ‘PageName’ and that the PageType property of this field is set to “Template”. This PageType allows you to specify your own custom ASPX code in the PageTemplate field.

The ASPX code is what needs to be put into the PageTemplate field. Not all of it though, just the bits that describe the page structure. The content parts can be left out and, as you will see shortly, we will specify the content in a different way (mapping the data dynamically from Notes). Your ASPX page may look different, but generally you want the ASPX tags at the top (which start with “<%@”) and the <html> tag.

Notice that the target data definition also specifies several fields that allow data to be mapped as content in the generated pages. Some of these you may recognize as the properties that were specified in the XML data island (the green part). We included PublishingPageContent for mapping the Notes rich text and PublishingPageLayout for specifying the page layout. Other page types may require additional properties but you will find that many of them can be omitted as the defaults are acceptable for migrations. Title and ApprovalCode allow setting of metadata on the page. ExternalImages and ExternalAttachments allow mapping of additional files to the appropriate SharePoint libraries.

Press OK to save the target data definition. Next, go to the Mapping tab to review how various fields are set from the dynamic Notes data. Most of these mappings will make sense to an experienced Migrator for Notes to SharePoint user, but two deserve special attention.

The PublishingPageLayout is set to a constant value, which is the URL of the appropriate layout page. It is critical that you replace this value with the address of a layout page on your SharePoint server. Recall that in the newly created test page in the example, the page layout “Article page with body only” was selected. In the resulting ASPX file, this translated to the PublishingPageLayout property in the XML data island (the green bit) set to “http://quest-e52a78ada/sites/publishing/_catalogs/masterpage/PageFromDocLayout.aspx”. This is the URL that you need to use here. If you do not get this part right, your pages will not open.

Figure 12. Replacing source value with address of a layout page on your SharePoint server

The jobs are also designed to set any migrated content to the “Approved” state. This is accomplished by mapping a constant value to the ApprovalCode field. Of course you can change this to a different constant value or even make it dynamic depending on the state of your Notes document.

Depending on the page layout you selected, you may need to map other properties as well. When you are ready, press the Run Job button to start the migration.

Migration jobs

Running migration jobs

When you are ready to run your migration job, select Run. You can do this by selecting the Run toolbar menu or by clicking the Run button at the bottom of the Designer or the Migration Jobs tab of the Console’s Database Properties dialog box. This button is a split function button. If you click the left side of the button, the entire migration job will run. The right side of the button is a drop down menu that allows you to run portions of the job like provisioning.

Figure 13. Run provisioning only

If you have access to both SharePoint and Notes on your machine, or if you are connected to a remote SharePoint server running Migrator for Notes to SharePoint's Import Service, you can run a complete data migration job all at once. Otherwise, you need to export the intermediate results to an XML file from Notes and then import intermediate results from an XML file into SharePoint. The following is an example of how you might use the export/import:

If you choose to use an intermediate data transfer file, you should also save the matching Job Definition. See Managing migration jobs for more details.

From the Console, you can select multiple databases, right-click, and select Migrate to SharePoint.

To view detail information regarding the jobs before you run them, click the Details link.

If you choose Save to Intermediate File, a dialog comes up that gives you an option to have the attachments saved to a separate folder rather than the default of the intermediate data file.

There are a couple of benefits to saving the attachments in a separate folder:

When you choose to save attachments and generated documents to a separate folder, Migrator for Notes to SharePoint uses the correct file names wherever possible when the attachments and generated documents (but not images) are saved to the file system.

The name of this separate folder is derived from the name of the intermediate data file with "_Files" appended. The name or location of this shared folder cannot be changed. You can move the intermediate file and its corresponding folder, but you cannot rename them, and they must remain in the same relative location to each other (that is, When reading "journal.xml" we expect that the "journal_Files" folder will be in the same directory as "journal.xml").

You should see your progress displayed in a task process dialog box. If you are using the Console and chose to run the job in the background, you can find the task process dialog box in the Task history node of the tree.

To cancel the migration, click Cancel Task or close the dialog box.

When your job is complete, you will have the opportunity to view your log file or go directly to the SharePoint list or library by clicking Go to List. To migrate the failed items for a job that completed with error, click Migrate Failed Items. For more information, see Migrating failed items.

Migrating failed items

You can load the failed items from the log file after changing the relevant settings, and migrate them again.