Run a Site Workflow with PowerShell and the Windows Task Scheduler

By: Chris Beckett   |   Comments   |   Related: > SharePoint

Problem

SharePoint 2010 introduced Site Workflows; workflows that can be manually started by a Site Administrator and are not bound to a specific list or library. Site Workflows can be useful for automating periodic administrative jobs, or extending business workflows with periodic batch processes. I like to think of them of being sort of like a timer job, but for a specific Site. The problem with Site workflows is that there is no out-of-box ability to schedule them.

Solution

The SharePoint Server Object API provides the ability to interact with Workflows via Server-side code. This makes it easy to interact with the Site Workflow Manager to start a workflow using PowerShell. In this tip, I am going to demonstrate how we can start a Site workflow using PowerShell that can be easily scheduled using the Windows Task Scheduler.

Create a PowerShell Script

The following script demonstrates how to start a workflow using the SharePoint Object API from PowerShell. For my tip, I have already created a simple Site workflow named "Sample Site Workflow". This script can be used to execute any Site workflow with default association data.

# SharePoint.Workflow.Start-SPSiteWorkflow

param (
   [string]$Url = "http://sharepoint/demos/workflow",
   [string]$Workflow = "Sample Site Workflow"
 )

Add-PSSnapin Microsoft.SharePoint.PowerShell -erroraction
SilentlyContinue
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint")

# get the workflow assocation from the target site/web
$site = Get-SPSite $Url
$culture = [System.Globalization.CultureInfo]::InvariantCulture
$wfAssociation = $site.RootWeb.WorkflowAssociations.GetAssociationByName($Workflow,$culture)

if ( $wfAssociation )
{
    # initialize and optionally update association data
    $assocData = $wfAssociation.AssociationData

    # start the workflow
    $wfRunOption = [Microsoft.SharePoint.Workflow.SPWorkflowRunOptions]::Asynchronous
    $site.WorkflowManager.StartWorkflow($site, $wfAssociation, $assocData,$wfRunOption)
}
else
{
    Write-Error "Workflow association not found on target web site."
}

Running a site workflow from code can be broken into 3 steps:

1. Get the Workflow Association on the target site from the SPWeb.WorkflowAssociations collection.
2. Build the Workflow Association Data string.
3. Start the workflow using the SPSite.WorkflowManager object.

The only tricky part of this code is the SPWorkflowAssocation.AssociationData property. This string value most commonly contains Xml representing serialized data from the Association form configured for the workflow. The appropriate elements and attributes consumed by the workflow are specific to the workflow, and how the form is serialized.

For SharePoint Designer 2010 workflows, this property will contain the Xml and default association parameter values based on the schema for the auto-generated InfoPath form. If you want to use the default association parameters, you can simply read the default value from the workflow association. This is what I have done in my sample.

Create a Windows Scheduled Task

Once we have completed and tested our PowerShell script, we can use the Windows Task Scheduler to automatically execute the PowerShell script as a single task, or on a repeating basis. For my sample, I will configure the workflow to run monthly.

1. Run the Windows Task Scheduler from Administrative Tools.
2. Click Create Basic Task... from the Action menu to start the wizard.
3. Enter a Name and Description for your scheduled task. Click Next.
4. Select "Monthly" as the Trigger from the options indicating when you want to task to start. Click Next.
5. Select "All Months", "1" for the days, and set the start date and time. Click Next.
6. Select "Start a program" for the Action. Click Next.
7. Enter "Powershell.exe" for the Program/script, and add the path and filename of the PowerShell script to run ("c:\powershell\Start-SPSiteWorkflow.ps1"). Click Next.
8. The completed task configuration should look like the image below. Click Finish

Next Steps

• Try creating and scheduling your own Site workflow.
• Try using PowerShell Remoting to schedule a Site workflow to run on a remote SharePoint server.
• Check these other tips:
  • Custom PowerShell Modules for SharePoint
  • Setting up PowerShell for SharePoint
  • Using the Windows Scheduler to run a SharePoint PowerShell Backup Script

About the author

Chris Beckett is a Business Solutions Architect, Mentor and Trainer with 20 years of experience.

This author pledges the content of this article is based on professional experience and not AI generated.

View all my tips