Adds new command spo listitem retentionlabel ensure. Closes pnp#4158

Author: martinlingstuyl

docs/docs/cmd/spo/listitem/listitem-retentionlabel-ensure.md

@@ -0,0 +1,58 @@
+# spo listitem retentionlabel ensure
+
+Apply a retention label to a list item
+
+## Usage
+
+```sh
+m365 spo listitem retentionlabel ensure [options]
+```
+
+## Options
+
+`-u, --webUrl <webUrl>`
+: URL of the site where the retentionlabel from a listitem to apply is located
+
+`--listItemId <listItemId>`
+: The ID of the list item for which the retention label should be applied.
+
+`--listId [listId]`
+: ID of the list where the retention label should be applied. Specify either `listTitle`, `listId` or `listUrl`
+
+`--listTitle [listTitle]`
+: Title of the list where the retention label should be applied. Specify either `listTitle`, `listId` or `listUrl`
+
+`--listUrl [listUrl]`
+: Server- or site-relative URL of the list. Specify either `listTitle`, `listId` or `listUrl`
+
+`-n, --name [name]`
+: The name of the retention label. Specify either `name` or `id`.
+
+`-i, --id [id]`
+: The id of the retention label. Specify either `name` or `id`.
+
+--8<-- "docs/cmd/_global.md"
+
+## Examples
+
+Applies the retention label _Some label_ to a list item in a given site based on the list id and label name
+
+```sh
+m365 spo listitem retentionlabel ensure --webUrl https://contoso.sharepoint.com/sites/project-x --listId 0cd891ef-afce-4e55-b836-fce03286cccf --listItemId 1 --name 'Some label'
+```
+
+Applies a retention label to a list item in a given site based on the list title and label id
+
+```sh
+m365 spo listitem retentionlabel ensure --webUrl https://contoso.sharepoint.com/sites/project-x --listTitle 'List 1' --listItemId 1 --id '7a621a91-063b-461b-aff6-d713d5fb23eb'
+```
+
+Applies the retention label _Some label_ to a list item in a given site based on the server relative list url
+
+```sh
+m365 spo listitem retentionlabel ensure --webUrl https://contoso.sharepoint.com/sites/project-x --listUrl /sites/project-x/lists/TestList --listItemId 1 --name 'Some label'
+```
+
+## Response
+
+The command won't return a response on success.

docs/mkdocs.yml

@@ -489,6 +489,7 @@ nav:
         - listitem remove: cmd/spo/listitem/listitem-remove.md
         - listitem attachment list: cmd/spo/listitem/listitem-attachment-list.md
         - listitem batch add: cmd/spo/listitem/listitem-batch-add.md
+        - listitem retentionlabel ensure: cmd/spo/listitem/listitem-retentionlabel-ensure.md
         - listitem retentionlabel remove: cmd/spo/listitem/listitem-retentionlabel-remove.md
         - listitem roleassignment add: cmd/spo/listitem/listitem-roleassignment-add.md
         - listitem roleassignment remove: cmd/spo/listitem/listitem-roleassignment-remove.md

src/m365/spo/commands.ts

@@ -147,6 +147,7 @@ export default {
   LISTITEM_RECORD_UNDECLARE: `${prefix} listitem record undeclare`,
   LISTITEM_RECORD_UNLOCK: `${prefix} listitem record unlock`,
   LISTITEM_REMOVE: `${prefix} listitem remove`,
+  LISTITEM_RETENTIONLABEL_ENSURE: `${prefix} listitem retentionlabel ensure`,
   LISTITEM_RETENTIONLABEL_REMOVE: `${prefix} listitem retentionlabel remove`,
   LISTITEM_ROLEASSIGNMENT_ADD: `${prefix} listitem roleassignment add`,
   LISTITEM_ROLEASSIGNMENT_REMOVE: `${prefix} listitem roleassignment remove`,

src/m365/spo/commands/listitem/ListItemRetentionLabel.ts

@@ -0,0 +1,8 @@
+export interface ListItemRetentionLabel {
+  complianceTag: string;
+  isTagPolicyHold: boolean;
+  isTagPolicyRecord: boolean;
+  isEventBasedTag: boolean;
+  isTagSuperLock: boolean;
+  isUnlockedAsDefault: boolean;
+} 

src/m365/spo/commands/listitem/SiteRetentionLabel.ts

@@ -0,0 +1,26 @@
+export interface SiteRetentionLabel {
+  AcceptMessagesOnlyFromSendersOrMembers: boolean;
+  AccessType?: any;
+  AllowAccessFromUnmanagedDevice?: any;
+  AutoDelete: boolean;
+  BlockDelete: boolean;
+  BlockEdit: boolean;
+  ComplianceFlags: number;
+  ContainsSiteLabel: boolean;
+  DisplayName: string;
+  EncryptionRMSTemplateId?: any;
+  HasRetentionAction: boolean;
+  IsEventTag: boolean;
+  MultiStageReviewerEmail?: any;
+  NextStageComplianceTag?: any;
+  Notes?: any;
+  RequireSenderAuthenticationEnabled: boolean;
+  ReviewerEmail?: any;
+  SharingCapabilities?: any;
+  SuperLock: boolean;
+  TagDuration: number;
+  TagId: string;
+  TagName: string;
+  TagRetentionBasedOn: string;
+  UnlockedAsDefault: boolean;
+}