Public/Remove-MondayBoardItem.ps1
Function Remove-MondayBoardItem { <# .SYNOPSIS Remove (delete or archive) Monday.com board items .DESCRIPTION This function removes Monday.com board items using the Monday.com API. By default, items are permanently deleted. Use -Archive to archive items instead (soft delete). Multiple items can be removed in a single operation for efficiency. .PARAMETER ItemId The ID(s) of the item(s) to remove. Accepts single ID or array of IDs. .PARAMETER BoardId The ID of the board containing the item(s). This parameter is for reference and validation purposes only - the Monday.com API identifies items uniquely without requiring board context for removal operations. .PARAMETER Archive Archive the item(s) instead of permanently deleting them. Archived items can be restored from the Monday.com interface. .PARAMETER Confirm Prompt for confirmation before removing items (especially useful for permanent deletion) .PARAMETER PassThru Return information about the removed items .EXAMPLE Remove-MondayBoardItem -ItemId 1234567890 Permanently deletes the specified item .EXAMPLE Remove-MondayBoardItem -ItemId 1234567890 -BoardId 9876543210 Permanently deletes the specified item from a specific board .EXAMPLE Remove-MondayBoardItem -ItemId 1234567890 -Archive Archives the specified item (soft delete - can be restored) .EXAMPLE Remove-MondayBoardItem -ItemId @(1234567890, 1234567891, 1234567892) -Archive -Confirm:$false Archives multiple items without confirmation prompt .EXAMPLE Get-MondayBoardItem -BoardId 1234567890 | Where-Object {$_.name -like "*test*"} | Remove-MondayBoardItem Pipeline example: Permanently deletes all items with "test" in the name .EXAMPLE Remove-MondayBoardItem -ItemId 1234567890 -Archive -PassThru Archives an item and returns information about the removed item .INPUTS System.Int64 System.Int64[] .OUTPUTS System.String (default) PSCustomObject (when -PassThru is used) .NOTES - By default, items are permanently deleted and cannot be recovered - Use -Archive to archive items instead - archived items can be restored from the Monday.com web interface - Use -Confirm parameter for safety with permanent deletions - Monday.com API rate limits apply for bulk operations .LINK https://developer.monday.com/api-reference/reference/items #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')] Param( [Parameter(Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true, Position=0)] [Alias('Id')] [Int64[]]$ItemId, [Parameter(Mandatory=$false)] [Int64]$BoardId, [Parameter(Mandatory=$false)] [Switch]$Archive, [Parameter(Mandatory=$false)] [Switch]$PassThru ) Begin { Write-Verbose -Message "Starting $($MyInvocation.InvocationName)..." # Collection to hold all item IDs for batch processing $allItemIds = @() } Process { # Collect all item IDs for batch processing $allItemIds += $ItemId } End { try { Write-Verbose -Message "Processing removal of $($allItemIds.Count) item(s)" if ($allItemIds.Count -eq 0) { Write-Warning -Message "No items specified for removal" return } # Determine the action and mutation to use $action = if ($Archive) { "archive" } else { "permanently delete" } # Monday.com API mutations for item removal # For archiving: archive_item # For permanent deletion: delete_item $mutationName = if ($Archive) { "archive_item" } else { "delete_item" } # Process items individually or in batches depending on the API limitations $results = @() $successCount = 0 foreach ($singleItemId in $allItemIds) { # Confirm action if requested $target = "item $singleItemId" if ($PSCmdlet.ShouldProcess($target, $action)) { Write-Verbose -Message "$(if ($Archive) { 'Archiving' } else { 'Permanently deleting' }) item ID: $singleItemId" # Build the mutation - archive_item and delete_item only take item_id, not board_id $mutation = "mutation { $mutationName (item_id: $singleItemId) { id } }" if ($BoardId) { Write-Verbose -Message "Board ID provided: $BoardId (for context only, not used in mutation)" } Write-Verbose -Message "GraphQL Mutation: $mutation" # Execute the mutation try { $response = Invoke-MondayApi -Query $mutation if ($response.$mutationName -and $response.$mutationName.id) { $removedId = $response.$mutationName.id $successCount++ if ($PassThru) { # Create return object with removal details $result = [PSCustomObject]@{ ItemId = [Int64]$removedId Action = if ($Archive) { "Archived" } else { "PermanentlyDeleted" } Timestamp = Get-Date Recoverable = $Archive } $result.PSObject.TypeNames.Insert(0, 'Monday.RemovedItem') $results += $result } $actionPast = if ($Archive) { "archived" } else { "permanently deleted" } Write-Verbose -Message "Successfully $actionPast item $removedId" } else { Write-Warning -Message "No confirmation received for removal of item $singleItemId" } } catch { $errorMessage = "Failed to remove item ${singleItemId}: $($_.Exception.Message)" Write-Error -Message $errorMessage # Continue processing other items even if one fails continue } } else { Write-Verbose -Message "Skipped removal of item $singleItemId (user declined or WhatIf)" } } # Return results if ($PassThru) { return $results } else { # Return summary message based on actual success count if ($successCount -gt 0) { $actionPast = if ($Archive) { "archived" } else { "permanently deleted" } $summary = "Successfully $actionPast $successCount item(s)" Write-Verbose -Message $summary return $summary } else { return "No items were removed" } } } catch { $errorMessage = "Error during item removal operation: $($_.Exception.Message)" Write-Error -Message $errorMessage throw $_ } finally { Write-Verbose -Message "Ending $($MyInvocation.InvocationName)..." } } } |