New-SyncTask

The ConnectionInfo parameter specifies the source and target stores that are to be used for the sync. Use the New-ConnectionInfo cmdlet to create an instance of an object for this parameter.

The OneWaySyncSourceToTarget parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:

FolderSyncRights = AllowTargetCreate, AllowTargetModify, AllowTargetDelete, FolderPropertyPreference: Source
ItemSyncRights = AllowTargetCreate, AllowTargetModify, AllowTargetDelete

The OneWaySyncSourceToTargetNoDeletes parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowTargetCreate, AllowTargetModify, FolderPropertyPreference: Source
ItemSyncRights = AllowTargetCreate, AllowTargetModify

The OneWaySyncTargetToSource parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete, FolderPropertyPreference: Target
ItemSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete

The OneWaySyncTargetToSourceNoDeletes parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, FolderPropertyPreference: Target
ItemSyncRights = AllowSourceCreate, AllowSourceModify

The TwoWaySync parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete, AllowTargetCreate, AllowTargetModify, AllowTargetDelete, FolderPropertyPreference: LastModified
ItemSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete, AllowTargetCreate, AllowTargetModify, AllowTargetDelete

The TwoWaySyncNoDeletes parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, AllowTargetCreate, AllowTargetModify, FolderPropertyPreference: LastModified
ItemSyncRights = AllowSourceCreate, AllowSourceModify, AllowTargetCreate, AllowTargetModify

The TwoWaySyncNoSourceDeletes parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, AllowTargetCreate, AllowTargetModify, AllowTargetDelete, FolderPropertyPreference: LastModified
ItemSyncRights = AllowSourceCreate, AllowSourceModify, AllowTargetCreate, AllowTargetModify, AllowTargetDelete

The TwoWaySyncNoTargetDeletes parameter is a shortcut for setting the -FolderSyncRights and -ItemSyncRights parameters with the following values:
FolderSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete, AllowTargetCreate, AllowTargetModify, FolderPropertyPreference: LastModified
ItemSyncRights = AllowSourceCreate, AllowSourceModify, AllowSourceDelete, AllowTargetCreate, AllowTargetModify

The Folders parameter specifies zero or more folder paths that are the starting folders for a sync session. If this value is empty or not provided, the starting folder is the {VisibleRoot} folder for the source and target stores.

Multiple starting folders can be set in a SyncTask, even if the will overlap. The order in which the starting folders are processed is by the QueuePosition property of each starting folder object. In the case of multiple folders with the same QueuePosition, the order of the folders is based on the order in which the were added. Starting folders can be set to be recursive, enumerating child folders during processing, or as a single folder operation. Use the Subfolders property of the starting folder object to control this behavior.

Starting folder objects are created by the New-StartingFolder cmdlet.

In addition to the New-StartingFolder cmdlet, specially formatted text strings can be used to define the starting folder(s), as follows:

If a folder path string starts with a number, followed by a colon ‘:’, such will indicate the queue position for the new starting folder:
-Folders '23:\{inbox}'

If a folder path starts with an equals ‘=’ sign, followed by a colon ‘:’, such will indicate that the subfolders of the identified folder are NOT to be included:
-Folders '=:\{inbox}'

If a folder path starts with a number followed by a colon, then is followed by an equals sign followed by a colon, the queue position is set as is the ‘no subfolders’ option:
-Folders '25:=:\{inbox}'

In the previous 3 examples, only a single folder path was provided. This will create a starting folder element that has its TargetFolderOption set to: CreateFullPath. See New-StartingFolder for detail about this option.

If a folder path has either of the above prefixes, or none, and lists two folder paths, such will indicate the source and target folder paths of the new starting folder.

Example 1:
-Folders '\{Inbox}\Archived Orders == \Archived Data\Orders'
Note: there MUST be a space on each side of the double-equal operator. This will not work: “value==value”, while this will work: “value == value’.

Example 2:
-Folders '12:\{Inbox}\Archived Orders == \Archived Data\Orders'

In both of the previous examples, and because two folder paths were included, the TargetFolderOption is set to: MergeWithTarget.

Multiple starting folders can be provided at once as an array or list:
-Folders '0:\{Inbox}', '1:\{Calendar}', '3:\'
In the above example, three starting folders are added with specific QueuePosition values.

The Exclusions parameter specifies zero or more folder exclusions to apply to the SyncTask.
An exclusion prevents the sync engine from processing the identified folder and any of its child folders.

This parameter can be set using a text string, or by creating an exclusion object with the New-FolderExclusion cmdlet.

The text string option should be either a full path string or a pattern-matching string as follows:

Literal Text Paths:
\Inbox\OldDocuments
\{DeletedItems}

Note the second example above contains a TokenizedPath. If using TokenizedPaths, the -ExclusionsUseTokenizedPaths switch parameter must also be used.

Pattern-Matching Text:
RX:Delete|Old|Sent
RX:Deleted|Archived

Note that for pattern-matching strings, the pattern is prefixed with ‘RX:’ to indicate that the text after the prefix is a regex pattern.

This parameter accepts one or more values separated by commas. For text-based values that contain spaces or characters that PowerShell might confuse as tokens, it is suggest to wrap such text in ‘single quotes’. Note that in PowerShell, a “double quote” will be parsed for PowerShell tokens while text in ‘single quotes’ is left exactly as is.

The ExclusionsUseTokenizedPaths specifies whether the excluded folders specified with the -Exclusions parameter are defined using TokenizedPaths.

The StartOnOrAfter parameter specifies the date and time on or after which the sync processing may occur for this SyncTask.

This parameter is useful for adding a SyncTask to the task queue with a deferred start time, in contrast to waiting to add it to the task queue manually at a certain time.

The DateRangeForItems parameter specifies either a range of dates or a range of days, for which only items with a modified date within the specified range will be synchronized.

When the date range is using a range of days, the number of days of the top and bottom ranges are added to the current date/time at which the sync session started for the SyncTask, not the date/time the task was created.

For example, if a new SyncTask were created on 2019-Jun-06 and with a RangeTop of 0 and a RangeBottom of 30, and was not started until 2019-Jun-30, items with a modified date on or before 2019-Jun-30 and on or after 2019-Jun-01 would be synchronized.

Use the New-DateRange cmdlet to create a date range object for this parameter.

If this parameter is not used, all items will be synchronized.

The FolderSpecificAllowedActions parameter specifies zero or more synchronization rights for specific folders. FolderSpecificAllowedActions uses the same set of limits as this cmdlet’s AllowedFolderActions and AllowedItemActions, except at a folder level.

When the sync engine in processing a sync task, it will first look for any folder specific rights, and if none are found that match the current folder being processed, the task-level rights are used.

Use the New-FolderSpecificAllowedActionsCollection cmdlet to create a new instance of an object that can be passed to the New-SyncTask cmdlet. Note that the New-FolderSpecificAllowedActionsCollection cmdlet creates an empty collection of rights. After creating, use the Add-FolderSpecificAllowedActions cmdlet to add one or more folder specific allowed actions to the collection.
Alternatively, the Add-FolderSpecificAllowedActions cmdlet can add rights directly to a SyncTask.

The AllowedFolderActions parameter specifies the general rights that the sync engine will have to perform operations on folders for this SyncTask.

When the sync engine is processing a folder for a sync task, it will first attempt to see if the folder matches a FolderSpecificAllowedActions value, and if not will use the folder rights of this parameter.

Use the New-AllowedFolderActions cmdlet to create an instance of an object that can be used with this parameter.

Alternatively, this parameter supports a formatted text value that can be converted to a FolderSyncRights object.
ASC = AllowSourceCreate
ASD = AllowSourceDelete
ASM = AllowSourceModify
ATC = AllowTargetCreate
ATD = AllowTargetDelete
ATM = AllowTargetModify
RSFT = RestoreSourceFromTargetIfDeleted
RTSF = RestoreTargetFromSourceIfDeleted
PPLM = PropertyPreference.LastModified
PPS = PropertyPreference.Source
PPT = PropertyPreference.Target

Example: -AllowedFolderActions 'ATC ATM ATD PPS'
Note: the order of shortcut tokens is irrelevant as is the amount of non-word characters between the tokens.
This example works equally as well: -AllowedFolderActions ' PPS\ATC\ATM\ATD '.
However, this will not work: -AllowedFolderActions 'ATCATMATDPPS'.

The AllowedItemActions parameter specifies the general rights that the sync engine will have to perform operations on items for this SyncTask.
When the sync engine is processing a folder for a sync task, it will first attempt to see if the folder matches a FolderSpecificAllowedActions value, and if not will use the item rights of this parameter.
Use the New-AllowedItemActions cmdlet to create an instance of an object that can be used with this parameter.
Alternatively, this parameter supports a formatted text value that can be converted to an AllowedItemActions object.
ASC = AllowSourceCreate
ASD = AllowSourceDelete
ASM = AllowSourceModify
ATC = AllowTargetCreate
ATD = AllowTargetDelete
ATM = AllowTargetModify

Example: -AllowedItemActions 'ATC ATM ATD'
Note: the order of shortcut tokens is irrelevant as is the amount of non-word characters between the tokens.
This example works equally as well: -AllowedItemActions ' ATC\ATM\ATD '.
However, this will not work: -AllowedItemActions 'ATCATMATD'.

The DisableMapiHttpForSource parameter determines whether the sync engine will create and used a MapiHTTP based connection to the source store.

MapiHTTP is only available on specific versions of Outlook. Refer to Microsoft’s article about MapiHTTP for details on versions.

NOTE: In Priasoft’s testing and real-world experience with customer environments, MapiHTTP is a slower protocol for long running data transfers. We suggest experimenting with this setting if performance is a concern. However, even though Exchange 2019 and Office 365 still support the older OutlookAnywhere (RPC-over-HTTP) protocol, which does perform better, Microsoft will like move to drop the protocol sometime in the year 2020.

The DisableMapiHttpForTarget parameter determines whether the sync engine will create and used a MapiHTTP based connection to the target store.
MapiHTTP is only available on specific versions of Outlook. Refer to Microsoft’s article about MapiHTTP for details on versions.
NOTE: In Priasoft’s testing and real-world experience with customer environments, MapiHTTP is a slower protocol for long running data transfers. We suggest experimenting with this setting if performance is a concern. However, even though Exchange 2019 and Office 365 still support the older OutlookAnywhere (RPC-over-HTTP) protocol, which does perform better, Microsoft will like move to drop the protocol sometime in the year 2020.

The UseAdminPrivilegeForSource parameter determines whether the sync engine requests system-level access to an Exchange store.
This feature is only available to on-premises deployments of Microsoft Exchange. This feature is not available for Office 365.

Microsoft Exchange support four different ways of accessing a mail store:
As-Owner: The owner of the mailbox authenticates. This would be the ActiveDirectory account for which a mailbox has been attached.
FullAccess: An administrator has provided the FullAccess permission of a non-owner to a store.
Database Permission: An administrator has grated access to all stores on a specific database.
System Privileges: An administrator has granted access to all stores on a specific database, and has allowed system-level access.

System Privileges allow an application to operate on an Exchange store without interference from user-level folder permissions. For example, if an owner of a store adjusts the permissions on a folder in the store such that only the owner is able to see or modify the folder, a non-owner could be blocked from accessing the same folder. System-level privileges would not be blocked by user actions.

System privileges are especially useful for on-premises public folders. With public folders it is not possible to grant the FullAccess permission to a public-folder-database or a public-folder-mailbox. If system privileges are not available (Office365) or cannot be set, perhaps due to business policy or lack of admin access to apply such, Super-ExMerge would need Owner permissions on each folder to be sync’d.

For any folder in which Super-ExMerge lacks sufficient privilege, the sync of that folder would fail if new data needed to be copied into it, or existing data modified or removed.

Use the following example to grant system privileges to a database for a specific user or group:
Get-MailboxDatabase -Identity DatabaseID | Add-ADPermission -User UserOrGroupID -AccessRights ExtendedRight -ExtendedRights Receive-As, ms-Exch-Store-Admin

The Receive-As right allows a user or group to open an Exchange store. This is very similar to the FullAccess permission that can be granted on a per-mailbox basis.
The ms-Exch-Store-Admin right extends the Receive-As right to allow opening a store with system privileges.

Note that for public folders on Exchange 2010 and earlier, Get-PublicFolderDatabase
would be used in the above command example instead of Get-Mailbox. Exchange 2013 and later use special mailboxes for public folders, so the above example works for those as well because public-folder-mailboxes are contained in normal mailbox databases.

Lastly, all versions of Microsoft Exchange have a delayed availability of permissions that are applied at a database level. Once applied, it can take up to four hours before Exchange will actually accept authentications with these new privileges. The only supported mechanisms for accelerating the use of the permissions is by restarting the Information Store service, or a reboot of the Exchange server. Given the impact that this has, it is often best to simply wait for the permissions to cache before attempting to use them.

The UseAdminPrivilegeForTarget parameter determines whether the sync engine requests system-level access to an Exchange store.
This feature is only available to on-premises deployments of Microsoft Exchange. This feature is not available for Office 365.

Refer to the detail in the complement parameter above, UseAdminPrivilegeForSource, for a full explanation of this option.

The SourceItemFilter parameter specifies a script block to be executed that can be used to evaluate a source item that is to be processed to and to either skip the item or allow further processing.

Use the New-ItemFilter cmdlet to create an instance of an object for this parameter.

The TargetItemFilter parameter specifies a script block to be executed that can be used to evaluate a target item that is to be processed to and to either skip the item or allow further processing.
Use the New-ItemFilter cmdlet to create an instance of an object for this parameter.