Reworks 'spo file move' command to new endpoint. Closes #6153

pnp · Sep 20, 2024 · 9b28b0a · 9b28b0a
1 parent 9ee5f47
commit 9b28b0a
Show file tree

Hide file tree

Showing 8 changed files with 668 additions and 183 deletions.
diff --git a/docs/docs/cmd/spo/file/file-move.mdx b/docs/docs/cmd/spo/file/file-move.mdx
@@ -1,4 +1,6 @@
 import Global from '/docs/cmd/_global.mdx';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 # spo file move
 
@@ -31,11 +33,14 @@ m365 spo file move [options]
 `--nameConflictBehavior [nameConflictBehavior]`
 : Behavior when a file or folder with the same name is already present at the destination. Allowed values: `fail`, `replace`, `rename`. Defaults to `fail`.
 
-`--retainEditorAndModified`
-: Use this option to retain the editor and modified date. When not specified, these values are reset when moving to another library.
+`--includeItemPermissions`
+: Ensure that item-level permissions are preserved during the move.
 
 `--bypassSharedLock`
 : This indicates whether a file with a share lock can still be moved. Use this option to move a file that is locked.
+
+`--skipWait`
+: Don't wait for the copy operation to complete.
 ```
 
 <Global />
@@ -45,7 +50,6 @@ m365 spo file move [options]
 All file versions are retained while moving a file.
 
 When you specify a value for `nameConflictBehavior`, consider the following:
-
 - `fail` will throw an error when the destination file already exists.
 - `replace` will replace the destination file if it already exists.
 - `rename` will add a suffix (e.g. Document1.pdf) when the destination file already exists.
@@ -70,16 +74,119 @@ Move a file to another document library and replace a file with the same name.
 m365 spo file move --webUrl https://contoso.sharepoint.com/sites/project-x --sourceUrl "/Shared Documents/Report project-x.pdf" --targetUrl "/sites/project-x/My Documents" --newName Report.pdf --nameConflictBehavior replace
 ```
 
-Move a file referenced by its ID to another document library and retain editor and modified date.
+Move a file referenced by its ID to another document library and retain item-level permissions.
 
 ```sh
-m365 spo file move --webUrl https://contoso.sharepoint.com/sites/project-x --sourceId b8cc341b-9c11-4f2d-aa2b-0ce9c18bcba2 --targetUrl "/sites/project-x/My Documents" --retainEditorAndModified
+m365 spo file move --webUrl https://contoso.sharepoint.com/sites/project-x --sourceId b8cc341b-9c11-4f2d-aa2b-0ce9c18bcba2 --targetUrl "/sites/project-x/My Documents" --includeItemPermissions
 ```
 
 ## Response
 
-The command won't return a response on success.
+### Standard Response
+
+<Tabs>
+  <TabItem value="JSON">
+
+  ```json
+  {
+    "CheckInComment": "",
+    "CheckOutType": 2,
+    "ContentTag": "{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1,1",
+    "CustomizedPageStatus": 0,
+    "ETag": "\"{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1\"",
+    "Exists": true,
+    "IrmEnabled": false,
+    "Length": "5987",
+    "Level": 1,
+    "LinkingUri": null,
+    "LinkingUrl": "",
+    "MajorVersion": 1,
+    "MinorVersion": 0,
+    "Name": "Test1.docx",
+    "ServerRelativeUrl": "/sites/project-x/documents/Test1.docx",
+    "TimeCreated": "2022-10-30T10:16:18Z",
+    "TimeLastModified": "2022-10-30T10:16:18Z",
+    "Title": null,
+    "UIVersion": 512,
+    "UIVersionLabel": "1.0",
+    "UniqueId": "b2307a39-e878-458b-bc90-03bc578531d6"
+  }
+  ```
+
+  </TabItem>
+  <TabItem value="Text">
+
+  ```text
+  CheckInComment      :
+  CheckOutType        : 2
+  ContentTag          : {03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1,1
+  CustomizedPageStatus: 0
+  ETag                : "{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1"
+  Exists              : true
+  IrmEnabled          : false
+  Length              : 5987
+  Level               : 1
+  LinkingUri          : null
+  LinkingUrl          :
+  MajorVersion        : 1
+  MinorVersion        : 0
+  Name                : Test1.docx
+  ServerRelativeUrl   : /sites/project-x/documents/Test1.docx
+  TimeCreated         : 2022-10-30T10:16:18Z
+  TimeLastModified    : 2022-10-30T10:16:18Z
+  Title               : null
+  UIVersion           : 512
+  UIVersionLabel      : 1.0
+  UniqueId            : b2307a39-e878-458b-bc90-03bc578531d6
+  ```
+
+  </TabItem>
+  <TabItem value="CSV">
+
+  ```csv
+  CheckInComment,CheckOutType,ContentTag,CustomizedPageStatus,ETag,Exists,IrmEnabled,Length,Level,LinkingUri,LinkingUrl,MajorVersion,MinorVersion,Name,ServerRelativeUrl,TimeCreated,TimeLastModified,Title,UIVersion,UIVersionLabel,UniqueId
+  ,2,"{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1,1",0,"""{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1""",1,,5987,1,,,1,0,Test1.docx,/sites/project-x/documents/Test1.docx,2022-10-30T10:16:18Z,2022-10-30T10:16:18Z,,512,1.0,b2307a39-e878-458b-bc90-03bc578531d6
+  ```
+
+  </TabItem>
+  <TabItem value="Markdown">
+
+  ```md
+  # spo file move --webUrl "https://contoso.sharepoint.com/sites/IT" --sourceUrl "/Shared Documents/Document.docx" --targetUrl "/sites/project-x/Shared Documents"
+
+  Date: 10/3/2023
+
+  ## b2307a39-e878-458b-bc90-03bc578531d6
+
+  Property | Value
+  ---------|-------
+  CheckInComment |
+  CheckOutType | 2
+  ContentTag | {03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1,1
+  CustomizedPageStatus | 0
+  ETag | "{03E171B6-9DF2-46D9-A7A1-D5FA0BD23E4B},1"
+  Exists | true
+  ExistsAllowThrowForPolicyFailures | true
+  IrmEnabled | false
+  Length | 5987
+  Level | 1
+  LinkingUri | https://contoso.sharepoint.com/sites/project-x/shared%20documents/Document.docx?d=w59d4e6fcf6f94ce78bea0273cedb1a19
+  LinkingUrl | https://contoso.sharepoint.com/sites/project-x/shared documents/Document.docx?d=w59d4e6fcf6f94ce78bea0273cedb1a19
+  MajorVersion | 1
+  MinorVersion | 0
+  Name | Document.docx
+  ServerRelativeUrl | /sites/project-x/shared documents/Document.docx
+  TimeCreated | 2023-05-23T09:51:34Z
+  TimeLastModified | 2023-05-23T10:13:01Z
+  Title |
+  UIVersion | 1536
+  UIVersionLabel | 1.0
+  UniqueId | b2307a39-e878-458b-bc90-03bc578531d6
+  ```
+
+  </TabItem>
+</Tabs>
+
+### `skipWait` response
 
-## More information
-
-- Move items from a SharePoint document library: [https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc](https://support.office.com/en-us/article/move-or-copy-items-from-a-sharepoint-document-library-00e2f483-4df3-46be-a861-1f5f0c1a87bc)
+The command won't return a response on success.
diff --git a/docs/docs/v10-upgrade-guidance.mdx b/docs/docs/v10-upgrade-guidance.mdx
@@ -159,6 +159,24 @@ In the past versions of CLI for Microsoft 365, the command had no output. When u
 
 When using the [spo file copy](./cmd/spo/file/file-copy.mdx) command, please use the new command input. This means that you'll have to remove option `--resetAuthorAndCreated` from your scripts and automation tools.
 
+### Updated command `spo file move`
+
+Just like `spo file copy`, we have decided to move the [spo file move](./cmd/spo/file/file-move.mdx) command to a new endpoint. This change is necessary to ensure the command's functionality and reliability. Because of the new endpoint, the command input and output have changed.
+
+**Command options:**
+
+Unfortunately, we had to drop the `--retainEditorAndModified` options as it's no longer supported by the new endpoint. In return, we were able to add two new options:
+- `--includeItemPermissions`: Ensure that item-level permissions are preserved during the move.
+- `--skipWait`: Don't wait for the copy operation to complete.
+
+**Command output:**
+
+In the past versions of CLI for Microsoft 365, the command had no output. When using option `--nameConflictBehavior rename`, it's hard for the user to know what the actual name of the copied file is. With the new endpoint, the command now returns the file information about the destination file, providing you with all the info you need to execute other commands on this file.
+
+#### What action do I need to take?
+
+When using the [spo file move](./cmd/spo/file/file-move.mdx) command, please use the new command input. This means that you'll have to remove option `--retainEditorAndModified` from your scripts and automation tools.
+
 ### Removed `spo folder rename` alias
 
 The `spo folder rename` command was removed and replaced by the [spo folder set](./cmd/spo/folder/folder-set.mdx) command.

diff --git a/src/m365/spo/commands/file/file-copy.spec.ts b/src/m365/spo/commands/file/file-copy.spec.ts
@@ -303,6 +303,7 @@ describe(commands.FILE_COPY, () => {
         nameConflictBehavior: CreateCopyJobsNameConflictBehavior.Fail,
         bypassSharedLock: false,
         ignoreVersionHistory: false,
+        operation: 'copy',
         newName: undefined
       }
     ]);
@@ -334,6 +335,7 @@ describe(commands.FILE_COPY, () => {
         nameConflictBehavior: CreateCopyJobsNameConflictBehavior.Fail,
         bypassSharedLock: false,
         ignoreVersionHistory: false,
+        operation: 'copy',
         newName: undefined
       }
     ]);
@@ -368,6 +370,7 @@ describe(commands.FILE_COPY, () => {
         nameConflictBehavior: CreateCopyJobsNameConflictBehavior.Rename,
         bypassSharedLock: true,
         ignoreVersionHistory: true,
+        operation: 'copy',
         newName: 'Document-renamed.pdf'
       }
     ]);
@@ -400,6 +403,7 @@ describe(commands.FILE_COPY, () => {
         nameConflictBehavior: CreateCopyJobsNameConflictBehavior.Replace,
         bypassSharedLock: false,
         ignoreVersionHistory: false,
+        operation: 'copy',
         newName: 'Document-renamed.pdf'
       }
     ]);

diff --git a/src/m365/spo/commands/file/file-copy.ts b/src/m365/spo/commands/file/file-copy.ts
@@ -120,6 +120,10 @@ class SpoFileCopyCommand extends SpoCommand {
     this.types.boolean.push('bypassSharedLock', 'ignoreVersionHistory', 'skipWait');
   }
 
+  protected getExcludedOptionsWithUrls(): string[] | undefined {
+    return ['targetUrl', 'sourceUrl'];
+  }
+
   public async commandAction(logger: Logger, args: CommandArgs): Promise<void> {
     try {
       const sourceServerRelativePath = await this.getSourcePath(logger, args.options);
@@ -144,7 +148,8 @@ class SpoFileCopyCommand extends SpoCommand {
           nameConflictBehavior: this.getNameConflictBehaviorValue(args.options.nameConflictBehavior),
           bypassSharedLock: !!args.options.bypassSharedLock,
           ignoreVersionHistory: !!args.options.ignoreVersionHistory,
-          newName: newName
+          newName: newName,
+          operation: 'copy'
         }
       );