Managing SharePoint List Workflow Associations using PnP PowerShell

Workflows in SharePoint automate business processes such as approvals, document reviews, and notifications. PnP PowerShell provides a way to manage workflow associations in SharePoint Online lists, allowing users to list, associate, or remove workflows efficiently.

What You’ll Learn:

✔️ How to connect to SharePoint Online
✔️ How to list all workflows associated with a SharePoint List
✔️ How to associate a workflow with a SharePoint List
✔️ How to remove a workflow association from a SharePoint List

Prerequisites

Before proceeding, ensure that:
PnP PowerShell is installed
You have SharePoint Admin or Site Owner permissions
You know the SharePoint site URL and list name

Step 1: Install and Import PnP PowerShell

If PnP PowerShell is not installed, install it using:

Install-Module -Name PnP.PowerShell -Scope CurrentUser -AllowClobber -Force

Then, import the module:

Import-Module PnP.PowerShell

PnP PowerShell is ready!

Step 2: Connect to SharePoint Online

To connect to a SharePoint Online site, run:

# Connect to SharePoint Online
Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive

🔹 Replace "yourtenant" with your SharePoint tenant name
🔹 Replace "yoursite" with your actual site name

Connected successfully!

Step 3: List All Workflow Associations for a SharePoint List

To get a list of workflows associated with a specific list, use:

# Define variables
$listName = "Documents"  # Change to your list name

# Get workflows associated with the list
$workflows = Get-PnPList -Identity $listName | Select -ExpandProperty WorkflowAssociations

# Display the workflows
$workflows | ForEach-Object {
    Write-Host "Workflow Name: $($_.Name), Status: $($_.Enabled)"
}

Lists all workflows associated with the specified list!

Step 4: Associate a Workflow with a SharePoint List

To add a workflow to a SharePoint List, use:

# Define variables
$listName = "Documents"  # Change to your list name
$workflowName = "Approval Workflow"  # Change to your workflow name

# Get the workflow template
$workflowTemplate = Get-PnPWorkflowDefinition | Where-Object { $_.DisplayName -eq $workflowName }

if ($workflowTemplate) {
    # Associate the workflow with the list
    Add-PnPWorkflowAssociation -List $listName -Name $workflowName -Definition $workflowTemplate
    Write-Host "Workflow '$workflowName' associated with list '$listName'."
} else {
    Write-Host "Workflow '$workflowName' not found!"
}

Workflow successfully associated with the SharePoint List!

Step 5: Remove a Workflow Association from a SharePoint List

To remove a workflow from a SharePoint List, use:

# Define variables
$listName = "Documents"  # Change to your list name
$workflowName = "Approval Workflow"  # Change to your workflow name

# Get the workflow association
$workflow = Get-PnPList -Identity $listName | Select -ExpandProperty WorkflowAssociations | Where-Object { $_.Name -eq $workflowName }

if ($workflow) {
    # Remove the workflow association
    Remove-PnPWorkflowAssociation -List $listName -Identity $workflow
    Write-Host "Workflow '$workflowName' removed from list '$listName'."
} else {
    Write-Host "Workflow '$workflowName' not found on list '$listName'."
}

Workflow successfully removed from the SharePoint List!

Common Errors & Solutions

Error	Cause	Solution
`Workflow not found`	Incorrect workflow name	Use `Get-PnPWorkflowDefinition` to list available workflows
`Access Denied`	Insufficient permissions	Ensure you have Admin or Site Owner rights
`List not found`	Incorrect list name	Verify the list name using `Get-PnPList`