The CreateCopyJobs API, copy or move SharePoint files or folders

Move a file using the CreateCopyJobs APIs

First step is to send post request with payload about the file to the CreateCopyJobs endpoint i.e. /_api/site/CreateCopyJobs (POST)

Here is how my post request payload looks like

Here is the response we get from the HTTP call

Once the request is sent, it goes in a queue and we can check the status of the queue by calling another SharePoint endpoint i.e. /_api/site/GetCopyJobProgress (GET).

So, we have to construct a request so the /_api/site/GetCopyJobProgress to call the right Azure queue instance using the response data from the CreateCopyJobs APIs above. Here is the JSON payload for the /_api/site/GetCopyJobProgress GET request. We can see how the data is mapped comparing the above response data with the below request payload:

From the payload is very obvious that my copy job was hosted to a server where the JobQueueUri is the server, then I have the Id or the job JobId and also a key EncryptionKey to be able to authenticate and check the job status.

GetCopyJobProgress API - Different statuses and responses

So, we have to poll the GetCopyJobProgress API until we get job status success, but here is first the response you'd expect when the job is in progress.

Job in the queue, the "JobState" is 4

From my observation when you get "JobState" = 4, then it is still in the queue and in progress.

Note, pay attention on the results node, sometimes there is a log of actions happened and that information might be of interest to you.

Job success, the "JobState" is 0, but should not have any errors in the results node of the response

Job done with errors, the "JobState" is still 0, but there is a JobError in the results node of the response

Here is the response data and the "JobState" is still 0, but we have to pay attention on the results log where we have errors. So, "JobState" equals 0, does not mean successfully completed.

Note, we will have to parse the result node to JSON and try find any errors. In this scenario we have the following error: "A file or folder with the name 'Test.docx' already exists at the destination."

Here is the MigrationJobState from the Microsoft.SharePoint.Client DLL:

Options that we can specify in a CreateCopyJobs request

I used the SharePoint OData metadata and the CSOM dll to get some more information and following options are available at the moment:

Here is the enum for NameConflictBehavior pulled from the Microsoft.SharePoint.Client dll:

AllowSchemaMismatch: allows file move with missing or mismatched field definition on the destination list for source field. More clarification bellow.

IgnoreVersionHistory: ignores version history when moves the file and will create only one version (1.0) on the target location

IsMoveMode: true moves the file, false creates a copy of the file

NameConflictBehavior: 1 = REPLACE and 2 = KEEP BOTH

Copy a file using the CreateCopyJobs API

Copying a file follows the same rules to call CreateCopyJobs endpoint i.e. /_api/site/CreateCopyJobs (POST), but the payload send to the API has set the "IsMoveMode" to false or not specified at all. Here is how my post request payload looks like:

That is followed by polling the /_api/site/GetCopyJobProgress to get the status of the job. The same process as the described above for file move.

Copy or move a folder using the CreateCopyJobs API

The exact same process applies when moving or copying folder, but the request payload differs where we have to specify folder instead of file. Here is an example:

Important: Folder cannot be moved using MigrationNameConflictBehavior = Replace, but just with MigrationNameConflictBehavior = Rename

Tips on how to solve common errors that might popup during move or copy

How to solve GetCopyJobProgress error: A file or folder with the name 'Test.docx' already exists at the destination

There is "NameConflictBehavior" option that can be specified with the payload to prevent conflict between the file to be moved and a target file with the same name. Allowed values are 1 = REPLACE and 2 = KEEP BOTH.

CreateCopyJobs sends response error 500, mismatched field definition on the destination list

So, the CreateCopyJobs will send back immediately response 500 when there is a list, field schema definition mismatch. For example, you are trying to copy file with content type 'Picture', but the content type 'Picture' is not available on the target library then the API will error because there might be a possible data loss and will not proceed. Here is the response payload:

If you still want to proceed and move the document you can create another /_api/site/CreateCopyJobs (POST) request, but specify in the payload "AllowSchemaMismatch":true. Example:

Is the CreateCopyJobs API supported?

Yes and no, maybe not yet :) . Well the SharePoint Client Side Object DLL has it and we can use it in backed solutions, but in the same time is not officially documented which means Microsoft might not support you in a case of failure.

Benefits of the CreateCopyJobs API

Performs copy or move on Azure servers, so no download-upload stream is happening from the machine where the script is executed.

Built-in retry mechanisms so we do not have to implement additional logic for that.

It is cross site collection, including OneDrive for Business. Previously, we had copy move util API working only within the site collection of the file to be copied.

It can copy and move ASPX pages from SitePages library to SitePages library although it is not exposed form the SitePages library UI.

Batch jobs are possible, but not covered in this blog.

Conclusion

Well, I find it handy and it is one API for copy and move together. I will keep an eye on the API and how it evolves in future. The previous time I had a look there wasn't an option for NameConflictBehavior and this was few months ago. That means that they rapidly update it with new features.