New-SmJob

Detailed Description

New-SmJob is the heart of Simply Migrate. A job, in its simplest form is a mechanism of causing an action against a single source of data.  That action may be a migration to a specified target, or a reporting task.

Syntax

New-SmJob 
[-Source] {PSTFile | Exchange | ExchangePubFolders | EnterpriseVault | EnterpriseVaultFileSystemArchiving | FilesMsg | FilesEml | Bloomberg | EmailXTender | ZantazEAS | ArchiveManager | Metalogix | OneDrive | OneDriveBusiness | ReportOnly | FileSystem | Dropbox | BoxNet | Job | GMail | GoogleDrive | SharePointLibrary | Discovery } 
[-SourceInput] <string> 
[[-Target] {PSTFile | Exchange | ExchangePubFolders | EnterpriseVault | FilesMsg | FilesEml | OneDrive | OneDriveBusiness | ReportOnly | Delete | FileSystem | Dropbox | BoxNet | GMail | GoogleDrive | SharePointLibrary }]
[[-TargetOutput] <string>] 
[-Batch <Batch>] 
[-BatchId <int>] 
[-RehydrationSource {EmailXtender | Zantaz | EnterpriseVault}] [-SourceOptions {UseEWS | UseMAPI | Ex2007 | Ex2010 | Ex2010sp1 | Ex2010sp2 | Ex2013 | Ex2013sp1 | Ex2016 | UseArchive | EVRehydrate | EVJournal | IncludeHold | KeepStub  | ZantasRehydrate | UseHostedArchive | IgnoreNetworkDrives | NoDiscoveryAnalysis | EnableEwsTrace | ExtractJournalAttach | UseStream | UseFullTextSearch | MoveItem | DetailedPfDiscovery | NoMAPI | ScanArchives | DropboxBusiness}] 
[-TargetOptions {Ex2007 | Ex2010 | Ex2010sp1 | Ex2010sp2 | Ex2013 | Ex2013sp1 | Ex2016 | UseArchive | EnqueueOnly | DeDupe | Bulk | UseHostedArchive | EnableEwsTrace | UseStream | MoveItem }] 
[-TargetFolder <string>] 
[-SourceFolder <string>] 
[-SourceParams <string>]
[-TargetParams <string>] 
[-MaxPSTSize <string>] 
[-SourceResource <string>] 
[-TargetResource <string>]
[-SourceAuthCode <string>] 
[-TargetAuthCode <string>] 
[-SourceRefreshToken <string>] 
[-TargetRefreshToken <string>] 
[-SourceFilter <string>] 
[-SourceExchServer <string>] 
[-TargetExchServer <string>] 
[-SourceCredential <pscredential>] 
[-TargetCredential <pscredential>] 
[-DateFrom <datetime>] 
[-DateTo <datetime>] 
[-Priority <int>]
[-FilterByJob <int>] 
[-FilterByQuery <string>] 
[-Force] 
[-JobConfig <IJobConfig>] 
[-SourceAutodiscoverUrl <string>] 
[-TargetAutodiscoverUrl <string>] 
[-Schedules <int[]>] 
[-Tags <string>] 
[-SourceEwsUrl <string>]
[-TargetEwsUrl <string>]  
[<CommonParameters>]

Parameters

    -Batch <Batch>
        Provide Batch from pipeline

        Required?                    false
        Position?                    Named
        Accept pipeline input?       true (ByValue)
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -BatchId <int>
        Specify BatchId

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -DateFrom <datetime>
        Specify date to migrate items from

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -DateTo <datetime>
        Specify date to migrate items to

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -FilterByJob <int>
        Specify the Job Id of a previous job to filter out of items discovered in this job

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -FilterByQuery <string>
        Specify a filter query string for this job.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -Force
        Use Force to skip any confirmation prompts.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -JobConfig <IJobConfig>
        Provide a job specific configuration.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -MaxPSTSize <string>
        Specify maximum output file size is megabytes, e.g. 1000

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      MaxFileSize
        Dynamic?                     false

    -Priority <int>
        Specify job priority as an integer (higher is better)

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -RehydrationSource <RehydrationType>
        Specify rehydration source for this job

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -Schedules <int[]>
        Associate this job with one or more schedules

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -Source <Source>
        Specify source system

        Required?                    true
        Position?                    0
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceAuthCode <string>
        OAuth 2 Auth Code from New-SMAuthToken

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceAutodiscoverUrl <string>
        Provide a specific Exchange autodiscover URL to use in place of the default autodetection.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceCredential <pscredential>
        Specify the source credentials to use

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceEwsUrl <string>
        Provide the source Exchange Web Service Url (O365 default https://outlook.office365.com/EWS/Exchange.asmx)

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceExchServer <string>
        Specify the source Exchange mailbox server name if not using Autodiscover

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceFilter <string>
        Specify the source email address to filter by

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceFolder <string>
        Specify root folder in source to search (default is the root folder)

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceInput <string>
        Specify source item identity or filename

        Required?                    true
        Position?                    1
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      SourceFile, SourceMailbox, SourcePst, SourceEvArchiveId, SourceEvADGroup,
        SourceZantasUser, SourceExPFServer, SourceDiscoveryPath
        Dynamic?                     false

    -SourceOptions <SourceOptions[]>
        Specify source options for this job

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceParams <string>
        Provide additional source parameters as a JSON string

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceRefreshToken <string>
        OAuth 2 Refresh Token

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -SourceResource <string>
        Resource Name for OAuth connections

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -Tags <string>
        Tag this job with #tag1,#tag2 style comma-separated tags

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -Target <Target>
        Specify target system

        Required?                    false
        Position?                    2
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetAuthCode <string>
        OAuth 2 Auth Code from New-SMAuthToken

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetAutodiscoverUrl <string>
        Provide a specific Exchange autodiscover URL to use in place of the default autodetection.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetCredential <pscredential>
        Specify the source credentials to use

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetEwsUrl <string>
        Provide the target Exchange Web Service Url (O365 default https://outlook.office365.com/EWS/Exchange.asmx)

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetExchServer <string>
        Specify the target Exchange mailbox server name if not using Autodiscover

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetFolder <string>
        Specify root folder in target to save under (default is the root folder)

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetOptions <TargetOptions[]>
        Specify source options for this job

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetOutput <string>
        Specify target item identity or filename

        Required?                    false
        Position?                    3
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      TargetFile, TargetMailbox, TargetPst
        Dynamic?                     false

    -TargetParams <string>
        Provide additional target parameters as a JSON string

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetRefreshToken <string>
        OAuth 2 Refresh Token

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    -TargetResource <string>
        Resource Name for OAuth connections

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

Inherited values

Some job configuration parameters are inherited from the Simply Migrate installation configuration.  (Get-SmConfig).  These parameters can be altered on a per job basis if desired, through the Set-SmJobConfig cmdlet, or combining New-SmJobConfig with the -JobConfig parameter while creating a job.
New Simply Migrate jobs will inherit the settings outlined in the Get-SmConfig parameters.
The following examples show how to change an existing job configuration and how to change a new job configuration to avoid inheritance.
This example shows how to set an existing job (JobId 1) to only effect items of IPM.Note message Class.

Set-SmJobConfig -JobId -IncludeMsgClass IPM.Note

The following example shows how to set the job configuration of a job during creation to override the MaxThreads global server setting.

New-SmJob -Source Exchange -SourceInput user@domain.com -SourceOptions Ex2010sp2, UseStream -JobConfig (New-SmJobConfig -MaxThreads 3) .....

Examples

New-SMJob is used to create Migration, Discovery or Reporting jobs. Alone, a job will not action the request. A Job needs to be added to a batch, andthe batch executed to run.

An example how to migrate a Mailbox to a PST File;

PS C:\Simply Migrate>$creds = Get-Credential
PS C:\Simply Migrate>New-SMJob -Source Exchange -SourceInput user@domain.com -SourceCredential $creds -Target PSTFile -TargetOutput C:\Folder\PSTFile.pst
JobId             : 201
BatchId           :
JobStatus         : Created
TimeStarted       :
TimeFinished      :
Source            : Exchange
Target            : PSTFile
SourceType        : {"srcmailbox":"user@domain.com"}
TargetType        : {"targpst":"C:\\Folder\\PSTFile.pst"}
DateFrom          : 1/1/1900 12:00:00 AM
DateTo            : 1/1/2100 12:00:00 AM
ItemsTotal        :
ItemsFailed       : 0
ItemsRemaining    : 0
FailedCount       : 0
Params            :
SMVersion         : X.X.X.XXXX
JobCreatedBy      : USER_CONTEXT_USERNAME
JobModifiedBy     :
ProcessingInBatch :
SourceParams      : {[srcmailbox, user@domain.com]}
TargetParams      : {[targpst, C:\Folder\PSTFile.pst]}
PercentComplete   : 0
SourceMailbox     : user@domain.com
TargetMailbox     : PSTFile.pst

Note: The above example creates a new Job. In itself this will NOT commence the task requested. The job should be added to a running batch to commence the task requested. This is further explained in the Start-SMBatch cmdlet help.

The command issued above can be broken down for explanation as follows.

The New-SMJob cmdlet is responsible for the generation of a new job. All subsequent paramters define the job being created.

The -Source defines the type of data being requested. In the above example this is Exchange Server mailbox data.

The -SourceInput takes in the parameter of what will actually be requested. In the above example, it is the UPN or email address of the users mailbox that will be used as a Source of data.

Depending on the deployment, it may be necessary to use different credentials than those being used by the powershell session. The above example, is taking a set of powershell credentials from the $creds variable, and using them to bind to the Source Mailbox.

The -Target parameter defines the type of data that you would like the resulting data to be targetted at. In the above example, this is a PST File.

The -TargetOutput parameter takes in a string that couples against the Target type. The above example shows this as being the path and name of the PST files you would ike the source data migrated to.

Source and Target Options

Within your Job, you can also define Source and Target Options that effect the processing of the jobs in a number of ways. The options are wide and varied, but fear not, they are explained in detail below.

PS C:\Simply Migrate>$creds = Get-Credential
PS C:\Simply Migrate>New-SMJob -Source Exchange -SourceInput user@domain.com -SourceCredential $creds -Target PSTFile -TargetOutput C:\Folder\PSTFile.pst -SourceOptions UseEWS,UseArchive
JobId             : 201
BatchId           :
JobStatus         : Created
TimeStarted       :
TimeFinished      :
Source            : Exchange
Target            : PSTFile
SourceType        : {"srcoption":"ews,archive","srcmailbox":"user@domain.com"}
TargetType        : {"targpst":"C:\\Folder\\PSTFile.pst"}
DateFrom          : 1/1/1900 12:00:00 AM
DateTo            : 1/1/2100 12:00:00 AM
ItemsTotal        :
ItemsFailed       : 0
ItemsRemaining    : 0
FailedCount       : 0
Params            :
SMVersion         : X.X.X.XXXX
JobCreatedBy      : USER_CONTEXT_USERNAME
JobModifiedBy     :
ProcessingInBatch :
SourceParams      : {[srcmailbox, user@domain.com]}
TargetParams      : {[targpst, C:\Folder\PSTFile.pst]}
PercentComplete   : 0
SourceMailbox     : user@domain.com
TargetMailbox     : PSTFile.pst

The above example will use an enhanced implementation of Exchange Web Services (EWS Option used) to read data from the Source, and also, only collect data from the Online Archive Mailbox (UseArchive option used). As you can see, multiple SourceOptions can be used in tandem with each other to achieve a large number of desired results.

The same system applied for TargetOptions. Specify the target options you wish to use, simply separating them with a comma.

Another useful set of options are the Exchange version options, used to specify the Exchange server version number; Ex2007, Ex2010, Ex2010sp1, Ex2010sp2, Ex2013, Ex2013sp1, Ex2016. As you can see each specific Exchange version can be specified (that is, those supported by EWS, see UseMapi option for pre-2007 Exchange!), however typically this is not required as if you leave the version out it will be auto-detected. When does this matter? If using a version pre-2013 either autodiscover may not be configured to provide the version schema information or it may just not work. In that case provide the version for best results.

NOTE: combinations of SourceOptions and TargetOptions can be used in a single job, and each of the available options is TAB completed for you, so you don’t have to worry about misspellings. It’s worth a note though, that Tab completion only works for Windows PowerShell Version 3 and above.