Note: PowerShell integration requires a ShareGate Migrate Pro or Enterprise subscription. It is not available on the Essentials plan.
Command
Import-BoxDocument
Description
The command to import Box documents to a SharePoint library.
Note: You can only copy Box.com documents with PowerShell.
Note: Since Insane mode is used by default (unless -NormalMode is specified), the command waits for the Microsoft 365 Azure import to complete before returning. Use -NoWaitForImportCompletion to return immediately after local processing instead; in that case, the returned result is provisional (the import isn't reflected in it yet). Use Wait-ImportCompletion, or keep the current PowerShell session running, to know when the import actually finishes. The previous -WaitForImportCompletion switch is now deprecated, since waiting for completion is the default behavior again.
Tips:
To learn how to adapt any
Import-BoxDocumentscript to perform an incremental migration, see Incremental update using PowerShell.To learn about available copy options, see Copy options in PowerShell.
If you experience considerable performance issues, see Box.com throttling.
Examples
Import all documents.
$box = Connect-Box -Email [email protected]
$dstSite = Connect-Site -Url "http://myfarm1/sites/mydestinationsite"
$dstList = Get-List -Name "mydstlib" -Site $dstSite
Import-BoxDocument -Box $box -DestinationList $dstList
Import all documents from another user in Admin mode.
$box = Connect-Box -Email [email protected] -Admin
Import-BoxDocument -Box $box -UserEmail [email protected] -DestinationList $dstList
Specify source and destination folders.
Import-BoxDocument -Box $box -SourceFolder "MyFolder/DocumentsToImport" -DestinationList $dstList -DestinationFolder "MyFolder/MySubFolder"
Specify source paths to import.
Import-BoxDocument -Box $box -DestinationList $dstList -SourceFilePath "MyFolder/DocumentsToImport/Document1.docx", "MyFolder/DocumentsToImport/Document2.docx"
Import documents with a property template.
$propertyTemplate = New-PropertyTemplate -AuthorsAndTimestamps -VersionHistory -Permissions -NoLinkCorrection -FlattenFolders -VersionLimit 5 -CheckInAs Publish -ContentApproval SameAsCurrent -From 2012-01-01 -To 2012-12-31
$box = Connect-Box -Email [email protected]
Import-BoxDocument -Box $box -SourceFolder "MyFolder/DocumentsToImport" -DestinationList $dstList -Template $propertyTemplate
Import documents with property mappings.
$mappings = Get-PropertyMapping -Box $box -DestinationList $dstList
$mappings = Set-PropertyMapping -MappingSettings $mappings -Source "CustomData1" -Destination "CustomData1"
Import-BoxDocument -Box $box -DestinationList $dstList -MappingSettings $mappings
Note: CustomData1 is custom metadata on certain Box files. They need to be explicitly mapped, as Get-PropertyMapping does not go through all Box files to find all your Box fields. If your metadata is part of a non-global metadata template in Box, follow this format when setting the property mapping: templateName_metadataFieldName. Unmapped custom metadata ends up in the UnmappedCustomMetadata column, which can be mapped to a multiple lines of text field at the destination.
Run a pre-check before importing all documents.
Import-BoxDocument -Box $box -DestinationList $dstList -WhatIf
Import documents without waiting for the Microsoft 365 Azure import to complete, then use Wait-ImportCompletion to know when it's finished.
$box = Connect-Box -Email [email protected]
$dstSite = Connect-Site -Url "http://myfarm1/sites/mydestinationsite"
$dstList = Get-List -Name "mydstlib" -Site $dstSite
Import-BoxDocument -Box $box -DestinationList $dstList -NoWaitForImportCompletion
Wait-ImportCompletion
Syntax
Import-BoxDocument
-Box <BoxInfo>
-DestinationList <List>
[-UserEmail <String>]
[-DestinationFolder <Uri>]
[-SourceFolder <Uri>]
[-TemplateName <String>]
[-NormalMode <SwitchParameter>]
[-NoWaitForImportCompletion <SwitchParameter>]
[-WhatIf <SwitchParameter>]
[-CopySettings <CopySettings>]
[-MappingSettings <MappingSettings>]
[-TaskName <String>]
Import-BoxDocument
-Box <BoxInfo>
-DestinationList <List>
-Template <PropertyTemplate>
[-UserEmail <String>]
[-DestinationFolder <Uri>]
[-SourceFolder <Uri>]
[-NormalMode <SwitchParameter>]
[-NoWaitForImportCompletion <SwitchParameter>]
[-WhatIf <SwitchParameter>]
[-CopySettings <CopySettings>]
[-MappingSettings <MappingSettings>]
[-TaskName <String>]
Import-BoxDocument
-Box <BoxInfo>
-DestinationList <List>
-Template <PropertyTemplate>
-SourceFilePath <Uri[]>
[-UserEmail <String>]
[-DestinationFolder <Uri>]
[-SourceFolder <Uri>]
[-NormalMode <SwitchParameter>]
[-NoWaitForImportCompletion <SwitchParameter>]
[-WhatIf <SwitchParameter>]
[-CopySettings <CopySettings>]
[-MappingSettings <MappingSettings>]
[-TaskName <String>]
Import-BoxDocument
-Box <BoxInfo>
-DestinationList <List>
-SourceFilePath <Uri[]>
[-UserEmail <String>]
[-DestinationFolder <Uri>]
[-SourceFolder <Uri>]
[-TemplateName <String>]
[-NormalMode <SwitchParameter>]
[-NoWaitForImportCompletion <SwitchParameter>]
[-WhatIf <SwitchParameter>]
[-CopySettings <CopySettings>]
[-MappingSettings <MappingSettings>]
[-TaskName <String>]
Parameters
-Box <BoxInfo>
Specifies the source Box.
Required? | True |
Default value | None |
Accept pipeline input? | True (ByValue, ByPropertyName) |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-CopySettings <CopySettings>
Specifies the copy settings.
Required? | False |
Default value | None |
Accept pipeline input? | True (ByValue, ByPropertyName) |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-DestinationFolder <Uri>
Specifies the folder path at the destination. Note: This parameter cannot be used to create new folders at the destination.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-DestinationList <List>
Specifies the destination list.
Required? | True |
Default value | None |
Accept pipeline input? | True (ByValue, ByPropertyName) |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-MappingSettings <MappingSettings>
Specifies the mapping settings.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-NormalMode <SwitchParameter>
Specifies that the normal mode should be used.
Note: Insane mode is always used by default in PowerShell.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-NoWaitForImportCompletion <SwitchParameter>
Specifies that the command returns after local processing without waiting for the Azure Insane mode import to complete.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-SourceFilePath <Uri[]>
Specifies the source file path.
Required? | True |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | Template, TemplateSourceFilePath |
Aliases | None |
-SourceFolder <Uri>
Specifies the folder path at the source.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-TaskName <String>
Specifies a name for the task.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-Template <PropertyTemplate>
Specifies the property template. To use the built-in "Full copy" template, do not specify this parameter.
Required? | True |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | Template, TemplateSourceFilePath |
Aliases | None |
-TemplateName <String>
Specifies the property template to use by its name. You can use ShareGate to configure property templates for the specified list (see Import Property Mapping or New Property Template). To use the built-in "Full copy" template, do not specify this parameter.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | Default, TemplateNameSourceFilePath |
Aliases | None |
-UserEmail <String>
Specifies the user account from which to migrate. If the parameter is not set, the logged in user's files will be imported. You must be connected as an administrator in order to use this parameter.
Required? | False |
Default value | None |
Accept pipeline input? | True (ByValue, ByPropertyName) |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |
-WhatIf <SwitchParameter>
Specifies that a pre-check will be executed instead of a migration. For more information, see Run a Pre-Check in PowerShell.
Required? | False |
Default value | None |
Accept pipeline input? | False |
Accept wildcard characters? | False |
Parameter set name | (All) |
Aliases | None |