Set-SyncTask

The TaskID parameter specifies an existing task in the task queue that should be updated. Tasks that are actively processing cannot be updated.

This parameter can accept an explicit Guid value, or an object that has a ‘TaskID’ property, such as a SyncTask object that is returned by Get-SyncTask.

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.

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

The AppendToExclusionsList switch parameter specifies whether to append or replace Exclusions applied by this cmdlet. If no Exclusions have been supplied, this parameter is ignored.

The QueuePosition parameter specifies the relative position in the task queue with lower numbers being closer to the top of the queue.

It is possible for several tasks to have the same QueuePosition number. When this occurs, the tasks with the same QueuePosition are processed in the order in which they were added.

A QueuePosition of Zero will set the item to the top of the queue, along with any other tasks that have a QueuePosition of zero. As such, a value of zero does not inherently result in the task being the next one processed. If several tasks already exist with a QueuePosition of zero, setting this value to a negative number will cause it to be ordered before those tasks with a value of zero.

The QueuePosition of tasks can be retrieved with the Get-SyncTask cmdlet. In addition, the Reset-QueuePosition cmdlet can be used to reorder in series some or all tasks.

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 setting a SyncTask in the task queue with a deferred start time.

The RemoveStartOnOrAfterDate switch parameter, if used, will clear the StartOnOrAfter date on an existing task. Doing so will cause the task to start based on its QueuePosition value. If a StartOnOrAfter parameter is also present and with a value, the value is ignored and the StartOnOrAfter value on the task is cleared.

The DateRangeForItems 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 parameters, 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 rights to the collection.
Alternatively, the Add-FolderSpecificAllowedActions cmdlet can add rights directly to a SyncTask.

The AppendToFolderSpecificAllowedActions switch parameter specifies whether to append or replace FolderSpecificAllowedActions applied by this cmdlet. If no FolderSpecificAllowedActions have been supplied, this parameter is ignored.

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 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 AllowedFolderActions 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 cmdlet 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 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 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 and instance of an object for this parameter.