documentation changes for the upcoming November release

jansenbe · jansenbe · commit fa642f5f1722 · 2019-11-04T12:14:50.000+01:00
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -1394,6 +1394,8 @@
           href: transform/modernize-userinterface-site-pages-model-publishing.md
         - name: Page transformation Functions and Selectors
           href: transform/modernize-userinterface-site-pages-api.md
+        - name: User mapping
+          href: transform/modernize-userinterface-site-pages-usermapping.md
         - name: URL mapping
           href: transform/modernize-userinterface-site-pages-urlmapping.md
         - name: Page layout mapping
diff --git a/docs/transform/modernize-userinterface-site-pages-configuration.md b/docs/transform/modernize-userinterface-site-pages-configuration.md
@@ -1,7 +1,7 @@
 ---
 title: Options to control the page transformation process
 description: Explains how to configure the page transformation process
-ms.date: 10/03/2019
+ms.date: 11/04/2019
 ms.prod: sharepoint
 localization_priority: Normal
 ---
@@ -156,6 +156,50 @@ PageTransformationInformation pti = new PageTransformationInformation(page)
 > [!NOTE]
 > This option is not available for publishing page transformation.
 
+## TargetPageName option
+
+Type | Default value if not specified
+-----|----
+String | empty
+
+You can optionally override the page name of the target page. By default the page transformation engine will generate one, but sometimes it's needed to override (e.g. default.aspx will collide with the default.aspx view page of the SitePages library).
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    TargetPageName = "mypage.aspx",
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    TargetPageName = "mypage.aspx",
+};
+```
+
+## TargetPageFolder option (as of November 2019 release)
+
+Type | Default value if not specified
+-----|----
+String | empty
+
+You can optionally specify the folder in which the target page will be created. Note that if a folder was created automatically (e.g. because you were transforming from an extra wiki page library) then the folder specified by this parameter will be combined with the auto-generated folder. You can specify a folder like this: `MyFolder` or `MyFolder/SubFolder` when you want to create a nested folder structure.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    TargetPageFolder = "MyFolder",
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    TargetPageFolder = "MyFolder",
+};
+```
+
 ## ReplaceHomePageWithDefaultHomePage option
 
 Type | Default value if not specified
@@ -450,6 +494,72 @@ PublishingPageTransformationInformation pti = new PublishingPageTransformationIn
 };
 ```
 
+## UserMappingFile option (as of November 2019 release)
+
+Type | Default value if not specified
+-----|----
+String | empty
+
+You can optionally specify a file with custom user mappings. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    UserMappingFile = @"c:\temp\usermappingfile.csv",
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    UserMappingFile = @"c:\temp\usermappingfile.csv",
+};
+```
+
+## LDAPConnectionString option (as of November 2019 release)
+
+Type | Default value if not specified
+-----|----
+String | empty
+
+You can optionally specify a custom LDAP connection string towards your Active Directory environment. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    LDAPConnectionString = "LDAP://OU=Test,DC=CONTOSO,DC=COM",
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    LDAPConnectionString = "LDAP://OU=Test,DC=CONTOSO,DC=COM",
+};
+```
+
+## SkipUserMapping option (as of November 2019 release)
+
+Type | Default value if not specified
+-----|----
+Bool | false
+
+The default behavior is to always perform user mapping when you are transforming pages coming from SharePoint on-premises, use this option to disable that. See the [URL mapping](modernize-userinterface-site-pages-urlmapping.md) article to learn more.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    SkipUserMapping = true,
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    SkipUserMapping = true,
+};
+```
+
 ## HandleWikiImagesAndVideos option
 
 Type | Default value if not specified
diff --git a/docs/transform/modernize-userinterface-site-pages-powershell.md b/docs/transform/modernize-userinterface-site-pages-powershell.md
@@ -1,7 +1,7 @@
 ---
 title: Transform classic pages to modern client-side pages using PowerShell
 description: Explains how to transform classic wiki and web part pages into modern client side pages using the SharePoint PowerShell
-ms.date: 10/22/2019
+ms.date: 11/04/2019
 ms.prod: sharepoint
 localization_priority: Priority
 ---
@@ -39,23 +39,28 @@ TargetWebUrl (`**`) (as of March 2019 release, version 3.7.1903.*) | | Cross sit
 TargetConnection (`**`) (as of the June 2019 release, version 3.8.1906.) | | Cross site transformation | Allows for a more flexible definition of the target via a connection object. This allows for example to perform cross tenant transformation of transformation from on-premises to online.
 UseCommunityScriptEditor (as of March 2019 release, version 3.7.1903.*) | $false | All page types | Use `-UseCommunityScriptEditor` if you've installed the community script editor and want to use it during transformation. Consult the [web part transformation list](modernize-userinterface-site-pages-webparts.md) article to learn more.
 SummaryLinksToHtml (as of March 2019 release, version 3.7.1903.*) | $false | All page types | Use `-SummaryLinksToHtml` if you prefer to transform the SummaryLinks web part to HTML hosted in the text web part instead of the default transformation using the QuickLinks web part. Consult the [web part transformation list](modernize-userinterface-site-pages-webparts.md) article to learn more.
-LogType (as of April 2019 release, version 3.8.1904.*) | None | All page types | Use `-LogType` to enabled logging: `File` will log to disk, `SharePoint` will create a log page in the SharePoint SitePages library.
+LogType (as of April 2019 release, version 3.8.1904.*) | None | All page types | Use `-LogType` to enabled logging: `File` will log to disk, `SharePoint` will create a log page in the SharePoint SitePages library, `Console` will output data to the console.
 LogFolder (as of April 2019 release, version 3.8.1904.*) |  | All page types | If `LogType` is set to `File` then you can use `-LogFolder` to specify the folder where the log will be created.
 LogVerbose (as of April 2019 release, version 3.8.1904.*) | $false | All page types | Use `-LogVerbose` to generate a verbose log.
 LogSkipFlush (as of April 2019 release, version 3.8.1904.*) | $false | All page types | By default each cmdlet call generates a unique log file, use the `-LogSkipFlush` parameter to accumulate log entries. Note that you'll have to end with a call without LogSkipFlush to persist the assembled log file entries.
 DontPublish (as of April 2019 release, version 3.8.1904.*) | $false | All page types | Use the `-DontPublish` option to not publish the created modern page.
 KeepPageCreationModificationInformation (as of October 2019 release, version 3.14.1910.*) | $false | All page types | Use `-KeepPageCreationModificationInformation` parameter if you want to take over the Author/Editor/Created/Modified page properties. This option only works for when the source page is in the same SPO tenant as the target destination of the modern page.
 PostAsNews (as of October 2019 release, version 3.14.1910.*) | $false | All page types | Use the `-PostAsNews` parameter if you want to post the created modern page as news on the site. This also implies that the page will be published, even if you've configured to skip publishing.
+SetAuthorInPageHeader (as of October 2019 release, version 3.14.1910.*) | $false | Wiki/webpart/blog pages | Use the `-SetAuthorInPageHeader` parameter if you want to populate the author in the header of the created page. The author will be set the (user mapped) source page author.
 DisablePageComments (as of April 2019 release, version 3.8.1904.*) | $false | All page types | Use `-DisablePageComments` if you want to disable the commenting option on the created page
 PublishingPage (as of April 2019 release, version 3.8.1904.*) | $false | Publishing pages | Set the `-PublishingPage` parameter if you're transforming a publishing page. For wiki,web part and blog pages this parameter must be omitted or set to false.
 PageLayoutMapping (as of April 2019 release, version 3.8.1904.*) |  | Publishing pages |Via `-PageLayoutMapping` you can specify the path the [page layout mapping file](modernize-userinterface-site-pages-model-publishing.md) that you'll use for your publishing page transformations when the publishing page is using a non out of the box page layout
 TargetPageName (as of Oct 2019 release, version 3.14.1910.*) |  | Wiki/webpart/blog pages | Use the `-TargetPageName` parameter to override the default name for the modern page. This is for example needed to prevent overwriting the existing home.aspx page if you a cross site transformation of a classic team site home page to a modern communication site.
 PublishingTargetPageName (as of May 2019 release, version 3.9.1905.*) |  | Publishing pages | Use the `-PublishingTargetPageName` parameter to override the name for the modern page
-SkipUrlRewriting (as of May 2019 release, version 3.9.1905.*) | $false | Cross site transformation | During publishing page transformation URL's are rewritten to be valid in the target site collection, but using the `-SkipUrlRewriting` you can disable the URL rewriting. See the [URL mapping](modernize-userinterface-site-pages-urlmapping.md) article to learn more.
+TargetPageFolder (as of November 2019 release, version 3.15.1911.*) |  | All page types | Use the `-TargetPageFolder` parameter to specify a target folder for the modern page. Note that if a folder was created automatically (e.g. because you were transforming from an extra wiki page library) then the folder specified by this parameter will be combined with the auto-generated folder. You can specify a folder like this: `MyFolder` or `MyFolder/SubFolder` when you want to create a nested folder structure.
 UrlMappingFile (as of July 2019 release, version 3.11.1907.*) |  | Cross site transformation | File with custom URL mapping definitions allow you to do more than just the default URL mapping. See the [URL mapping](modernize-userinterface-site-pages-urlmapping.md) article to learn more.
+SkipUrlRewriting (as of May 2019 release, version 3.9.1905.*) | $false | Cross site transformation | During publishing page transformation URL's are rewritten to be valid in the target site collection, but using the `-SkipUrlRewriting` you can disable the URL rewriting. See the [URL mapping](modernize-userinterface-site-pages-urlmapping.md) article to learn more.
 SkipDefaultUrlRewriting (as of September 2019 release, version 3.13.1909.*) | | Cross site transformation | When you use a custom URL mapping and you want to disable the default URL rewrite logic then set the `-SkipDefaultUrlRewriting` parameter.
 AddTableListImageAsImageWebPart (as of October 2019 release, version 3.14.1910.*) | $true | All page types | Images living inside a table/list are also created as separate image web parts underneath that table/list. Use the `-AddTableListImageAsImageWebPart` parameter to stop the creation of these separate image web parts.
 BlogPage (as of the October 2019 release, version 3.14.1910.*) | $false | Blog pages | Set the `-BlogPage` parameter if you're transforming a classic blog page. For wiki,web part and publishing pages this parameter must be omitted or set to false.
+UserMappingFile (as of November 2019 release, version 3.15.1911.*) |  | All page types | File with user mapping information. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
+LDAPConnectionString (as of November 2019 release, version 3.15.1911.*) |  | All page types | LDAP connection string to query active directory. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
+SkipUserMapping (as of November 2019 release, version 3.15.1911.*) | $false  | All page types | Skips the user mapping. For SPO transformations user mapping is off unless you specify a mapping file, for on-premises SharePoint user mapping is always on unless you set this flag. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
 
 (`*`) Mandatory command line parameter / (`**`) Mandatory when the `-PublishingPage` parameter was set (either `-TargetWebUrl` or `-TargetConnection`)
 
diff --git a/docs/transform/modernize-userinterface-site-pages-usermapping.md b/docs/transform/modernize-userinterface-site-pages-usermapping.md
@@ -0,0 +1,53 @@
+---
+title: User mapping during page transformation
+description: Explains how to the user mapping works when transforming pages
+ms.date: 11/04/2019
+ms.prod: sharepoint
+localization_priority: Priority
+---
+
+# User mapping during page transformation (as of the November 2019 release)
+
+When you're transforming pages from your on-premises SharePoint you typically are using Active Directory accounts (e.g. CONTOSO\JOE) to grant access to SharePoint while in SharePoint Online you use Azure Active Directory accounts to grant access. User mapping is a component of page transformation that enables you to map your on-premises Active Directory accounts to Azure Active Directory accounts in SharePoint Online and use those mapped accounts to specify user and group related information of the target page.
+
+## Default user mapping for pages transformed from on-premises SharePoint
+
+When you are transforming pages from on-premises SharePoint then user mapping is on by default: many customers that have on-premises and online SharePoint also use Active Directory sync which means that the on-premises users and groups also exist in SharePoint Online as users and groups. The default user mapping system will lookup the on-premises user by querying the local Active Directory environment, if a user is found than we take the user's UPN (user principal name) value and use that to find the same user in Azure Active Directory.
+
+Default user mapping does require a connection the your on-premises Active Directory which is done via LDAP queries. A default LDAP connection string is built based upon you fully qualified Active Directory ___domain name: if your Active Directory ___domain was contoso.com then the used LDAP connection string is LDAP://DC=contoso,DC=com. If this however is wrong then you specify a custom LDAP connection string via the `-LDAPConnectionString` parameter to the `ConvertTo-PnPClientSidePage` cmdlet if you're using PnP PowerShell. If you're using .Net then you can define the custom LDAP connection string via the `LDAPConnectionString` attribute of the .Net page transformation configuration objects (`PageTransformationInformation` and `PublishingPageTransformationInformation`).
+
+> [!IMPORTANT]
+> Given the mapping depends on ___domain lookups it will only work if the machine/account running the page transformation are joined to the same Active Directory ___domain as the one holding the accounts/groups that are used to authorize access to the on-premises SharePoint environment.
+
+If you want to completely disable user mapping for your SharePoint on-premises to SharePoint transformations then you can use the `-SkipUserMapping` parameter to the `ConvertTo-PnPClientSidePage` cmdlet if you're using PnP PowerShell. If you're using .Net then you can skip user mapping via the `SkipUserMapping` attribute of the .Net page transformation configuration objects (`PageTransformationInformation` and `PublishingPageTransformationInformation`).
+
+## Mapping based upon a mapping file
+
+If you don't like or cannot use the automatic user mapping based upon Active Directory lookups then there's also the option to specify a user mapping file. A user mapping file is a simple CSV file listing source account and target account as shown in below snippet
+
+```Text
+sharepoint\system,admin@contoso.onmicrosoft.com
+contoso\paul,paul@contoso.onmicrosoft.com
+contoso\bert,bert@contoso.com
+s-1-5-21-3138640143-967965215-2549001177-3604,SalesGroup
+```
+
+Some things to note:
+
+- You can map the **system account** via sharepoint\system
+- Groups have to be specified via the group sid
+
+Creating the mapping file is the first step, to actually use it you need to specify the file via the `UserMappingFile` parameter to the `ConvertTo-PnPClientSidePage` cmdlet if you're using PnP PowerShell. If you're using .Net then you can specify the file via the  `UserMappingFile` attribute of the .Net page transformation configuration objects (`PageTransformationInformation` and `PublishingPageTransformationInformation`).
+
+> [!IMPORTANT]
+> User mapping can also be used when doing cross site page transformation in SharePoint Online. It allows you to "replace" certain old accounts with newer ones.
+
+## Where does user mapping apply
+
+User mapping is integrated in page transformation in the following places:
+
+- If you have metadata user fields that you are copying over
+- If you have item level permissions on a source page and you're taking over these permissions (note that you can use the `SkipItemLevelPermissionCopyToClientSidePage` option to prevent this)
+- If you're populating the page header (via the `SetAuthorInPageHeader` option for wiki/webpart and blog pages or via appropriate configuration in your page layout mapping file for publishing pages)
+- If you're keeping the page author/editor/created/modified information via the `KeepPageCreationModificationInformation` option
+- If you're transforming a ContactFieldControl web part
