Notes SharePoint Blog

Notes Migrator for SharePoint has allowed for migration to SharePoint wiki pages for over a year now.  Wiki pages were of mild interest in SharePoint 2007, but as described in my last post they have evolved into an awesome target choice in SharePoint 2010.  For example, you may have noticed that the Site Pages library in many of the new 2010 site templates is now a Wiki library.

The following steps recap the basic steps and some of the advanced options for migrating Notes documents to Wiki pages.  These steps apply equally well for SharePoint 2007 or SharePoint 2010 (but SharePoint 2010 requires the use of Notes Migrator for SharePoint 5.3.1 or higher).

Basic Steps

• If using the Designer client, select a source Notes database, QuickPlace or QuickR room, or Domino.Doc library and then select a corresponding source data definition.  If using the Migration Console, simply open the Database Properties, got to the Migration Jobs tab, and add a new migration job.

• On the second tab, select a target SharePoint site and Wiki page library (or any document library).  When asked whether you want to load a default target definition, say “Yes” and load the “Wiki pages” data definition.  You can also provision a new library on the fly here.

• On the third tab, press the “Auto Map” button.  The default mappings will create Wiki pages with the same name as the original Notes document, use the rich text Body field as the Wiki page content, and map any embedded elements to files in a subfolder.

• Press the Run Job button and go!

What you get in the end is a bunch of new Wiki pages in your SharePoint library.  Any embedded images, attachments, or OLE objects shown on the Wiki pages are really stored in the “Attachments” subfolder.

Advanced Job Customizations (optional)

• If you prefer to put images and attachments into a separate library, simply edit the target data definition, select the Files field, and specify the Alternate Library property instead of the  Alternate Folder property.  (By the way, this is definitely the “2010” way to organize things.  Many 2010 templates contain a “Site Pages” wiki library and a “Site Assets” library where all the images and attachments are intended to go.)

• If you would like to migrate the original attachment icons for your Notes attachments, simply edit the target data definition and check the “Migrate Attachments as Image files” checkbox.  The additional image files will be saved to the same alternate folder or library described above.

• If you are migrating a QuickPlace site or other Notes/Domino application that does not store attachments inside the rich text Body field, you may wish to concatenate a rendered “attachment links” area to the bottom of the page so you can link to them.  QuickPlace and QuickR data definitions already have a built-in “{OtherAttachmentLinks}” section that you map to the existing WikiField in your target.  (If you are using other data sources. you will need to define an AttachmentLinks section in your source data definition.)

• Notice how you the above job maps multiple source columns to one target WikiField?  You can actually concatenate as many things as you want (multiple rich text fields, text fields, and even static labels) to your WikiField.
• If you want to map additional Notes items to SharePoint metadata fields, just do that as you would for list items.  The extra fields will show up in the page properties and you can use them in view columns.

• Of course, you can use many other Notes Migrator for SharePoint features with your Wiki pages:  created/modified metadata, document level permissions, content types, folders and subfolders, approval status, incremental migrations, and much more.

As hard-core Notes Migrator for SharePoint users know, there are about five ways to migrate Notes documents to web pages in SharePoint 2007:

• HTML pages
• Basic pages
• Wiki pages
• Web Part pages
• Publishing pages

In our extensive regression testing with SharePoint 2010, we noticed that the rules have changed a few interesting ways.  Here are four basic changes you should be aware of:

1. HTML pages have been “secured” – If you populate a SharePoint document library with migrated HTML pages, everything migrates correctly, but SharePoint does not display the pages the same way when a user clicks on one of them.  Instead of displaying the page in the browser, SharePoint forces the user to download the HTML file and view it locally.  This is annoying at a minimum, but if the file contains relative links to other images or attachments, they will not work at all when opened from a different location.

The reason for this is that Microsoft decided that displaying HTML files indiscriminately was a security risk and they added safeguards to prevent that by default.  The remedy to this is to turn the new security feature off.  In Central Administration, go to Manage Web Applications -> General Settings and select “Permissive” as your Browser File Handling Option.

Be sure to read the description on this option and make sure you understand the security implications.  Going “Permissive” is really no less secure than what we had in SharePoint 2007, but if you have users you don’t trust uploading content to your site, you might be better off choosing a different type of page to migrate to.

2. Basic pages are gone… sort of – If you go to the Create menu in a typical SharePoint 2010 team site, you will see that there is no longer a “Basic Page” option.  As described below, I think there is a good reason for it.

If you use Notes Migrator for SharePoint to generate a bunch of Basic pages, it actually does still work.  Each page looks nice but all the window dressing is gone and you are stuck in read-only mode.  Notice in the screen shot below that there is no Quick Launch menu and the Edit buttons are disabled.

Perhaps some of the new site templates I have not experimented with yet still expose the ‘Basic Page” construct, but I suggest that most of us move on to Wiki pages.

3. Wiki pages are king! – In SharePoint 2007, Wiki pages were a cute, but somewhat limited, list type that not many people used.  In SharePoint 2010, they have become something that is greatly improved and now pretty ubiquitous.  When you create a new “Page” using the Create menu in a team site, you are now creating a Wiki page.  And the “Site Pages” library that (by default) holds pages that users create is now a Wiki Page Library.

Microsoft basically merged the concept of Basic pages, Wiki pages and Web Part pages into a single construct that is much more powerful – and much more user friendly – than before.  Remember that crappy rich text editor in SharePoint 2007?   Now the editor sizzles.  End users can upload images and files and can even embed Web Parts in their rich content (similar to the way they used to embed OLE objects in their Windows applications).

NOTE:  Don’t attempt to migrate to SharePoint 2010 Wiki Pages in Notes Migrator for SharePoint version 5.3.  Somewhere between the 2010 beta and RTM, there was a breaking change in how one of the SharePoint APIs worked and we had to make a two line change to accommodate it in our product.  Notes Migrator for SharePoint 5.3.1 fixes this issue which will RTM in a couple weeks.  If you can’t wait that long, contact me through your Quest rep and we will get you a build.

4. Put your Assets in the right place – When migrating to any of the above page types, it has been common practice to put the associated images and attachments in a subfolder inside the same document library you were putting the pages in (described in this post).  That’s not the 2010 way to do it, and there are some cases where it actually does not work out very well. 

Page Libraries in particular are not really designed for holding binary files.  Our tool will let you migrate attachments and images there, but the result is not always satisfying.  For one thing, you loose some of the nice integration that you have between Office applications and “normal” document libraries.  We have seen cases where Word will not open .doc files from a folder in a Page Library.

The right solution here is to put images and attachments in the “Site Assets” library, or whatever place the designer of your site template intended such things to go.  As shown below, this matches perfectly what users will  be encouraged to do when they upload new attachments while editing a new page.  Putting images and attachments into different libraries is nothing new for Notes Migrator for SharePoint and the technique is pretty simple (described in this post).

I will have a lot more to say about SharePoint pages – especially Wiki pages – in future posts.  Web Part pages and Publishing pages still exist as distinct page types and migrating to these work pretty much the same as they did in SharePoint 2007. 

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, version control, etc.  These are great examples of applications that may well to the “publishing” site templates available in SharePoint Server 2010 and MOSS 2007.  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 Notes Migrator for 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.

Notes Migrator for 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.  The remainder of this walkthrough will use screen shots from SharePoint 2007, but the process is nearly identical for SharePoint 2010.

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

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

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.

Now 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, we need to extract the page to a local file so we can example the ASPX layout.  Select View All Site Content from the Site Actions men 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.

Save the ASPX file to your computer and edit in any text editor.  I like Visual Studio or SharePoint Designer, because it gives me nice color coding and formatting, but Notepad also works just fine.  Keep this ASPX file handy, because 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 Notes Migrator for SharePoint migration job.  You can start from scratch or customize an existing job if you prefer, but you might prefer to start with an existing job that I created.  I suggest downloading one of the following jobs, depending on which version of SharePoint you are targeting:

[DocLibrary to Publishing Page 2007.pmjob]

[DocLibrary to Publishing Page 2010.pmjob]

If you are starting with the above jobs, should first change the source Notes database to refer to the 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”, etc.). 

You should also change and target SharePoint URL to point to your publishing site.  Both 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 jobs, 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.   

Remember that ASPX code we looked at when we downloaded a sample ASPX page from the server?  That is the code we need to put into the PageTemplate field.  But we don’t want all of it, just the bits that describe the page structure.  We can leave out the content parts 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 be different than the one I showed above, but generally you want the ASPX tags at the top (which start with “<%@”) and the <html> tag.  In my example, I am going to grab the first four lines and paste it into the little drop down editor for the PageTemplate.

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) in the above example.  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 Notes Migrator for 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 the address of a layout page on your SharePoint server.  Recall that when I created a test page in the example above, I selected the page layout “Article page with body only”.  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.

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 and start migrating! 

Upcoming releases of Notes Migrator for SharePoint will add a few things to make the above process a bit easier, but there is really no need to wait.  You can generate great looking publishing pages now.