How to: Deploy a Project Server Workflow

Article
07/28/2014

Applies to: Office 2010 | Project 2010 | Project Server 2010 | SharePoint Server 2010

In this article
Creating a Project Server Workflow Solution Package
Installing a Workflow Solution Package
Uninstalling a Workflow Solution Package
Alternate Procedure for Updating a Workflow Assembly
Configuring a Workflow on a Farm

You can use a SharePoint solution package to install Microsoft Project Server 2010 workflows on production servers in a SharePoint farm. You can separately activate a workflow for each instance of Project Web App.

Note

There will be several tools for workflows available for Project Server 2010. The tools help to create simple (non-branching) workflows, import and export enterprise project types (EPTs), associate EPTs with workflows, and visualize workflows on Project Server. The tools will be published on MSDN Code Gallery (https://code.msdn.microsoft.com/).

The procedures in this article use the BranchingWorkflow sample described in How to: Create a Branching Workflow. You should install and test workflows on a test installation of Project Server before deploying them to a production server. For more information, see How to: Install and Test a Project Server Workflow.

This article includes the following sections:

Creating a Project Server Workflow Solution Package
Installing a Workflow Solution Package
Uninstalling a Workflow Solution Package
Complete Script Example for Managing a Workflow Solution
Alternate Procedure for Updating a Workflow Assembly
Configuring a Workflow on a Farm

Creating a Project Server Workflow Solution Package

By using Microsoft Visual Studio 2010, you can easily create a SharePoint solution package (.wsp file) for a Project Server workflow. When you develop a workflow, Visual Studio 2010 creates the Features and Package folders in the workflow project (Figure 1). The Features folder includes the default Feature1 feature.

Note

The top-level folder structure includes the Features folder and the Package folder, which contain the SharePoint Feature and package definitions. Because Visual Studio 2010 uses the folder structure to match SharePoint directories on the target computer and to build SharePoint solution files, the top-level folder structure should not be changed.

Procedure 1. To create a workflow solution package

On a Project Server computer, run Visual Studio 2010 as an administrator, and then open a Project Server workflow solution. For example, open the BranchingWorkflow solution.

Tip

You can open a workflow solution and create a SharePoint solution package on another Project Server computer, where Visual Studio 2010 is not configured with the Project Server – Workflow and SharePoint Server – Workflow tabs in the Toolbox, as described in How to: Configure Visual Studio 2010 for a Project Server Workflow. The workflow activities in the Toolbox tabs are necessary only if you need to add an activity.
Optional: Modify the feature title, description, or name:
1. Expand the Features folder. Right-click Feature1, and then click View Designer.
2. On the Feature1.feature tab, the default description in the Description text box is My SharePoint Workflow Feature. For example, change the description to Branching Workflow example for testing, and then save and close the Feature Designer.
3. You can also rename the default Feature1 feature. For example, right-click Feature1 in Solution Explorer, and then click Rename. When you rename the Feature1 node, Visual Studio also renames the subnodes. The code in this article uses the Feature1 name.
Optional: Add items to the package manifest. For example, add images or icons that can be used in the enterprise project type (EPT) drop-down list or the Project Web App site collection feature list:
1. In Solution Explorer, right-click the BranchingWorkflow project, click Add, and then click SharePoint Mapped Folder.
2. In the Add SharePoint Mapped Folder dialog box, expand the TEMPLATE folder, and then click IMAGES. Click OK.
3. In Solution Explorer, right-click the IMAGES1 folder, click Add, click Existing Item, and then navigate to the directory that contains the images you want to import. For example, import P14SDK.gif and P14SDK_small.gif from the Project Server 2010 SDK download.
Verify the package contents before building the package file:
1. In Solution Explorer, expand the Package folder, and then double-click the Package.package node to open the Package Designer (Figure 1).
2. Leave the Reset Web Server check box clear. It is not necessary to restart IIS when you first install the package. When you upgrade the package, you can restart the Project Server Queue service, restart the SharePoint Timer service, and reset IIS manually or by using a script.
  
  Figure 1. Using the Package Designer in Visual Studio 2010
3. On the Package.package tab, if you imported any images, verify that the package includes the IMAGES1 (BranchingWorkflow) item and the image files.
4. At the bottom of the Package.package tab, click Manifest. In Preview of Packaged Manifest, verify that the manifest includes the workflow assembly and deployment target, any optional template files you added, and the feature manifest. For example, the BranchingWorkflow manifest that includes the two optional image files shows the following.
```
<Solution xmlns="https://schemas.microsoft.com/sharepoint/" 
    SolutionId="57e93e21-e17f-4bfa-8630-b0dde64ea029" SharePointProductVersion="14.0">
  <Assemblies>
    <Assembly Location="BranchingWorkflow.dll" DeploymentTarget="GlobalAssemblyCache" />
  </Assemblies>
  <TemplateFiles>
    <TemplateFile Location="IMAGES\P14SDK.gif" />
    <TemplateFile Location="IMAGES\P14SDK_small.gif" />
  </TemplateFiles>
  <FeatureManifests>
    <FeatureManifest Location="BranchingWorkflow_Feature1\Feature.xml" />
  </FeatureManifests>
</Solution>
```
  When you install the workflow package on another Project Server computer, you need to know the feature manifest location, for example, BranchingWorkflow_Feature1.
Build the solution package file. In Solution Explorer, right-click the BranchingWorkflow project, and then click Package.

Optional: Verify the contents of the BranchingWorkflow.wsp file:

In the bin\Debug subfolder of the Visual Studio solution, make a copy of the BranchingWorkflow.wsp file.

Change the file extension to .cab, and then open BranchingWorkflow_Copy.cab by using WinZip. Table 1 shows the files and subdirectories in the package.

Table 1. Files and directories in the workflow solution package

Name	Path
BranchingWorkflow.dll
manifest.xml
Feature.xml	BranchingWorkflow_Feature1\
Elements.xml	BranchingWorkflow_Feature1\BranchingWorkflow\
(optional image files)	images\

Note

The Feature1.Template.xml file in the Visual Studio solution shows that the Feature element is missing the Id attribute. However, when you run the Package command, Visual Studio adds the required attributes for the Feature element when it creates the Feature.xml file.

The generated Feature.xml file that is in the BranchingWorkflow.wsp solution package includes the Id attribute and Scope attribute of the Feature element:

<?xml version="1.0" encoding="utf-8"?>
<Feature xmlns="https://schemas.microsoft.com/sharepoint/" Title="BranchingWorkflow Feature1" 
Description="Branching Workflow example for testing" Id="6de058f5-92bb-4c32-82f3-ac1e1841f89b" Scope="Site">
  <Properties>
    <Property Key="GloballyAvailable" Value="true" />
  </Properties>
  <ElementManifests>
    <ElementManifest Location="BranchingWorkflow\Elements.xml" />
  </ElementManifests>
</Feature>

The BranchingWorkflow.wsp file can be copied to other Project Server computers for installation.

Installing a Workflow Solution Package

You can use Windows PowerShell commands to install and update a workflow solution package in a Project Web App site collection. You must install the package for each instance of Project Web App where you want the workflow to be available.

Procedure 2 shows the individual Windows PowerShell commands required to install the workflow. For a script that installs, removes, or updates a workflow package, see the Complete Script Example for Managing a Workflow Solution section.

Procedure 2. To install a workflow solution package

Copy the workflow package to another Project Server computer. For example, create the PSScripts file share on the ServerName computer, and then copy BranchingWorkflow.wsp to \\ServerName\PSScripts.
On the Windows Start menu on the ServerName computer, click the Microsoft SharePoint 2010 Products folder, right-click SharePoint 2010 Management Shell, and then click Run as administrator.

Tip

If you want to edit a script or run SharePoint cmdlets in the Windows PowerShell integrated scripting environment (ISE), you must register the SharePoint snap-in in the current ISE session or add the following command to one of the Windows PowerShell profiles. For information about creating and modifying a profile, see Windows PowerShell Profiles in Windows PowerShell Help, and then add the command to the profile (commands are not case-sensitive).

The following command is not necessary in the SharePoint 2010 Management Shell; it already has the SharePoint snap-in added.
```
Add-PSSnapin Microsoft.SharePoint.PowerShell; Get-PSSnapin
```
Run the following command, which imports the solution to the SharePoint farm:
```
Add-SPSolution -LiteralPath C:\PSScripts\BranchingWorkflow.wsp
```
For more information about the Add-SPSolution cmdlet, for example, type Get-Help Add-SPSolution in the Windows PowerShellcommand window.

Tip

When you run the command in the SharePoint 2010 Management Shell window, you are asked to confirm the action. To suppress the confirmation, add the -Confirm:$false argument to the command.
The following command installs the solution in the Project Web App site collection:
```
Install-SPSolution -Identity BranchingWorkflow.wsp -GacDeployment
```
Note

The Install-SPSolution command starts a SharePoint Timer process. If the install process is not complete, the Enable-SPFeature command in the following step shows an error.
The following command enables the workflow in the Project Web App site collection that is named pwa on the ServerName computer:
```
Enable-SPFeature -Identity BranchingWorkflow_Feature1 -Url https://ServerName/pwa
```
The Enable-SPFeature command activates the feature. To see the results, click Site collection features on the Project Web App Site Settings page. The Features page (https://ServerName/PWA/_layouts/ManageFeatures.aspx?Scope=Site) shows that BranchingWorkflow Feature1 is active.
To enable Project Web App to create workflow instances, open Site Settings in Project Web App, click Workflow Settings, and then click Add a workflow. Alternately, you can open the Add a Workflow page with the following script:
```
$ie = 'C:\Program Files (x86)\Internet Explorer\iexplore.exe'
& $ie "https://ServerName/pwa/_layouts/AddWrkfl.aspx"
```
On the Add a Workflow page, click the BranchingWorkflow – BranchingWorkflow template, type Branching Workflow for the name, and then click OK.

The Branching Workflow example is now ready for use in Project Web App. To create an EPT and use the workflow, see the procedures in How to: Install and Test a Project Server Workflow.

Installation of the workflow solution adds files in the following places:

The Feature.xml and Elements.xml files are installed in the [Program Files]\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\FEATURES\ directory. The example creates the BranchingWorkflow_Feature1 subdirectory.
The optional images are installed in the [Program Files]\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\IMAGES\BranchingWorkflow\ directory.
The BranchingWorkflow.dll assembly is installed in the global assembly cache. See [Windows]\assembly.

Uninstalling a Workflow Solution Package

The Windows PowerShell cmdlets that are used to uninstall a solution package are the opposite of the cmdlets for installation, and performed in reverse order.

Procedure 3. To uninstall a workflow solution package

Disable the workflow feature with the following command:
```
Disable-SPFeature -Identity BranchingWorkflow_Feature1 -Url https://ServerName/pwa
```
The Disable-SPFeature command deactivates the feature. To see the results (Figure 2), click Site collection features on the Project Web App Site Settings page to open the Features page (https://ServerName/PWA/_layouts/ManageFeatures.aspx?Scope=Site).

Figure 2. The Features page shows the BranchingWorkflow Feature1 is not active

Uninstall the solution, as follows:

Uninstall-SPSolution -Identity BranchingWorkflow.wsp

Remove the solution:
```
Remove-SPSolution -Identity BranchingWorkflow.wsp
```
Note

The Uninstall-SPSolution command starts a SharePoint Timer process. If the uninstall process is not complete, the Remove-SPFeature command shows the following error:

Remove-SPSolution : The solution "branchingworkflow.wsp" has been deployed in the farm. Please retract the deployment before removing the solution. You can also use the -override parameter to forcibly remove the solution, but you will not be able to retract the solution deployment.
To disable Project Web App from creating workflow instances, open Site Settings in Project Web App, click Workflow Settings, and then click Remove a workflow. Alternately, you can open the Remove a Workflow page by using the following script:
```
$ie = 'C:\Program Files (x86)\Internet Explorer\iexplore.exe'
& $ie "https://ServerName/pwa/_layouts/RemWrkfl.aspx"
```
On the Remove a Workflow page, click the Remove option button for the BranchingWorkflow – BranchingWorkflow template, and then click OK.

The files are uninstalled from the three locations previously described.

Complete Script Example for Managing a Workflow Solution

The Install-PJWorkflow.ps1 script can install, remove, or update a workflow. Copy and save the script in a file named Install-PJWorkflow.ps1, for example in the C:\PSScripts directory. To run or edit the script in the Windows PowerShell ISE editor, see the tip in step 2 of Procedure 2.

To use the script, run SharePoint 2010 Management Shell as an administrator. For example, run the following commands to install the BranchingWorkflow.wsp package on the local Project Server computer. The backtick character (grave accent or ASCII 96) in the Install-PJWorkflow command is an escape character for line continuation.

cd C:\PSScripts
.\Install-PJWorkflow E:\Project\WorkflowExamples\BranchingWorkflow.wsp `
   https://ServerName/pwa BranchingWorkflow_Feature1 install

Because the arguments are named parameters, you can also use parameter names in the command. The following example uses the –action named parameter:

.\Install-PJWorkflow E:\Project\WorkflowExamples\BranchingWorkflow.wsp `
   https://ServerName/pwa BranchingWorkflow_Feature1 -action install

Warning

The Install-PJWorkflow.ps1 script works if the workflow feature is active only on the Project Web App site that you specify. If there are two or more sites in the SharePoint farm where the workflow is active, you must deactivate the feature on both sites before you retract the solution.

The Start-Sleep cmdlet uses the $sleepTime variable to set a sleep time of five seconds between some of the commands. The Install-SPSolution and Uninstall-SPSolution cmdlets start a SharePoint timer job. If the timer job is not complete, you get an error message when you run Enable-SPFeature or Remove-SPSolution. The script finds the timer job and waits for it to complete.

If Windows Internet Explorer is not installed on the C: drive, change the value of the $ie variable.

########################################################################################
## Install-PJWorkflow.ps1
## Windows PowerShell script for installing, removing, and updating a Project Server  
## workflow solution file. Run as administrator.
## Requires that the workflow is active on only one Project Web App site in the farm.
## Arguments:
##   wspFile     --.WSP file name and full path.
##   serverUrl   -- URL of Project Web App.
##   featureName -- Workflow name and SharePoint Feature name, 
##                  for example: MyWorkflow_Feature1.
##   action      -- Specifies whether to install, remove, or update a workflow with 
##                  the same feature name. 
##                  Valid values: install, remove, or update
## Example: 
##   Install-PJWorkflow C:\Test\TestWF.wsp https://server/pwa MyWorkflow_Feature1 install
#########################################################################################

param($wspFile, $serverUrl, $featureName, $action)

Set-StrictMode -version 2.0
[bool]$argErr = $false
[bool]$install = $false
[bool]$remove = $false

# Set the path to Internet Explorer.
$ie = 'C:\Program Files (x86)\Internet Explorer\iexplore.exe'
[int]$sleepTime = 5     # Sleep for five seconds.

if ($wspFile -eq $null) 
{ 
    $argErr = $true 
}
else
{
    $inFile = New-Object System.IO.FileInfo $wspFile
    
    if (-not $infile.Exists)
    {
        Write-Error -message "File does not exist: $wspfile" -category InvalidArgument
        $argErr = $true 
    }
}

if ($serverUrl -eq $null) 
{ 
    $argErr = $true 
}
else
{
    if (-not (Get-SPSite $serverUrl))
    {
        Write-Host "Site URL is not valid: $serverUrl"
        $argErr = $true
    }
}

if ($featureName -eq $null) 
{ 
    $argErr = $true 
}

if ($action -eq $null)
{
        Write-Host "No action specified."
        $argErr = $true
}
else
{
    [string]$actionL = $action.ToLower()
    
    switch($actionL)
    {
        { $_ -eq "update" }   { $install = $true; $remove = $true; break }
        { $_ -eq "install" }  { $install = $true; break }
        { $_ -eq "remove" }   { $remove = $true; break }
        default               { Write-Host "Invalid action: $action "; $argErr = $true }
    }
}

if ($argErr)
{ 
    Write-Host "Usage: Install-PJWorkflow wspFile serverUrl featureName -action (update | install | remove)"
    Write-Host "Example: `n`tInstall-PJWorkflow C:\Test\TestWF.wsp https://server/pwa MyWorkflow_Feature1" install
    exit
}

# Wait for the SharePoint timer job name that contains \"solution-deployment\".
function Wait4Timer
{    
    Write-Host -NoNewLine "`nFinding timer job"
    
    # The language-dependent display name of the timer job contains \"Solution Retraction\". 
    # while (($jd = Get-SPTimerJob | ?{ $_.DisplayName -like \"*Solution Retraction*\"+$fileName+\"*\" }) -eq $null)
    while (($jd = Get-SPTimerJob | ?{ $_.Name -like "*solution-deployment*" + $fileName + "*" }) -eq $null) 
    {
        Write-Host -NoNewLine .
        Start-Sleep -Seconds 1
    }
    $jdName = $jd.Name
    Write-Host "`njob: $jdName"
    Write-Host -NoNewLine Waiting to finish
    
    while ((Get-SPTimerJob $jdName) -ne $null) 
    {
       Write-Host -NoNewLine .
       Start-Sleep -Seconds 1
    }
    
    Write-Host
    $jd.HistoryEntries | %{ Write-Host job history: $_.Status }
    Write-Host
} # End of function Wait4Timer.

$fileName = $inFile.Name
write-host "Using $fileName; action = $action`n"

if ($remove)
{
    # Remove the workflow feature.
    
    # Set-PSDebug -Step
    
    Write-Host "Running Disable-SPFeature for $featureName on $serverUrl ..."
    Disable-SPFeature -Identity $featureName -Url $serverUrl -Confirm:$false
    Start-Sleep -Seconds $sleepTime
    
    Write-Host "Running Uninstall-SPSolution for $fileName ..."
    Uninstall-SPSolution -Identity $fileName -Confirm:$false
    
    Wait4Timer
    
    Write-Host "Running Remove-SPSolution for $fileName ..."     
    Remove-SPSolution -Identity $fileName -Confirm:$false
    Start-Sleep -Seconds $sleepTime
    
    # Restart services.
    Write-Host "Restarting services ..."

    Restart-Service -DisplayName "SharePoint 2010 Timer"
    Restart-Service -DisplayName "Microsoft Project Server Queue Service 2010"
    Start-Sleep -Seconds $sleepTime
    
    Write-Host "Restarting IIS ..."
    IISReset
    
    # Set-PSDebug -Off
    if (-not $install)
    {
        # Remove the feature in PWA Workflow Settings only if not updating.
        Write-Host "`nRemove the $featureName workflow, by using the browser."
        
        & $ie "$serverUrl/_layouts/RemWrkfl.aspx"
        Read-Host "Press ENTER to continue"
        Write-Host
    }
}

if ($install)
{
    # Install the workflow feature.    
    # Set-PSDebug -Step

    Write-Host "Running Add-SPSolution for $inFile.FullName ..."   
    Add-SPSolution -LiteralPath $inFile.FullName -Confirm:$false
    Start-Sleep -s $sleepTime
    
    Write-Host "Running Install-SPSolution for $fileName ..."
    Install-SPSolution -Identity $fileName -GACDeployment -Confirm:$false

    Wait4Timer
    
    Write-Host "Running Enable-SPFeature for $featureName on $serverUrl ..."
    Enable-SPFeature -Identity $featureName -Url $serverUrl -Confirm:$false
    Start-Sleep -s $sleepTime
    
    # Set-PSDebug -Off
    
    if (-not $remove)
    {
        # Add the feature in PWA Workflow Settings only if not updating.
        Write-Host "Add the $featureName workflow, by using the browser."
        
        & $ie "$serverUrl/_layouts/AddWrkfl.aspx"
        Read-Host "Press ENTER to continue"
    }
}
Write-Host "Completed $action of $fileName"

Following is the output in a SharePoint 2010 Management Shell window for an example that uses the update option of the Install-PJWorkflow.ps1 script:

PS > .\Install-PJWorkflow C:\PSScripts\BranchingWorkflow.wsp https://ServerName/pwa BranchingWorkflow_Feature1 update
Using BranchingWorkflow.wsp; action = update

Running Disable-SPFeature for BranchingWorkflow_Feature1 on https://ServerName/pwa ...
Running Uninstall-SPSolution for BranchingWorkflow.wsp ...

Finding timer job
job: solution-deployment-branchingworkflow.wsp-0
Waiting to finish...............................
job history: Succeeded

Running Remove-SPSolution for BranchingWorkflow.wsp ...
Restarting services ...
WARNING: Waiting for service 'Microsoft Project Server Queue Service 2010
(ProjectQueueService14)' to finish stopping...
WARNING: Waiting for service 'Microsoft Project Server Queue Service 2010
(ProjectQueueService14)' to finish starting...
WARNING: Waiting for service 'Microsoft Project Server Queue Service 2010
(ProjectQueueService14)' to finish starting...
Restarting IIS ...

Attempting stop...
Internet services successfully stopped
Attempting start...
Internet services successfully restarted
Running Add-SPSolution for C:\PSScripts\BranchingWorkflow.wsp.FullName ...

Name                           SolutionId                           Deployed
----                           ----------                           --------
branchingworkflow.wsp          57e93e21-e17f-4bfa-8630-b0dde64ea029 False
Running Install-SPSolution for BranchingWorkflow.wsp ...

Finding timer job
job: solution-deployment-branchingworkflow.wsp-0
Waiting to finish..........................
job history: Succeeded

Running Enable-SPFeature for BranchingWorkflow_Feature1 on https://ServerName/pwa ...
Completed update of BranchingWorkflow.wsp

Alternate Procedure for Updating a Workflow Assembly

Instead of recreating a workflow solution package and running the Install-PJWorkflow.ps1 script on a Project Server computer, you can update the workflow by manually replacing the assembly in the global assembly cache. You can also use Visual Studio 2010 to deploy and retract the workflow on the development computer.

Important

If you use Visual Studio 2010 to deploy and retract a workflow, you must create a custom deployment that resets the SharePoint Timer service and the Project Server Queue service. For more information, see Walkthrough: Creating a Custom Deployment Step for SharePoint Projects.

We recommend that you use Install-PJWorkflow.ps1 or a similar Windows PowerShell script to install, remove, or update a workflow for Project Web App.

Procedure 4. To manually update a workflow assembly

Stop the Project Server Queue service and the SharePoint Timer service.
Add the updated workflow assembly to the global assembly cache. For example, open the Run dialog box on the Start menu, and then type assembly in the Open text box. Drag BranchingWorkflow.dll into the assembly window.
Start the Project Server Queue service and the SharePoint Timer service.
Restart IIS. In a Command Prompt window, run iisreset.
Repeat steps 1 – 4 for every Project Web App server in the SharePoint farm.

Configuring a Workflow on a Farm

On a SharePoint farm that includes a computer running Project Server and one or more Project Web App servers, the front-end web service on the Project Server computer can be turned off for performance or security reasons. In that case, workflows cannot start until the workflow configuration settings on a separate Project Web App server are updated. Procedure 5 shows how to turn off the front-end web service and update the workflow configuration settings.

Note

Procedure 5 is not necessary if you use the Project Server computer also as a front-end Project Web App server.

Procedure 5. To reconfigure a workflow on a farm

Turn off Project Web App (the front-end web service) on the Project Server computer. On the Central Administration page for SharePoint 2010, in the System Settings group, click Manage services on server. On the Services on Server page, click Stop for the Microsoft SharePoint Foundation Web Application service.

Note

Leave the Project Application Service running on the Project Server computer.
On a separate Project Web App server, open a SharePoint 2010 Management Shell window, and then run the following Windows PowerShell commands:
```
$webapp = Get-SPWebApplication -identity http://WebApplication[:port]
$webapp.UpdateWorkflowConfigurationSetttings()
```
For example, if the URL of a Project Web App site is https://ServerName/pwa, the –identity parameter is https://ServerName.
On each Project Web App server in the farm, do the following:
1. Restart Internet Information Services (IIS).
2. Open the Services window, and then restart Microsoft Project Server Events Service 2010 and Microsoft Project Server Queue Service 2010.

How to: Deploy a Project Server Workflow

Creating a Project Server Workflow Solution Package

Procedure 1. To create a workflow solution package

Installing a Workflow Solution Package

Procedure 2. To install a workflow solution package

Uninstalling a Workflow Solution Package

Procedure 3. To uninstall a workflow solution package

Complete Script Example for Managing a Workflow Solution

Alternate Procedure for Updating a Workflow Assembly

Procedure 4. To manually update a workflow assembly

Configuring a Workflow on a Farm

Procedure 5. To reconfigure a workflow on a farm

See Also

Tasks

Additional resources