Simple SharePoint Solutions

The easiest way to package and deploy a Sharepoint workflow

2011-11-19T07:37:00.005-05:00

Note: this relates to packaging up MOSS 2007 workflows created in Visual Studio.

If you have developed your workflow in Visual Studio and have already been F5 deploying it (which means you have already created your feature.xml and workflow.xml), and now you are ready to package it up into a wsp for deploying to other servers, then the following is probably the quickest way of doing that.

Essentially, it involves using WSP Builder. However, this method doesn't require using any of the WSP Builder project templates to do it. The templates are useful if you create your workflow project from the WSP Builder templates to begin with. But if you created your workflow with the normal Visual Studio workflow templates, THEN want to use WSP Builder templates for packaging the workflow, its a bit of a pain to do. This will enable you to get your .wsp with the absolute minimum in changes to your Visual Studio project.

1. install WSP Builder, then load Visual Studio and your workflow project

2. in your Project, create 12/TEMPLATE/FEATURES/your_feature_name

3. copy feature.xml, workflow.xml, and your InfoPath task forms (.xsn's) into this folder

4. right-click your project, click WSPBuilder -> Build WSP

WSP Builder will automatically
1. build your manifest.xml for you, adding in everything it sees in your 12 folder structure
2. get your project's assembly (.dll)
3. package it all into a .wsp file and drop it in the root of your project

Below are my installation and removal scripts.

rem Workflow installation script

d:\stsadm -o addsolution -filename d:\deploy\MyWorkflowProject\MyWorkflowProject.wsp

d:\stsadm -o deploysolution -name MyWorkflowProject.wsp -immediate -allowGacDeployment

pause

d:\stsadm -o activatefeature -name MyWorkflowProject -url http://server_to_deploy_to

rem Workflow removal script

d:\stsadm -o deactivatefeature -name MyWorkflowProject -url http://server_to_deploy_to

d:\stsadm -o retractsolution -name MyWorkflowProject.wsp -immediate

pause

d:\stsadm -o deletesolution -name MyWorkflowProject.wsp -override

How to email members of a SharePoint group

2011-10-18T21:53:00.004-04:00

This relates to MOSS 2007.

In doing a state machine workflow, I have noticed how you can assign a SharePoint group to a task no problem, but when you set that group as the recipient of an email activity, you get an error. I wrote a very simple function that takes in the SharePoint group's name as a parameter and returns a semi-colon delimited string of the email addresses of the people in the group. I also had another scenario where I wanted to get the login names of the individuals in the group, too, so I made another parameter that acts as a switch - you choose whether you want login names or email addresses. Just assign the function below to your email task's To property and you are good to go!

Private Function GetGroupInfo(ByVal GroupName As String, ByVal WhatToGet As String) As String
    'PURPOSE: returns semicolon-separated string of group member login names or email addresses

    Dim strReturnString As String = ""

    'get group
    Dim TheGroup As SPGroup = workflowProperties.Web.SiteGroups(GroupName)

    'loop through group and build string of login names or email addresses
    For Each GroupMember As SPUser In TheGroup.Users

        If WhatToGet = "LOGIN_NAMES" Then

            If strReturnString = "" Then
                strReturnString = GroupMember.LoginName
            Else
                strReturnString = strReturnString & "; " & GroupMember.LoginName
            End If

        ElseIf WhatToGet = "EMAIL_ADDRESSES" Then

            If strReturnString = "" Then
                strReturnString = GroupMember.Email
            Else
                strReturnString = strReturnString & "; " & GroupMember.Email
            End If
        End If
    Next

    Return strReturnString

End Function

To get the email addresses of members in a SharePoint group called "Account Personnel" and then assign them to an email activity's To property, type:
MyTaskEmail_To = GetGroupInfo("Account Personnel", "EMAIL_ADDRESSES")

Workflow task link in email

2011-10-18T19:24:00.005-04:00

Just wanted to do a quick post on a recent gotcha. I created a MOSS 2007 state machine workflow and added custom email activities to send emails notifying users of their tasks. I wanted to have a link in those emails that pointed directly to the user's task, ie the same link you get when you enable "Send e-mail when ownership assigned?" in the task list's Settings -> List Settings -> Advanced settings screen.

I thought I could simply reference the task's ListItemId property, but it kept coming up as -1. After finding an article on SharePoint Tricks, I realized I needed to create a Field variable for the ListItemId property, then reference the Field variable.

1. In the create task activity, create a Field from the ListItemId (by default it says -1).

2. The link in the email concatenates workflowProperties.SiteUrl, workflowProperties.TaskListUrl, "/DispForm.aspx?ID=", and finally createMyApprovalTask_ListItemId.ToString()

This will link directly to the user's task form on the SharePoint site.

That's it!

How to remove a SharePoint solution that is giving an error

2011-09-28T23:31:00.001-04:00

A while back I had a solution that would just not be removed. In the Solution Management screen in Central Administration, the Status for the solution was a bright red "Error". Attempting to remove it from there would give an error.

Luckily, I found a great post by Alex Thissen that clearly explains how to use stsadm to remove a malfunctioning solution. The blog post is called Remove malfunctioning Windows SharePoint Services solutions.

In a nutshell, if retracting the solution:

stsadm -o retractsolution -name solutionname.wsp -immediate

doesn't work, and if deleting the solution:

stsadm -o deletesolution -name solutionname.wsp -override

doesn't work, then

1. run an enumeration to see the scheduled deployments

stsadm -o enumdeployments

2. use the JobId to cancel the deployment

stsadm -o canceldeployment -id 2529c788-971c-46a3-b69f-a2a0a1fcc851

Afterwards, you can verify it by doing 1. again.

How to start a SharePoint State Machine workflow without association or initiation forms

2011-09-22T21:33:00.002-04:00

This assumes you are creating a SharePoint 2007 state machine workflow in Visual Studio.

If you ever need a workflow to start, but don't want it to have an association or initiation form, you have to do two things, both of which are in workflow.xml:

1. In the Workflow element, do not specify an AssociationUrl (for the association form) or InstantiationUrl (for the initiation form). Just leave it out of the element completely! You may want to do the same thing if you have no modification form.
The attributes indicate the web forms that will host the association and initiation forms. By default, they look like AssociationUrl="_layouts/CstWrkflIP.aspx" and InstantiationUrl="_layouts/IniWrkflIP.aspx".

2. In the MetaData element, be sure Association_FormURN and Instantiation_FormURN are commented out.

How to create and deploy a web-enabled InfoPath form with managed code

2011-06-26T23:27:00.000-04:00

In this article, we will create a web-enabled InfoPath form that will have managed code in its "on load" that will populate a field automatically. We will deploy our InfoPath form to a SharePoint form library.

First off: this article assumes you are using MOSS 2007, Microsoft Office InfoPath 2007, and Visual Studio 2008. To add managed code to an InfoPath form, Visual Studio Tools for Applications (VSTA) must be installed.

If VSTA is not set up, the following message appears:

"InfoPath cannot add the event handler.

To work with Visual Basic or C# code, VSTA is required. .NET Framework 2.0 and Microsoft Core XML Services 6.0 must be installed before VSTA."

To install VSTA:
----------------
1. Control Panel -> Add or Remove Programs -> Microsoft Office 2007 -> Change

2. Under Microsoft Office InfoPath -> .NET Programmability Support, check the .NET Programmability Support for .NET Framework version 2.0 and then under that check Visual Studio Tools for Applications

Also, be sure Microsoft Core XML Services 6.0 is installed (it will show up as MSXML6). Check for it in Add or Remove Programs, and if it is not installed, search for it on microsoft.com, then download it.

Now, on to why we are here...

To create a web-enabled InfoPath form with managed code:
--------------------------------------------------------
1. Create the form in InfoPath. I won't go in detail here. Just create a form with a few fields. Call one of the fields AccountId.

2. change compatibility settings to make it web-enabled:
Tools -> Form Options -> Compatibility -> check Design a form template that can be opened in a browser or InfoPath

3. give the form Full Trust:
Tools -> Form Options -> Security and Trust -> select Full Trust

4. add code - to have custom code when the form loads:
a. set location where you want the Visual Studio project to be created
Tools -> Programming -> under Programming Language, specify language and project location
b. indicate you want to code for the loading of the form
Tools -> Programming -> Loading Event... (it will prompt you to save the form
if you haven't already)
VSTA will create a Visual Studio project (using the form's name) in the location
specified in a. Visual Studio will load with project opened.
c. add code to populate a form field automatically when form loads
under FormEvents_Loading, add code to execute when form loads

Dim strAccountId As String = ""

            strAccountId = "P-" & Date.Now.ToString()

            'populate account field on infopath form with account #
            Me.CreateNavigator.SelectSingleNode("my:MyForm/my:AccountId", Me.NamespaceManager).SetValue(strAccountId )

5. run the project to see the form field being populated

To deploy a web-enabled InfoPath form with managed code:
--------------------------------------------------------
6. publish the form template
back in InfoPath,
a. click Publish Form Template...
b. select To a network location and click Next
c. enter a location to publish the template, a place where an administrator can access and click Next, clear textbox then click Next, click Publish, click Close

7. upload Form Template in Central Admin
a. in Central Administration -> Application Management -> Manage Form Templates, click Upload Form Template
b. browse to location you just published to and select form template
c. click Upload

8. activate the form at the site collection level
In Site Settings -> Site Collection Features, find form template and click Activate
Notice the form template appears as a Site Content Type under Site Settings -> Site Content Types

9. create and set up a form library and add that content type to it
create new form library
a. I go in through View All Site Content -> Create -> Form Library
b. give it a Name
c. Document Template should have Microsoft Office InfoPath form
d. click Create

10. set up library
a. settings -> form library settings -> advanced settings
check Yes for Allow management of content types
check Display as a web page
check No for Display "New Folder" command on the New menu (I just like to remove NewFolder, this isn't really necessary)
click Ok
b. Under Content Types, remove Form and add new content type (form template)
a. click Form -> Delete this content type
b. click Add from existing site content types, select new content type, click Add, then click OK

11. go back to form library and click New

12. You should now see the form display as a web page, and notice the AccountId field was populated programmatically!

How to get a list of running workflows in a document library

2010-12-17T20:39:00.009-05:00

Getting a list of workflows that are running on a list library or document library is pretty straightforward. Essentially, all we need to do is get a handle on the site, get a handle on the list, loop through the list's items, then for each item, loop through that item's workflows collection, then for each workflow, look at its InternalState and if its set to "Running", its, uhh, running. You could remove the IF statement from the code below and display all workflows for the current item to see whats Running, Completed, Locked, or Canceled. Once you have a handle on the workflow, you could then do whatever else you might need to do with it. What if you wanted to be emailed every time a workflow got locked? In my case, I have a document library with items that may have workflows running on them. As these workflows have due dates, I need to look at all running workflows in the list, and if today is past their due date, I want to stop these workflows. I will then put this code in a SharePoint timer job that will execute daily. In fact, I will post an article on this in the coming days or weeks after I actually do it! This is using VS2008/MOSS2007 and the code is in VB, but it would be extremely easy to rewrite in C#. I would imagine this would work in SharePoint 2010, but I haven't tested yet. If anyone wants to copy/paste it in 2010 and test it for the rest of us, we'd love a confirmation!

For simplicity's sake, we will create a console application that will access our SharePoint site and loop through the document library's workflows to find the running ones.

1. in Visual Studio, click File -> New Project -> Windows -> Console Application

2. it defaults to ConsoleApplication1, leave it and click OK

3. in Solution Explorer, right-click ConsoleApplication1, click Add Reference

4. browse to C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI\ and select Microsoft.SharePoint.dll

5. above Module Module1, add:

Import Microsoft.SharePoint

6. inside Sub Main(), add:

Dim site As New SPSite("http://my_sp_site_here")   'get site
Dim list As SPList = site.RootWeb.Lists("my_document_library")   'get document library

For Each item As SPListItem In list.Items   'for each item in library
  For Each wrkflw As Workflow.SPWorkflow In item.Workflows    'for current item's list of workflows
    If wrkflw.InternalState.ToString = "Running" Then   'if current workflow is running
      Console.WriteLine(wrkflw.InstanceId.ToString)   'display it's instance id
    End If
  Next
Next

Console.WriteLine()
Console.Write("Press ENTER to continue")
Console.ReadLine()

Update 12 Hive Through A Feature

2010-06-09T09:18:00.020-04:00

As we got our SharePoint environment up and running, we needed to have the ability to make changes to our 12-Hive. We also wanted to have the flexibility to undo the changes and restore the 12-Hive to the way it was originally.

This post discusses the scenario where you need to make changes to files that already exist in the 12-Hive. I call this solution HiveUpdates. If you have a need to add new files to the 12-Hive that do not already exist, such as new images or layouts, check out my other article Add New Files To 12-Hive Through A Solution. I call that solution HiveAdditions. We decided it would be best for us to separate these two types of Hive changes into two separate solutions.

This solution, HiveUpdates, allows us to modify existing Hive files. This solution contains a feature that, when activated, makes a backup copy of the original file, then overwrites the original with the new file. When the feature is deactivated, it copies the backup file back to the original filename.

The method I used is based on the article 12 Hive System-File Changes: One Feature to rule them all!. The above post has a routine that is called when the feature is activated or when its deactivated. The code that fires simply "swaps" newly changed 12-hive files with their corresponding original 12-hive files. This happens both when the feature is activated or deactivated. While the "swap" code seems like a good idea on the surface (the same code that deploys the changes will swap files back to undeploy them), I found in practice this seemed risky and even prone to error if something went wrong on the feature activate or feature deactivate. I sometimes got the files out of sync and would lose the original 12-Hive versions.

Therefore, I modified the code to first make a backup copy of a 12-Hive file I want to update, then overwrite the original 12-hive file with my changed version (this is an activate). On a deactivate, it overwrites my changed version with the original's backup file. The original's backup file always stays there as a backup, which makes me feel very safe. And I like feeling safe. I like my job and want to keep it.

1. In Visual Studio 2008, File -> New -> Project

2. Under Visual C#, pick SharePoint, then Empty

3. For Name, type: HiveUpdates

4. For Location, type: D:\development

5. Click OK

6. Select Full Trust (Deploy to GAC) and click OK

7. In WSP View (View -> Other Windows -> WSP View), click "Create new feature"

8. Change Feature Scope to Farm

9. Check Add feature receiver

10. click OK

11. In Solution Explorer, rename Feature1 to HiveUpdates

12. Rename Feature1Receiver.cs to HiveUpdatesReceiver.cs

13. Double-click HiveUpdatesReceiver.cs to open it

14. Rename class from FeatureReceiver1 to HiveUpdatesReceiver

15. Below that, you'll see the constructor "public FeatureReceiver1". Rename constructor from FeatureReceiver1 to HiveUpdatesReceiver.

16. In WSP View, hit refresh and notice FeatureReceiver1 is now HiveUpdatesReceiver

17. Rename Feature1 folder to HiveUpdates

Make the following code modifications/additions to HiveUpdatesReceiver.cs:

18. At the top of the code, add the following using statements:

using Microsoft.SharePoint.Administration;
using System.IO;

19. Above the HiveUpdatesReceiver constructor, add the following:

private DirectoryInfo localDirectory = new DirectoryInfo(@"C:\");

20. In the FeatureActivated method, add:

DeployToHive(properties);

21. In the FeatureDeactivating method, add:

RemoveFromHive(properties);

22. Below the FeatureUninstalling method, add the following 4 methods (DeployToHive, RemoveFromHive, GetHiveFile, GetLocalDirectory):

private void DeployToHive(SPFeatureReceiverProperties properties)
{
    //loop through each server in the farm
    foreach (SPServer server in properties.Definition.Farm.Servers)
    {
        //if the current server is a WebFrontEnd server
        if (server.Role == SPServerRole.WebFrontEnd || server.Role == SPServerRole.Application 
            || server.Role == SPServerRole.SingleServer)
        {
            string localFilePath = GetLocalDirectory(properties.Definition.RootDirectory,
                     server.Name);
            localDirectory = new DirectoryInfo(localFilePath);

            foreach (FileInfo fileinfo in localDirectory.GetFiles("*", 
                     SearchOption.AllDirectories))
            {
                //if current file in feature exists in 12 hive on current server
                if (File.Exists(GetHiveFile(fileinfo.FullName, server.Name)) 
                    && (!fileinfo.FullName.Contains(".hivebackup")))
                    // backup file from 12 hive to feature
                    File.Copy(GetHiveFile(fileinfo.FullName, server.Name),
                              fileinfo.FullName + ".hivebackup", true);

                //if current file in feature exists
                if (File.Exists(fileinfo.FullName) && 
                    (!fileinfo.FullName.Contains(".hivebackup")))
                    // copy local file to the 12 hive
                    File.Copy(fileinfo.FullName, GetHiveFile(fileinfo.FullName, server.Name), 
                               true);
            }
        }
    }
}



private void RemoveFromHive(SPFeatureReceiverProperties properties)
{
    //loop through each server in the farm
    foreach (SPServer server in properties.Definition.Farm.Servers)
    {
        //if the current server is a WebFrontEnd server
        if (server.Role == SPServerRole.WebFrontEnd
           || server.Role == SPServerRole.Application
           || server.Role == SPServerRole.SingleServer)
        {
            string localFilePath = GetLocalDirectory(properties.Definition.RootDirectory,
                server.Name);
            localDirectory = new DirectoryInfo(localFilePath);

            foreach (FileInfo fileinfo in localDirectory.GetFiles("*",
                 SearchOption.AllDirectories))
            {
                //if current backup file in feature exists in 12 hive
                if (File.Exists(fileinfo.FullName + ".hivebackup"))
                    // copy hivebackup file back to the 12 hive
                    File.Copy(fileinfo.FullName + ".hivebackup",
                              GetHiveFile(fileinfo.FullName, server.Name), true);
            }
        }
    }
}



string GetHiveFile(string fileName, string serverName)
{
    if (fileName.StartsWith(localDirectory.FullName))
    { // file is local
        string p = @"\\" + serverName
                   + @"\C$\Program Files\Common Files\Microsoft Shared\web server extensions\12"
                   + fileName.Remove(0, localDirectory.FullName.Length);
        return p;
    }
    throw new Exception("Filepath doesn't point to correct local hive!");
}



string GetLocalDirectory(string filePath, string serverName)
{
    return @"\\" + serverName + @"\" + @filePath.Replace(":", "$") + @"\12";

    //write a class that writes exceptions to the event log
    throw new Exception("Filepath doesn't point to correct local hive!");
}

Now we need to create the appropriate 12-Hive file structure for the feature in Solution Explorer. Any 12-Hive files we want to update will have their newer versions placed in the file structure we are about to create.

23. In Solution Explorer, right-click project HiveUpdates, then click Add -> New Item... -> SharePoint -> Template.

24. You will notice a folder called Templates was created in the Solution Explorer. Delete the default file TemplateFile1.txt.

25. Under Templates, create a folder called FEATURES.

26. Under FEATURES, create a folder called HiveUpdates.

So far, we have created 12/TEMPLATE/FEATURES/HiveUpdates. This is the location in the 12-Hive where that feature's feature.xml gets deployed to. But now, we must create another 12-Hive structure under this folder. This is where our newer files will be deployed to when the solution is initially deployed. When the feature is activated, this is where the above code will store backups of the original files from the 12-Hive, as well as the source from which to overwrite the 12-Hive files with.

27. Under HiveUpdates, create a folder called 12.

28. Under 12, create a folder called TEMPLATE.

29. Under TEMPLATE, create a folder called LAYOUTS.

30. Copy application.master in here. Either make some small change to it or at the very least change the date on the file so its different from what it is in the 12-Hive. Be sure to right-click application.master and click Include In Project if it is not already included.

31. In WSP View, double-click feature.xml.

32. Change the value of Title from Feature1 to HiveUpdates.

33. Verify Scope is set to Farm.

33. After the title or scope, add: ActivateOnDefault="false"

34. Verify your manifest was created correctly. In WSP View, Under HiveUpdates, you should see manifest.xml. Double-click manifest.xml and verify your file path for application.master is FEATURES\HiveUpdates\12\TEMPLATE\LAYOUTS.

35. click Build -> Rebuild Solution

36. click Build -> Package Solution

The solution package that you just created in the above step, HiveUpdates.wsp, was created in your project's bin\debug folder.

To deploy the solution:

37. create folder d:\deploy

38. copy HiveUpdates.wsp from project's bin\debug folder to d:\deploy

39. In d:\deploy, create two batch files, add_hiveupdates.bat and remove_hiveupdates.bat.

add_hiveupdates.bat:

c:

cd\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN

stsadm -o addsolution -filename d:\deploy\HiveUpdates\HiveUpdates.wsp

stsadm -o deploysolution -name HiveUpdates.wsp -immediate -allowGacDeployment

pause

stsadm -o activatefeature -name HiveUpdates

d:

remove_hiveupdates.bat:

c:

cd\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN

stsadm -o deactivatefeature -name HiveUpdates

stsadm -o retractsolution -name HiveUpdates.wsp -immediate

pause

stsadm -o deletesolution -name HiveUpdates.wsp

d:

40. in d:\deploy, type add_hiveupdates.wsp and hit enter

41. verify solution was deployed in Central Administration -> Operations -> Solution Management

42. verify files were added to 12-Hive!

Add New Files To 12-Hive Through A SharePoint Solution

2010-06-05T16:07:00.009-04:00

As we got our SharePoint environment up and running, we needed to have the ability to make changes to our 12-Hive. We also wanted to have the flexibility to undo the changes and restore the 12-Hive to the way it was originally.

This post discusses the scenario where you need to add new files to the 12-Hive that do not already exist, such as new images or layouts. I call this solution HiveAdditions. If you have a need to update files that already exist in the 12-Hive, check out my other article Update 12 Hive Through A Feature. I call that solution HiveUpdates. We decided it would be best for us to separate these two types of Hive changes into two separate solutions.

This solution, HiveAdditions, simply allows us to add files into the 12-Hive upon a deployment. When we retract this solution, it simply removes all those files. We liked this approach because it allows us to have this solution as the one place for all new 12-Hive files. If we needed to add new files, we retract this solution, add the new files to the solution, then deploy it again.

1. In Visual Studio 2008, File -> New -> Project

2. Under Visual C#, pick SharePoint, then Empty

3. For Name, type: HiveAdditions

4. For Location, type: D:\development

5. Click OK

6. Select Full Trust (Deploy to GAC) and click OK

7. In Solution Explorer, right-click project HiveAdditions, then click Add -> New Items... -> SharePoint -> Root File

8. Leave Name alone and click Add

9. Under RootFiles (which now appears in Solution Explorer), delete RootFile1

Under RootFiles, we must mirror the 12-Hive locations where we want to add the new files.

Let's add image files under TEMPLATE/IMAGES.

10. Right-click RootFiles, click Add -> New Folder and name it TEMPLATE.

11. Right-click TEMPLATE, click Add -> New Folder and name it IMAGES.

12. Drag and drop your images into IMAGES folder. Be sure to right-click newly added files and click Include In Project if they are not already included.

13. Verify your manifest was created correctly. Click View -> Other Windows -> WSP View. Under HiveAdditions, you should see manifest.xml, then under that, RootFiles -> TEMPLATE -> IMAGES followed by the files you added. Double-click manifest.xml and verify your file paths are under TEMPLATE\IMAGES\file1.jpg, etc.

14. click Build -> Rebuild Solution

15. click Build -> Package Solution

The solution package that you just created in the above step, HiveAdditions.wsp, was created in your project's bin\debug folder.

To deploy the solution:

16. create folder d:\deploy

17. copy HiveAdditions.wsp from project's bin\debug folder to d:\deploy

18. In d:\deploy, create two batch files, add_hiveadditions.bat and remove_hiveadditions.bat.

add_hiveadditions.bat:

c:

cd\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN

stsadm -o addsolution -filename d:\deploy\HiveAdditions\HiveAdditions.wsp

stsadm -o deploysolution -name HiveAdditions.wsp -immediate -allowGacDeployment

d:

remove_hiveadditions.bat:

c:

cd\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\BIN

stsadm -o retractsolution -name HiveAdditions.wsp -immediate

pause

stsadm -o deletesolution -name HiveAdditions.wsp

d:

19. in d:\deploy, type add_hiveadditions.wsp and hit enter

20. verify solution was deployed in Central Administration -> Operations -> Solution Management

21. verify files were added to 12-Hive!

How to deploy SharePoint list templates

2009-08-25T23:00:00.020-04:00

Ok, so after I had packaged up three web parts into their own features in a solution (wsp) file, I had one more issue to address: those three web parts were dependent on lists created from two list templates. So I needed to also package up those list templates as features in the solution file.

After finding countless pages that explain how to do it the hard way (and there are many hard ways), I finally realized one of my favorite sites showed me the easiest, best way, by far. Jeremy Thake of SharePointDevWiki created a video showing how its done. Jeremy is the man downunder! Excuse me, the bloke downunder.

In addition, I also needed to package up two list templates into the solution package, not just one as is done in the video. As with most stuff SharePoint, once you know how to do something, its extremely easy to do.

At a high level, here is what we will do:

Create some lists in your SharePoint site.

Install SPSource from CodePlex and use it to reverse engineer the lists you created on your SharePoint site back into list templates, storing the necessary files that make up the list templates into a Visual Studio project.

Use BuildWSP to build your WSP!

Note: in this example, I will create a new Visual Studio project. However, I want to add the reverse-engineered list templates into my existing project with my web parts. To do this, all I have to do is copy the contents of my FEATURES folder from my new Visual Studio project (where I reverse engineered my list templates) into my existing Visual Studio project's FEATURES folder (where my web parts already are). When I run BuildWSP, it will just simply see the new list template features and add those to the .wsp. I will not show the copy in the steps below because I don't know if you need to add your list templates to a pre-existing project, but like I said, just copy the list templates from the FEATURES folder if you want to do this.

Ok, so now for a little bit of detail.

In your SharePoint site, create two lists. I will call one Contact List Template and the other Sent Emails Template in this example. Add some columns to them.

Download SPSource from CodePlex. I put spsource.exe in a folder called d:\deploy, but just put it somewhere easy to get to.

If you haven't already downloaded and installed WSPBuilder, do it. WSPBuilder will be added under the Tools menu in Visual Studio.

Create the Visual Studio project that will be the destination for the reverse-engineered list templates.
1. In Visual Studio, click File -> New -> Project -> WSPBuilder -> WSPBuilder Project
2. Name it MyListTemplates and click OK.

Add a feature for each list template you wish to reverse engineer. (Note: Trying to add both list templates to the same feature has proven to be problematic. If you add them to the same feature, when you deploy the feature and create lists from the list templates, all the lists you create will only use the definition from the first list template that was deployed, even if you create a list based on the second list template. Therefore, create one feature for each list template!)
1. In the Solution Explorer, right-click the project, then click Add -> New Item -> WSPBuilder -> Blank Feature
2. Name it ContactListTemplate and click Add.
3. In the Feature Settings dialog, change the Scope to Site and click OK.
4. Do a. through c. again, but this time name the feature SentEmailsTemplate.
5. Notice both features have been added under /12/TEMPLATE/FEATURES/ in your Solution Explorer. Each contains an elements.xml and feature.xml.

Create a .spsource file for each feature. These files tell SPSource what lists to reverse engineer into list templates.
1. In Solution Explorer, right-click the ContactListTemplate feature, then click Add -> New Item -> Common -> XML File, name it contactlist.spsource and click Add.
2. In Solution Explorer, right-click the SentEmailsTemplate feature, then click Add -> New Item -> Common -> XML File, name it contactlist.spsource and click Add.
3. Copy the contents of elements.xml into both of these .spsource files.
4. In contactlist.spsource, add the following inside the Elements tag:
  
  <ListTemplate Name="Contact List Template" />
5. In sentemails.spsource, add the following inside the Elements tag:
  
  <ListTemplate Name="Sent Emails Template" />
In your project's folder, create a text file called SPSource.cmd with these contents:
@ECHO OFF

SET SPSOURCE="d:\deploy\SPSource.exe"
SET DEVSITEURL="http://sharepoint2007:1001/marketing"

%SPSOURCE% -designsite %DEVSITEURL%

PAUSE
Be sure to set DEVSITEURL to your SharePoint site where you created the lists back in step 1.

Double-click SPSource.cmd so it runs. If you get an error message saying something like "Method not found...SPOpenBinaryOptions...), you need to install Windows SharePoint Services 3.0 Service Pack 1 (SP1). This is because SPSource requires methods that are in WSS 3.0 SP1.
In Solution Explorer, click Show All Files. Under the two features, you'll see a new folder under each with the same name. Right-click the new folders and click Include In Project.

Build the project.

Create the wsp solution file by clicking Tools -> WSP Builder -> Build WSP.

You can now deploy MyListTemplates.wsp with stsadm as you normally deploy wsps! Use addsolution, deploysolution, and activatefeature to deploy however you want to deploy it (ie using GAC or CAS, etc).

How to create a SharePoint State Machine Workflow: Part 6 - Add task notification emails

2009-08-20T23:03:00.008-04:00

Here in Part 6, we'll add email notification events so when a task is assigned, approved, or rejected, the appropriate emails are sent to the proper people. This part assumes you have completed part 4.


1. go back to the design surface and double-click PeerReviewerApprovalInitialization to drill down into it

2. drag and drop a SendEmail activity below hlogPeerReviewerApprovalTaskCreated
    and set the following properties:
    a. Name: sendPeerReviewerApprovalTaskEmail
    b. Body: click the ellipses, click the "Bind to a new member" tab,
             remove the 1 from the end of the "New member name" and click OK
    c. CC: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    d. CorrelationToken: choose workflowToken from dropdownlist
    e. Subject: click the ellipses, click the "Bind to a new member" tab,
                remove the 1 from the end of the "New member name" and click OK
    f. To: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    g. MethodInvoking: type PeerReviewerApprovalTaskEmail and hit enter
    h. You will be taken to the code stub for PeerReviewerApprovalTaskEmail. Copy and paste the following code:

        'get PeerReviewer's email address
        Dim PeerReviewerObject As SPUser = GetUserObject(PeerReviewer)
        Dim PeerReviewerEmail = PeerReviewerObject.Email

        'get CC's email address
        Dim CCObject As SPUser = GetUserObject(CC)
        Dim CCEmail = CCObject.Email


        sendPeerReviewerApprovalTaskEmail_To = PeerReviewerEmail
        sendPeerReviewerApprovalTaskEmail_CC = CCEmail
        sendPeerReviewerApprovalTaskEmail_Subject = "Approval of " & workflowProperties.Item.File.Name & " has been assigned to you."
        sendPeerReviewerApprovalTaskEmail_Body = "<span style='font-family: arial; font-size: medium'>" & _
                                                 "Task assigned by " & workflowProperties.OriginatorUser.Name & " on " & DateTime.Now & _
                                                 "</span>" & _
                                                 "<br>" & _
                                                 "<span style='font-family: arial; font-size: x-small'>" & _
                                                 "Due by " & DateTime.Today & _
                                                 "<br><br>" & _
                                                 "Instructions: <br>" & Instructions & _
                                                 "<br><br>" & _
                                                 "Please approve " & workflowProperties.Item.File.Name & _
                                                 "<br><br>" & _
                                                 "To complete this task:" & _
                                                 "<br><br>" & _
                                                 "    1. Review " & "<a href='" & workflowProperties.SiteUrl & "\" & workflowProperties.ItemUrl & "'>" & workflowProperties.Item.File.Name & "</a>" & "." & _
                                                 "<br>" & _
                                                 "    2. Use the <b>Edit this task</b> button to Approve/Reject the document." & _
                                                 "<br><br>" & _
                                                 "To view this workflow's history, click " & "<a href=" & workflowProperties.SiteUrl & "/_layouts/WrkStat.aspx?List=" & workflowProperties.ListId.ToString & "&WorkflowInstanceID=" & workflowProperties.WorkflowId.ToString & ">here</a>" & "." & _
                                                 "</span>"

        'if this is the first time we have gone to the peer reviewer state, do not show comments
        '  in email
        If ArrivedFromInitiatorState = True Then
            'get the comments entered by the initiator
            Dim Comments As String = onInitiatorApprovalChanged.AfterProperties.ExtendedProperties("txtComments").ToString

            sendPeerReviewerApprovalTaskEmail_Body = sendPeerReviewerApprovalTaskEmail_Body & _
                                                 "<span style='font-family: arial; font-size: x-small'>" & _
                                                 "<br><br>" & _
                                                 "<font color=red>Comments:</font> <br>" & Comments & _
                                                 "</span>"
        End If

3. go back to the design surface and double-click InitiatorApprovalInitialization to drill down into it

4. drag and drop a SendEmail activity below hlogPeerReviewerApprovalTaskCreated
    and set the following properties:
    a. Name: sendInitiatorApprovalTaskEmail
    b. Body: click the ellipses, click the "Bind to a new member" tab,
             remove the 1 from the end of the "New member name" and click OK
    c. CC: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    d. CorrelationToken: choose workflowToken from dropdownlist
    e. Subject: click the ellipses, click the "Bind to a new member" tab,
                remove the 1 from the end of the "New member name" and click OK
    f. To: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    g. MethodInvoking: type InitiatorApprovalTaskEmail and hit enter
    h. You will be taken to the code stub for PeerReviewerApprovalTaskEmail. Copy and paste the following code:

        'get Initiator's email address
        Dim InitiatorObject As SPUser = GetUserObject(workflowProperties.Originator)
        Dim InitiatorEmail = InitiatorObject.Email

        'get CC's email address
        Dim CCObject As SPUser = GetUserObject(CC)
        Dim CCEmail = CCObject.Email

        'get PeerReviewer's name
        Dim PeerReviewerObject As SPUser = GetUserObject(PeerReviewer)
        Dim PeerReviewerName = PeerReviewerObject.Name

        'get the comments entered by the peer reviewer
        Dim Comments As String = onPeerReviewerApprovalChanged.AfterProperties.ExtendedProperties("txtComments").ToString

        sendInitiatorApprovalTaskEmail_To = InitiatorEmail
        sendInitiatorApprovalTaskEmail_CC = CCEmail
        sendInitiatorApprovalTaskEmail_Subject = "Approval of " & workflowProperties.Item.File.Name & " has been assigned to you."
        sendInitiatorApprovalTaskEmail_Body = "<span style='font-family: arial; font-size: medium'>" & _
                                                 "Task assigned by " & PeerReviewerName & " on " & DateTime.Now & _
                                                 "</span>" & _
                                                 "<br>" & _
                                                 "<span style='font-family: arial; font-size: x-small'>" & _
                                                 "Due by " & DateTime.Today & _
                                                 "<br><br>" & _
                                                 "Instructions: <br>" & Instructions & _
                                                 "<br><br>" & _
                                                 "Please approve " & workflowProperties.Item.File.Name & _
                                                 "<br><br>" & _
                                                 "To complete this task:" & _
                                                 "<br><br>" & _
                                                 "    1. Review " & "<a href='" & workflowProperties.SiteUrl & "\" & workflowProperties.ItemUrl & "'>" & workflowProperties.Item.File.Name & "</a>" & "." & _
                                                 "<br>" & _
                                                 "    2. Use the <b>Edit this task</b> button to Approve/Reject the document." & _
                                                 "<br><br>" & _
                                                 "To view this workflow's history, click " & "<a href=" & workflowProperties.SiteUrl & "/_layouts/WrkStat.aspx?List=" & workflowProperties.ListId.ToString & "&WorkflowInstanceID=" & workflowProperties.WorkflowId.ToString & ">here</a>" & "." & _
                                                 "<br><br>" & _
                                                 "<font color=red>Comments:</font> <br>" & Comments & _
                                                 "</span>"

5. go back to the design surface and double-click PeerReviewerApprovalActivities to drill down into it

6. drag and drop a SendEmail activity between hlogPeerReviewerApproved and hlogWorkflowCompleted
    and set the following properties:
    a. Name: sendPeerReviewerApprovedEmail
    b. Body: click the ellipses, click the "Bind to a new member" tab,
             remove the 1 from the end of the "New member name" and click OK
    c. CC: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    d. CorrelationToken: choose workflowToken from dropdownlist
    e. Subject: click the ellipses, click the "Bind to a new member" tab,
                remove the 1 from the end of the "New member name" and click OK
    f. To: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    g. MethodInvoking: type InitiatorApprovalTaskEmail and hit enter
    h. You will be taken to the code stub for PeerReviewerApprovedEmail. Copy and paste the following code:

        'get Initiator's email address
        Dim InitiatorObject As SPUser = GetUserObject(workflowProperties.Originator)
        Dim InitiatorEmail = InitiatorObject.Email

        'get CC's email address
        Dim CCObject As SPUser = GetUserObject(CC)
        Dim CCEmail = CCObject.Email

        'get PeerReviewer's name
        Dim PeerReviewerObject As SPUser = GetUserObject(PeerReviewer)
        Dim PeerReviewerName = PeerReviewerObject.Name

        sendPeerReviewerApprovedEmail_To = InitiatorEmail
        sendPeerReviewerApprovedEmail_CC = CCEmail
        sendPeerReviewerApprovedEmail_Subject = workflowProperties.Item.File.Name & " has been approved by " & PeerReviewerName & ". Peer Review Complete."
        sendPeerReviewerApprovedEmail_Body = "<span style='font-family: arial; font-size: medium'>" & _
                                                 workflowProperties.Item.File.Name & " was approved by " & PeerReviewerName & " on " & DateTime.Now & _
                                                 "<br><br>" & _
                                                 "Peer Review Complete" & _
                                                 "<br><br>" & _
                                                 "<span style='font-family: arial; font-size: x-small'>" & _
                                                 "To view this workflow's history, click " & "<a href=" & workflowProperties.SiteUrl & "/_layouts/WrkStat.aspx?List=" & workflowProperties.ListId.ToString & "&WorkflowInstanceID=" & workflowProperties.WorkflowId.ToString & ">here</a>" & "." & _
                                                 "</span></span>"

7. drag and drop a SendEmail activity between hlogPeerReviewerRejected and setStateInitiatorApproval
    and set the following properties:
    a. Name: sendPeerReviewerRejectedEmail
    b. Body: click the ellipses, click the "Bind to a new member" tab,
             remove the 1 from the end of the "New member name" and click OK
    c. CC: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    d. CorrelationToken: choose workflowToken from dropdownlist
    e. Subject: click the ellipses, click the "Bind to a new member" tab,
                remove the 1 from the end of the "New member name" and click OK
    f. To: click the ellipses, click the "Bind to a new member" tab,
           remove the 1 from the end of the "New member name" and click OK
    g. MethodInvoking: type InitiatorApprovalTaskEmail and hit enter
    h. You will be taken to the code stub for PeerReviewerRejectedEmail. Copy and paste the following code:

        'get Initiator's email address
        Dim InitiatorObject As SPUser = GetUserObject(workflowProperties.Originator)
        Dim InitiatorEmail = InitiatorObject.Email

        'get CC's email address
        Dim CCObject As SPUser = GetUserObject(CC)
        Dim CCEmail = CCObject.Email

        'get PeerReviewer's name
        Dim PeerReviewerObject As SPUser = GetUserObject(PeerReviewer)
        Dim PeerReviewerName = PeerReviewerObject.Name

        sendPeerReviewerRejectedEmail_To = InitiatorEmail
        sendPeerReviewerRejectedEmail_CC = CCEmail
        sendPeerReviewerRejectedEmail_Subject = workflowProperties.Item.File.Name & " has been rejected by " & PeerReviewerName
        sendPeerReviewerRejectedEmail_Body = "<span style='font-family: arial; font-size: medium'>" & _
                                                 workflowProperties.Item.File.Name & " was rejected by " & PeerReviewerName & " on " & DateTime.Now & _
                                                 "<br><br>" & _
                                                 "<span style='font-family: arial; font-size: x-small'>" & _
                                                 "To view this workflow's history, click " & "<a href=" & workflowProperties.SiteUrl & "/_layouts/WrkStat.aspx?List=" & workflowProperties.ListId.ToString & "&WorkflowInstanceID=" & workflowProperties.WorkflowId.ToString & ">here</a>" & "." & _
                                                 "</span></span>"

Posts in this series:
Part 1: Introduction
Part 2: Create the initiation form
Part 3: Create the task form
Part 4: Create the state machine workflow
Part 5: Add workflow history logging
Part 6: Add task notification emails

How to create a SharePoint State Machine Workflow: Part 5 - Add workflow history logging

2009-08-20T22:55:00.007-04:00

Here in Part 5, We'll add history logging to the workflow. This is really useful as it allows the user to see messages about the status of the workflow, such as who approved it or rejected it. This part assumes you have completed part 4.

1. add this function to the code:

Private Function GetUserObject(ByVal accountID As String) As SPUser
If accountID.IndexOf("\") > 0 Then
Dim user As SPUser = Me.workflowProperties.Web.SiteUsers(accountID)
Return user
Else
Dim user As SPUser = Me.workflowProperties.Web.SiteUsers("OSS\" + accountID)
Return user
End If
End Function

2. go back to the design surface and double-click InitialStateActivities to drill down into it

3. drag and drop a LogToHistoryListActivity activity between onWorkflowActivated and setStatePeerReviewerApproval1
and set the following properties:
a. name: hlogWorkflowStarted
b. EventId: WorkflowStarted
c. HistoryDescription: Workflow started.
d. HistoryOutcome: create property hlogWorkflowStarted_HistoryOutcome
e. UserId: create property hlogWorkflowStarted_UserId

4. double-click the onWorkflowActivated activity to be taken to its code stub

5. copy and paste the following code to have 1. the workflow's originator assigned to the UserId property of the
logToHistory activity, and 2. the instructions entered by the originator assigned to the HistoryOutcome property:

'assign workflow's executor to the LogToHistory activity's user id
Dim executor As SPUser = GetUserObject(workflowProperties.Originator)
hlogWorkflowStarted_UserId = executor.ID

'assign the instructions to the HistoryOutcome property
hlogWorkflowStarted_HistoryOutcome = "Instructions: " & initform.txtInstructions

6. go back to the design surface and double-click InitiatorApprovalInitialization to drill down into it

7. drag and drop a LogToHistoryListActivity activity below createInitiatorApprovalTask
and set the following properties:
a. name: hlogInitiatorApprovalTaskCreated
b. EventId: TaskCreated
c. HistoryDescription: Initiator approval task created. Awaiting approval.
d. UserId: 0

8. go back to the design surface and double-click InitiatorApprovalActivities to drill down into it

9. drag and drop a LogToHistoryListActivity activity between ifInitiatorApproved and setStatePeerReviewerApproval
and set the following properties:
a. name: hlogInitiatorApproved
b. EventId: TaskCompleted
c. HistoryDescription: Initiator approved.
d. HistoryOutcome: create property hlogInitiatorApproved_HistoryOutcome
e. UserId: create property hlogInitiatorApproved_UserId

10. click on the onInitiatorApprovalChanged activity and set the following property
a. Executor: create property onInitiatorApprovalChanged_Executor

11. double-click onInitiatorApprovalChanged activity to be taken to its code stub

12. copy and paste the following code to have the task's executor assigned to the UserId property of the
logToHistory activity:

'assign task's executor to the LogToHistory activity's user id
Dim executor As SPUser = GetUserObject(onInitiatorApprovalChanged_Executor)
hlogInitiatorApproved_UserId = executor.ID

'assign the task's comments to the HistoryOutcome property
hlogInitiatorApproved_HistoryOutcome = "Comments: " & onInitiatorApprovalChanged.AfterProperties.ExtendedProperties("txtComments").ToString

13. go back to the design surface and double-click PeerReviewerApprovalInitialization to drill down into it

14. drag and drop a LogToHistoryListActivity activity below createPeerReviewerApprovalTask
and set the following properties:
a. name: hlogPeerReviewerApprovalTaskCreated
b. EventId: TaskCreated
c. HistoryDescription: Peer Reviewer approval task created. Awaiting approval.
d. UserId: 0

15. go back to the design surface and double-click PeerReviewerApprovalActivities to drill down into it

16. drag and drop a LogToHistoryListActivity activity between ifPeerReviewerApproved and setStateFinalState
and set the following properties:
a. name: hlogPeerReviewerApproved
b. EventId: TaskCompleted
c. HistoryDescription: Peer Reviewer approved.
d. HistoryOutcome: create property hlogPeerReviewerApproved_HistoryOutcome
e. UserId: create property hlogPeerReviewerApproved_UserId

17. drag and drop a LogToHistoryListActivity activity between ifPeerReviewerRejected and setStateInitiatorApproval
and set the following properties:
a. name: hlogPeerReviewerRejected
b. EventId: TaskCompleted
c. HistoryDescription: Peer Reviewer rejected.
d. HistoryOutcome: create property hlogPeerReviewerRejected_HistoryOutcome
e. UserId: create property hlogPeerReviewerRejected_UserId

18. click on the onPeerReviewerApprovalChanged activity and set the following property
a. Executor: create property onPeerReviewerApprovalChanged_Executor

19. double-click onPeerReviewerApprovalChanged activity to be taken to its code stub

20. copy and paste the following code to have the task's executor assigned to the UserId property of the
logToHistory activity:

'assign task's executor to the LogToHistory activity's user id
Dim executor As SPUser = GetUserObject(onPeerReviewerApprovalChanged_Executor)
hlogPeerReviewerApproved_UserId = executor.ID
hlogPeerReviewerRejected_UserId = executor.ID

'assign the task's comments to the HistoryOutcome property
hlogPeerReviewerApproved_HistoryOutcome = "Comments: " & onPeerReviewerApprovalChanged.AfterProperties.ExtendedProperties("txtComments").ToString
hlogPeerReviewerRejected_HistoryOutcome = "Comments: " & onPeerReviewerApprovalChanged.AfterProperties.ExtendedProperties("txtComments").ToString

21. go back to the design surface and double-click PeerReviewerApprovalActivities to drill down into it

22. drag and drop a LogToHistoryListActivity activity between hlogPeerReviewerApproved and setStateFinalState
and set the following properties:
a. name: hlogWorkflowCompleted
b. EventId: WorkflowCompleted
c. HistoryDescription: Workflow completed.
d. UserId: 0

How to create a SharePoint State Machine Workflow: Part 4 - Create the state machine workflow

2009-08-19T22:01:00.014-04:00

Here in Part 4, we create the workflow and deploy it to the SharePoint server. I have done these steps with both Visual Studio 2005 and 2008. When deploying, it tells you what to do based on whether you are using 2005 or 2008. Also, I included VB as well as C# code depending on your tastes. It seems like most everybody is using C#. We use VB in-house traditionally so I figured I would stay with VB. You'll notice that there really isn't a whole lot of code here at all - just lots and lots of steps. This workflow works off of four states: InitialState, InitiatorApproval, PeerReviewerApproval and FinalState.

1. In Visual Studio 2005, File -> New -> Project -> SharePoint -> SharePoint Server State Machine, call it AgendaItemPeerReview
In Visual Studio 2008, File -> New -> Project -> Visual Basic -> Office -> 2007 -> SharePoint 2007 State Machine Workflow,
call it AgendaItemPeerReview
set location to d:\asp or whatever you want
Rename Workflow1.vb to PeerReviewWorkflow.vb and doubleclick it to open the design surface.
It will start out with a state called Workflow1InitialState. Rename Workflow1InitialState to InitialState.

Note: The workflow MUST have a different name than the solution/project. Do NOT rename file workflow1.cs (and thus the
workflow1 class) to the same name you chose as the solution/project.

2. add three more states and name them InitiatorApproval, PeerReviewerApproval and FinalState

3. right click workflow and set CompletedStateFinish property to the new state you created called FinalState
be sure InitialStateName is InitialState

We will build the workflow by adding activities to the various states.
Afterwards, we will come back and add the necessary code. I do it this way because some code is autogenerated while
other code must be written by us, and by building the whole workflow first, all the generated code will be together,
then all our code will be together below the generated code. Also, this provides more of a top-down approach to
designing (and understanding) the workflow.

4. in state InitialState, click eventDrivenActivity1 and rename it to InitialStateActivities

5. double-click this activity to drill down into it; in here we will create a sequential workflow; notice there is
already an onWorkflowActivated1 event
a. Rename onWorkflowActivated1 to onWorkflowActivated.
b. Drill down into CorrelationToken and change OwnerActivityName to PeerReviewWorkflow.
c. Drill down into WorkflowProperties and change Name to PeerReviewWorkflow.

6. in the Toolbox, find the Windows Workflow section and drag and drop a SetState event below onWorkflowActivated
a. rename setState activity to setStatePeerReviewerApproval
b. set TargetStateName property to PeerReviewerApproval
c. click on PeerReviewWorkflow to go back to workflow view; notice the line drawn from InitialState to
state PeerReviewerApproval

For the two approval states, we are going to add the same stuff, ie initialization code for when a state is entered,
code to execute while in the state, and code to execute when the state is completed.

7. for each of the two states, drag and drop into them:
a. a StateInitialization activity
b. an EventDriven activity
c. a StateFinalization activity

8. in stateInitiatorApproval, rename the activities to:
InitiatorApprovalInitialization
InitiatorApprovalActivities
InitiatorApprovalFinalization

9. in statePeerReviewerApproval, rename the activities to:
PeerReviewerApprovalInitialization
PeerReviewerApprovalActivities
PeerReviewerApprovalFinalization

We will now add the specific tasks within each of these three activities (initialization, activities, finalization) for each state.
Essentially, we will be creating sequential workflows within each of these activities.

10. in InitiatorApproval, double-click InitiatorApprovalInitialization to drill down into it

11. drag and drop a CreateTask activity and set the following properties:
a. rename it createInitiatorApprovalTask
b. set CorrelationToken to InitiatorApprovalToken; click the + next to it to set the OwnerActivityName to
InitiatorApproval
c. for TaskId, click the ellipses, click the "Bind to a new member" tab, remove the 1 from the end of the "New member name"
and click OK
d. follow the same step for TaskProperties
e. exit this sequential workflow view by clicking on PeerReviewWorkflow on the design surface

12. double-click InitiatorApprovalFinalization to drill down into it

13. drag and drop a CompleteTask activity and set the following properties:
a. rename it completeInitiatorApprovalTask
b. set CorrelationToken to InitiatorApprovalToken; click the + next to it to set the OwnerActivityName to
InitiatorApproval
c. for TaskId, click the ellipses, on the "Bind to an existing member" tab, click createInitiatorApprovalTask_TaskId
d. exit this sequential workflow view by clicking on PeerReviewWorkflow on the design surface

14. double-click InitiatorApprovalActivities to drill down into it

15. drag and drop an OnTaskChanged activity and set the following properties:
a. rename it onInitiatorApprovalChanged
b. set CorrelationToken to InitiatorApprovalToken; click the + next to it to set the OwnerActivityName to
InitiatorApproval
c. for TaskId, click the ellipses, on the "Bind to an existing member" tab, click createInitiatorApprovalTask_TaskId
d. for AfterProperties and BeforeProperties, click the ellipses, click the "Bind to a new member" tab,
remove the 1 from the end of the "New member name" and click OK

16. drag and drop an IfElse activity and rename it InitiatorApprovalStatus

17. click on the left branch and set the following properties:
a. rename it ifInitiatorApproved
b. for Condition, click Code Condition

18. drag and drop a setState activity under ifInitiatorApproved
a. rename it setStatePeerReviewerApproval
b. set the TargetStateName to PeerReviewerApproval

19. click PeerReviewWorkflow to go back to higher-level view of workflow

20. in PeerReviewerApproval, double-click PeerReviewerApprovalInitialization to drill down into it

21. drag and drop a CreateTask activity and set the following properties:
a. rename it createPeerReviewerApprovalTask
b. set CorrelationToken to PeerReviewerApprovalToken; click the + next to it to set the OwnerActivityName to
PeerReviewerApproval
c. for TaskId, click the ellipses, click the "Bind to a new member" tab, remove the 1 from the end of the "New member name"
and click OK
d. follow the same step for TaskProperties
e. exit this sequential workflow view by clicking on PeerReviewWorkflow on the design surface

22. double-click PeerReviewerApprovalFinalization to drill down into it

23. drag and drop a CompleteTask activity and set the following properties:
a. rename it completePeerReviewerApprovalTask
b. set CorrelationToken to PeerReviewerApprovalToken; click the + next to it to set the OwnerActivityName to
PeerReviewerApproval
c. for TaskId, click the ellipses, on the "Bind to an existing member" tab, click createPeerReviewerApprovalTask_TaskId
d. exit this sequential workflow view by clicking on PeerReviewWorkflow on the design surface

24. double-click PeerReviewerApprovalActivities to drill down into it

25. drag and drop an OnTaskChanged activity and set the following properties:
a. rename it onPeerReviewerApprovalChanged
b. set CorrelationToken to PeerReviewerApprovalToken; click the + next to it to set the OwnerActivityName to
InitiatorApproval
c. for TaskId, click the ellipses, on the "Bind to an existing member" tab, click createPeerReviewerApprovalTask_TaskId
d. for AfterProperties and BeforeProperties, click the ellipses, click the "Bind to a new member" tab,
remove the 1 from the end of the "New member name" and click OK

26. drag and drop an IfElse activity and rename it PeerReviewerApprovalStatus

27. click on the left branch and set the following properties:
a. rename it ifPeerReviewerApproved
b. for Condition, click Code Condition

28. drag and drop a setState activity under ifPeerReviewerApproved
a. rename it setStateFinalState
b. set the TargetStateName to FinalState

29. click on the right branch and set the following properties:
a. rename it ifPeerReviewerRejected
b. for Condition, click Code Condition

30. drag and drop a setState activity under ifPeerReviewerRejected
a. rename it setStateInitiatorApproval
b. set the TargetStateName to InitiatorApproval

Now we are ready to start adding code. First we will add code in InitialState, for when the workflow starts.

31. Go to the code-behind and find the following line (this is the VB version, but the C# version looks almost identical):
Public workflowProperties As SPWorkflowActivationProperties = New Microsoft.SharePoint.Workflow.SPWorkflowActivationProperties

Above it, type:

VISUAL BASIC
------------
Public workflowId As System.Guid

VISUAL C#
---------
public Guid workflowId = default(System.Guid);

Below the workflowProperties line, type:

VISUAL BASIC
------------
Dim PeerReviewer As String
Dim CC As String
Dim Instructions As String

VISUAL C#
---------
private String PeerReviewer = default(String);
private String CC = default(String);
private String Instructions = default(String);

32. back on design surface, double-click InitialStateActivitites to drill down into it

33. double-click onWorkflowActivated. This will take you to the code behind and show the generated code stub
onWorkflowActivated_Invoked. Copy and paste the following code into it:

VISUAL BASIC
------------
workflowId = workflowProperties.WorkflowId

Dim serializer As XmlSerializer = New XmlSerializer(GetType(InitForm))
Dim reader As XmlTextReader = New XmlTextReader(New System.IO.StringReader(workflowProperties.InitiationData))
Dim initform As InitForm = CType(serializer.Deserialize(reader), InitForm)

Dim prPeerReviewer() As Person
prPeerReviewer = initform.gpPeerReviewer
PeerReviewer = prPeerReviewer(0).AccountId

Dim prCC() As Person
prCC = initform.gpCC
CC = prCC(0).AccountId

Instructions = initform.txtInstructions

VISUAL C#
---------
workflowId = workflowProperties.WorkflowId;

XmlSerializer serializer = new XmlSerializer(typeof(InitForm));
XmlTextReader reader = new XmlTextReader(new System.IO.StringReader(workflowProperties.InitiationData));
InitForm initform = (InitForm)serializer.Deserialize(reader);

Person prPeerReviewer = new Person();
prPeerReviewer = (Person)initform.gpPeerReviewer[0];
//PeerReviewer = prPeerReviewer.AccountId.GetValue(0).ToString();
PeerReviewer = prPeerReviewer.AccountId;

Person prCC = new Person();
prCC = (Person)initform.gpCC[0];
//CC = prCC.AccountId.GetValue(0).ToString();
CC = prCC.AccountId;

Instructions = initform.txtInstructions;

34. go to the top of PeerReviewWorkflow.vb and add the following code:

VISUAL BASIC
------------
imports System.Xml.Serialization
imports System.Xml

VISUAL C#
---------
using System.Xml.Serialization;
using System.Xml;

Next, we will add code to the InitiatorApproval state.

35. go back to the design surface and double-click InitiatorApprovalInitialization to drill down into it

36. double-click createInitiatorApprovalTask to be taken to its MethodInvoking code stub. Copy and paste
the following code in it.

VISUAL BASIC
------------
createInitiatorApprovalTask_TaskId = Guid.NewGuid
createInitiatorApprovalTask_TaskProperties = new SPWorkflowTaskProperties
createInitiatorApprovalTask_TaskProperties.Title = "Initiator Approval of " & workflowProperties.Item.File.Name
createInitiatorApprovalTask_TaskProperties.AssignedTo = workflowProperties.Originator
createInitiatorApprovalTask_TaskProperties.Description = ""
createInitiatorApprovalTask_TaskProperties.TaskType = 0
createInitiatorApprovalTask_TaskProperties.ExtendedProperties("txtInstructions") = Instructions

VISUAL C#
---------
createInitiatorApprovalTask_TaskId = Guid.NewGuid();
createInitiatorApprovalTask_TaskProperties = new SPWorkflowTaskProperties();
createInitiatorApprovalTask_TaskProperties.Title = "Initiator Approval of " + workflowProperties.Item.File.Name;
createInitiatorApprovalTask_TaskProperties.AssignedTo = workflowProperties.Originator;
createInitiatorApprovalTask_TaskProperties.Description = "";
createInitiatorApprovalTask_TaskProperties.TaskType = 0;
createInitiatorApprovalTask_TaskProperties.ExtendedProperties["txtInstructions"] = Instructions;

37. go back to the design surface and double-click InitiatorApprovalActivities to drill down into it

38. double-click onInitiatorApprovalChanged to be taken to its Invoked code stub. Copy and paste
the following code in it.

VISUAL BASIC
------------
onInitiatorApprovalChanged_AfterProperties = onInitiatorApprovalChanged.AfterProperties
onInitiatorApprovalChanged_BeforeProperties = onInitiatorApprovalChanged.BeforeProperties

VISUAL C#
---------
onInitiatorApprovalChanged_AfterProperties = onInitiatorApprovalChanged.AfterProperties;
onInitiatorApprovalChanged_BeforeProperties = onInitiatorApprovalChanged.BeforeProperties;

39. go back to the design surface and click ifInitiatorApproved and set the following properties:
a. drill down into the Condition property (already set to Code Condition), and next to the second
Condition property, type InitiatorApproved and hit enter
b. you will be taken to the code stub for InitiatorApproved routine; copy and paste the following
code into it:

VISUAL BASIC
------------
If onInitiatorApprovalChanged_AfterProperties.ExtendedProperties("status").ToString = "accepted" Then
e.Result = True
End If

VISUAL C#
---------
if (onInitiatorApprovalChanged_AfterProperties.ExtendedProperties["status"].ToString() == "accepted")
{
e.Result = true;
}

Next, we will add code to the PeerReviewerApproval state.

40. go back to the design surface and double-click PeerReviewerApprovalInitialization to drill down into it

41. double-click createPeerReviewerApprovalTask to be taken to its MethodInvoking code stub. Copy and paste
the following code in it.

VISUAL BASIC
------------
createPeerReviewerApprovalTask_TaskId = Guid.NewGuid
createPeerReviewerApprovalTask_TaskProperties = new SPWorkflowTaskProperties
createPeerReviewerApprovalTask_TaskProperties.Title = "Peer Reviewer Approval of " & workflowProperties.Item.File.Name
createPeerReviewerApprovalTask_TaskProperties.AssignedTo = PeerReviewer
createPeerReviewerApprovalTask_TaskProperties.Description = ""
createPeerReviewerApprovalTask_TaskProperties.TaskType = 0
createPeerReviewerApprovalTask_TaskProperties.ExtendedProperties("txtInstructions") = Instructions

VISUAL C#
---------
createPeerReviewerApprovalTask_TaskId = Guid.NewGuid();
createPeerReviewerApprovalTask_TaskProperties = new SPWorkflowTaskProperties();
createPeerReviewerApprovalTask_TaskProperties.Title = "Peer Reviewer Approval of " + workflowProperties.Item.File.Name;
createPeerReviewerApprovalTask_TaskProperties.AssignedTo = PeerReviewer;
createPeerReviewerApprovalTask_TaskProperties.Description = "";
createPeerReviewerApprovalTask_TaskProperties.TaskType = 0;
createInitiatorApprovalTask_TaskProperties.ExtendedProperties["txtInstructions"] = Instructions;

42. go back to the design surface and double-click PeerReviewerApprovalActivities to drill down into it

43. double-click onPeerReviewerApprovalChanged to be taken to its Invoked code stub. Copy and paste
the following code in it.

VISUAL BASIC
------------
onPeerReviewerApprovalChanged_AfterProperties = onPeerReviewerApprovalChanged.AfterProperties
onPeerReviewerApprovalChanged_BeforeProperties = onPeerReviewerApprovalChanged.BeforeProperties

VISUAL C#
---------
onPeerReviewerApprovalChanged_AfterProperties = onPeerReviewerApprovalChanged.AfterProperties;
onPeerReviewerApprovalChanged_BeforeProperties = onPeerReviewerApprovalChanged.BeforeProperties;

44. go back to the design surface and click ifPeerReviewerApproved and set the following properties:
a. drill down into the Condition property (already set to Code Condition), and next to the second
Condition property, type PeerReviewerApproved and hit enter
b. you will be taken to the code stub for PeerReviewerApproved routine; copy and paste the following
code into it:

VISUAL BASIC
------------
If onPeerReviewerApprovalChanged_AfterProperties.ExtendedProperties("status").ToString = "accepted" Then
e.Result = True
End If

VISUAL C#
---------
if (onPeerReviewerApprovalChanged_AfterProperties.ExtendedProperties["status"].ToString() == "accepted")
{
e.Result = true;
}

45. go back to the design surface and click ifPeerReviewerRejected and set the following properties:
a. drill down into the Condition property (already set to Code Condition), and next to the second
Condition property, type PeerReviewerRejected and hit enter
b. you will be taken to the code stub for PeerReviewerApproved routine; copy and paste the following
code into it:

VISUAL BASIC
------------
If onPeerReviewerApprovalChanged_AfterProperties.ExtendedProperties("status").ToString = "rejected" Then
e.Result = True
End If

VISUAL C#
---------
if (onPeerReviewerApprovalChanged_AfterProperties.ExtendedProperties["status"].ToString() == "rejected")
{
e.Result = true;
}

46. sign the assembly
a. right-click the project, then click properties
b. click Signing
c. if Sign the assembly is not already checked...
d. check Sign the assembly
e. choose <new> from the dropdown
f. enter MyKeyFile for the key file name
g. uncheck Protect my key file with a password
h. click OK

47. follow instructions above for creating the workflow's Initiation and Task forms using Microsoft Office InfoPath

48. If developing in Visual Studio 2005: copy PeerReviewInit.xsn and PeerReviewTask.xsn to DeploymentFiles\FeatureFiles folder

49. be sure feature.xml is set up correctly
a. title: Agenda Item Peer Review feature
b. description: This feature installs the Agenda Item Peer Review workflow
c. if deploying via Visual Studio 2008:
under the <ElementManifests> tag, add:
<ElementFile Location="PeerReviewInit.xsn" />
<ElementFile Location="PeerReviewTask.xsn" />

50. be sure workflow.xml is set up correctly
a. name: AgendaItemPeerReview
b. description: This is the Agenda Item Peer Review workflow
c. CodeBesideClass: AgendaItemPeerReview.PeerReviewWorkflow
d. after CodeBesideAssembly, you must have the following:
TaskListContentTypeId="0x01080100C9C9515DE4E24001905074F980F93160"
e. after TaskListContentTypeId, you must have the following:
AssociationUrl="_layouts/CstWrkflIP.aspx"
InstantiationUrl="_layouts/IniWrkflIP.aspx"
ModificationUrl="_layouts/ModWrkflIP.aspx"
f. copy initiation form's urn into the <Association_FormURN> and <Instantiation_FormURN> tags
g. copy task form's urn into the <Task0_FormURN> tag

51. deploy solution
a. Visual Studio 2005: right click project, click Properties, click Build Events, change NODEPLOY to
DEPLOY at the end of the Post-build event command line, click Build, click Rebuild Solution
b. Visual Studio 2008: click Build, then click Deploy Solution

52. The first time you deploy it, the AgendaItemPeerReview assembly is added to the GAC. The workflow.xml
file needs the assembly's public key token.
a. Start, Settings, Control Panel, Administrative Tools, Microsoft .NET Framework 2.0 Configuration
b. click Manage the Assembly Cache
c. click View List of Assemblies in the Assembly Cache
d. right-click on AgendaItemPeerReview and click Properties
e. copy the public key token and click OK
f. paste the public key token in workflow.xml where you find PublicKeyToken
g. redeploy solution (step 51)

Another method for retrieving the assembly's public key token
-------------------------------------------------------------
If you want to skip step 52, retrieve the public key token using the sn.exe utility then
update workflow.xml (step 50) with it

1. copy sn.exe from c:\program files\microsoft visual studio 8\sdk\v2.0\bin to d:\
2. change directory to d:\asp\agendaitempeerreview\agendaitempeerreview\bin\debug
3. d:\sn -T agendaitempeerreview.dll
4. copy (or type) the resulting public key token into the workflow.xml

How to create a SharePoint State Machine Workflow: Part 3 - Create the task form

2009-08-19T21:48:00.007-04:00

In Part 3, we will create the workflow's task form. In Part 4, we will configure this form to be called as the task form.

1. load Microsoft Office InfoPath 2007
2. Under Design a form, click Design a Form Template, click Blank, then click OK
3. click Insert, Layout Table..., 2 columns, 3 rows, click OK
4. add three buttons to the right column, last row
5. in Design Tasks, click Data Source
a. double-click myFields and rename it to TaskForm and click OK
b. right-click TaskForm and click Add...
c. for name, type status
d. click OK
6. double-click the first button
a. change Label to Approve
b. click Rules...
c. click Add...
d. click Add Action...
e. select Submit using a data connection from dropdown
f. click Add...
g. be sure Create a new connection to submit data is selected and click Next
h. select To the hosting environment, such as an ASP.NET page or a hosting application
i. leave Submit as the name for the data connection and click Finish
j. click OK
k. click Add Action...
l. select Set a field's value
m. click icon to the right of the Field textbox
n. click status and click OK
o. for value, type: accepted
p. click OK
q. click Add Action...
r. select Close the form from the dropdown
s. uncheck If changes have not been saved...
t. click OK
u. click OK
v. click OK
w. click OK
7. double-click the second button
a. change Label to Reject
b. click Rules...
c. click Add...
d. click Add Action...
e. select Submit using a data connection from dropdown
f. click Add...
g. be sure Create a new connection to submit data is selected and click Next
h. select To the hosting environment, such as an ASP.NET page or a hosting application
i. leave Submit as the name for the data connection and click Finish
j. click OK
k. click Add Action...
l. select Set a field's value
m. click icon to the right of the Field textbox
n. click status and click OK
o. for value, type: rejected
p. click OK
q. click Add Action...
r. select Close the form from the dropdown
s. uncheck If changes have not been saved...
t. click OK
u. click OK
v. click OK
w. click OK
8. double-click the third button
a. change Label to Cancel
b. click Rules...
c. click Add...
d. click Add Action...
e. select Close the form from the dropdown
f. uncheck If changes have not been saved...
g. click OK
h. click OK
i. click OK
j. click OK
9. in left column, first row, type: Instructions
10. in left column, second row, type: Comments
11. in the right column, first row, drop a text box control into it
a. double-click the text box control
b. change field name to txtInstructions
c. click Display tab and check Multi-line
d. click OK
e. drag the bottom edge of the control down a little ways so a few lines of text will show
12. in the right column, second row, drop a text box control into it
a. double-click the text box control
b. change field name to txtComments
c. click Display tab and check Multi-line
d. click OK
e. drag the bottom edge of the control down a little ways so a few lines of text will show
13. when the task form loads, we want txtInstructions to populate automatically with what was typed in
to txtInstructions on the initiation form
a. on the Desktop, create a file called ItemMetadata.xml (CASE IS EXTREMELY IMPORTANT!!!) with the following text in it:
<z:row xmlns:z="#RowsetSchema" ows_txtInstructions="" />
b. in Design Tasks, click Data Source, click Manage Data Connections... (near bottom)
c. click Add
d. click Create a connection to Receive data
e. click Next
f. be sure XML document is selected and click Next
g. click Browse and select ItemMetadata.xml from Desktop
h. click Next
i. be sure Include the data as a resource file... is selected and click Next
j. click Finish
k. click Close
l. double-click txtInstructions
m. click the fx button next to the value text field
n. click Insert Field or Group...
o. change data source in drop down to ItemMetadata (Secondary)
p. click :ows_txtInstructions
q. click Ok
r. click Ok
s. click Ok
Note: In the code that creates the tasks in the workflow, we will add txtInstructions to the task's
ExtendedProperties and populate it with txtInstructions from the initiation form. ItemMetaData.xml
will get this value from the task's txtInstructions property (added in ExtendedProperties) and will
then populate the task form's txtInstructions textbox on load.
14. make form be able to open in a browser or in a client application
a. in Design Tasks, click Design Checker, click Change Compatibility Settings...
b. in the Compatibility category, check Design a form template that can be opened in a browser or InfoPath
c. in the Security and Trust category, uncheck Automatically determine security level, click Full Trust
d. click OK
15. save form in My Documents as PeerReviewTask.xsn
16. retrieve the form's id
a. click File, Properties
b. copy text in ID textbox into notepad to be used in a later step. it should look like this:
urn:schemas-microsoft-com:office:infopath:PeerReviewTask:-myXSD-2008-07-30T18-33-30
17. publish the InfoPath form
a. click File, Publish
b. select To a network location
c. click Next
d. browse to the workflow project's location and name the file PeerReviewTask.xsn
e. click OK
f. click Next
g. delete the path in the textbox and click Next
h. click Publish
i. click Close

How to create a SharePoint State Machine Workflow: Part 2 - Create the initiation form

2009-08-19T21:15:00.012-04:00

In Part 2, we will create the workflow's initiation form. In Part 4, we will configure this form to be called in two locations: first, when a user associates the workflow with a document library, and second, when a user instantiates the workflow on a particular document. Thus, we are using the same form as both the association form and the initiation form. Its possible to use different forms collecting different information, but for simplicity, we will use the same form for both.

1. load Microsoft Office InfoPath 2007
2. Under Design a form, click Design a Form Template, click Blank, then click OK
3. if the Contact Selector control has not been added to the controls list, you will need to add it
a. on the Design Tasks pane, click Controls; if Contact Selector does not appear
under the Custom controls in the bottom of the list, continue with the following
steps. If it does appear there (ie you already added it), skip to step 4
b. click Add or Remove Custom Control...
c. click Add button
d. click ActiveX Control and click Next
e. click Contact Selector from the list and click Next
f. click Don't include a .cab file and click Next
g. click Value and click Next
h. in the Field or group type dropdown, select Field or Group (any data type) and click Finish, Close, OK
4. click Insert, Layout Table..., 2 columns, 4 rows, click OK
5. add two buttons to the right column, last row
6. double-click the first button
a. change Label to OK
b. click Rules...
c. click Add...
d. click Add Action...
e. select Submit using a data connection from dropdown
f. click Add...
g. be sure Create a new connection to submit data is selected and click Next
h. select To the hosting environment, such as an ASP.NET page or a hosting application
i. leave Submit as the name for the data connection and click Finish
j. click OK
k. click Add Action...
l. select Close the form from the dropdown
m. uncheck If changes have not been saved...
n. click OK
o. click OK
p. click OK
q. click OK
r. stretch out OK button
7. double-click the second button
a. change Label to Cancel
b. click Rules...
c. click Add...
d. click Add Action...
e. select Close the form from the dropdown
f. uncheck If changes have not been saved...
g. click OK
h. click OK
i. click OK
j. click OK
8. in left column, first row, type: Peer Reviewer
9. in left column, second row, type: CC
10. in left column, third row, type: Instructions
11. in the right column, third row, drop a text box control into it
a. double-click the text box control
b. change field name to txtInstructions
c. click Display tab and check Multi-line
d. click OK
12. resize left column to be smaller than right column, resize txtInstructions to allow
for multiple lines
13. in the right column, first row, drop a Contact Selector control into it
a. double-click the control, rename it to gpPeerReviewer, click OK
14. in the right column, second row, drop a Contact Selector control into it
a. double-click the control, rename it to gpCC, click OK
15. in Design Tasks, click Data Source
a. double-click myFields and rename it to InitForm and click OK
b. right click group1 and delete it
c. right click gpPeerReviewer and click Add
d. name is Person, the type is Group, check Repeating
e. right click Person, click Add..., enter name as DisplayName, click OK
f. right click Person, click Add..., enter name as AccountId, click OK
g. right click Person, click Add..., enter name as AccountType, click OK
h. right click Person, click Reference..., click gpCC, click OK
16. make form be able to open in a browser or in a client application
a. in Design Tasks, click Design Checker, click Change Compatibility Settings...
b. in the Compatibility category, check Design a form template that can be opened in a browser or InfoPath
c. in the Security and Trust category, uncheck Automatically determine security level, click Full Trust
d. click OK
17. create the context for the form so it knows where to retrieve people's names from:
a. open Notepad and type in the following and save it as Context.xml in the same folder as the workflow:
<Context
isStartWorkflow="true"
isRunAtServer="true"
provideAllFields="true"
siteUrl="http://sharepoint2007:100"
/>
Note: be sure siteUrl is for your site!!!
18. add a secondary data source using Context.xml so form can retrieve contact data:
a. in Design Tasks, Data Source, click Manage Data Connections...
b. click Add...
c. Create a new connection to Receive Data
d. click Next
e. click XML document
f. click Next
g. browse to Context.xml
h. click Next
i. click Include the data as a resource file in the form template or template part
j. click Next
k. leave Context as the name of the data connection
l. ensure Automatically retrieve data when form is opened is checked
m. click Finish
n. click Close
19. save form in My Documents as PeerReviewInit.xsn
20. retrieve the form's id
a. click File, Properties
b. copy text in ID textbox into notepad to be used in a later step. it should look like this:
urn:schemas-microsoft-com:office:infopath:PeerReviewInit:-myXSD-2008-07-23T13-50-07
21. publish the InfoPath form
a. click File, Publish
b. select To a network location
c. click Next
d. browse to the workflow project's location and name the file PeerReviewInit.xsn
e. click OK
f. click Next
g. delete the path in the textbox and click Next
h. click Publish
i. click Close
22. create the schema for the form so the workflow can reference the contents of the form
a. click File, Save as source files...
b. browse to the folder where the workflow is
c. click OK
d. close Microsoft InfoPath (you will not be able to make any changes to the form once InfoPath is closed)
e. click Start, Run, type CMD and click OK
f. change folder to the workflow's folder
g. type: xsd myschema.xsd /c /language:VB (Note: you may have to find xsd.exe on your HD first)
h. rename the resulting myschema.vb to InitForm.vb
23. add file to workflow project
a. in Visual Studio in Solution Explorer, Show All Files
b. right-click InitForm.vb and click Include In Project

How to create a SharePoint State Machine Workflow: Part 1 - Introduction

2009-08-19T20:35:00.011-04:00

A while back I was tasked with creating a SharePoint workflow that would enable peer review of a document. (BTW, this whole article series will be all about creating workflows with Visual Studio, not SharePoint Designer.) An initiator would assign the workflow to a document in a document library and set who they wanted to peer review it. Now, if you've searched the internet for SharePoint workflows, you've undoubtedly seen that one sequential workflow that always pops up in examples. The problem is that sometimes a sequential workflow doesn't cut it - you just might need a state machine workflow. Imagine having a workflow where someone wants to send a document out for approval to three people sequentially, like a manager, a division director, and a department director. After the manager approves it, it goes to the division director, then when that person approves it, the department director gets it. But what if the division director rejects it? You might want it to bounce back to the manager. Similarly, if the department director rejects it, it goes back to the division director. The state machine workflow is the way to do this as each person will be a state.

This will be a six part series on how to create a SharePoint state machine workflow, although only the first four parts are necessary to create a functioning workflow
.
This example will employ a simple peer review model. An initiator will start a workflow on a document in a document library, assigning the person they want to act as the peer reviewer in the Initiation form. The workflow then starts. The peer reviewer will get a task. If the peer reviewer approves the task, the workflow is complete. If the peer review rejects the task, the initiator will get a task. In theory, the initiator could make changes to their document, and once they are done, they would approve the task, thus moving the flow back to the peer reviewer again. Once again, the peer reviewer would need to accept the task (which ends the workflow) or reject it (which sends the flow back to the initiator).

You are currently reading Part 1 of this series.
Part 2 will focus on using InfoPath to create the workflow's Initiation form.
Part 3 will focus on using InfoPath to create the workflow's Task form.
Part 4 will focus on creating the state machine workflow itself.

After part 4, you will have a fully functioning workflow. The following two parts are more like enhancements, but you'll likely want them.

Part 5 will focus on adding workflow history logging to the workflow.
Part 6 will focus on adding task notification emails to the workflow.

How to deploy a SharePoint web part to bin

2009-07-23T21:00:00.043-04:00

As I was learning how to deploy my web parts as features in a solution package .wsp (I used WSPBuilder to create the .wsp), I realized I needed to make sure they were deployed not to the GAC (which is the default), but rather to the web application's /bin folder (under the web application in IIS). Bin is preferred over GAC because of security reasons: deploying to GAC unnecessarily exposes the web part's assembly .dll to every application on the server.

This post will show you how to deploy a web part to the /bin folder (using WSPBuilder) AND how to configure it using CAS (Code Access Security) so your web part can actually run from that folder too! I kept finding articles that discuss one or the other, but not both. Those articles that did help me quite a bit have been referenced in the last part of this post.

So, from the top, when you create a web part in Visual Studio 2008 and hit F5, the web part will deploy to the site you selected (right-click Project's Properties, click Debug, then whatever site you typed in Start browser with URL). In your Solution Explorer, you will notice a folder called /bin with another folder called /debug under that, and the compiled code will sit under there. This means its being deployed into the GAC.

At a high level, there's really two steps we must do to get our web part to run from the web application's (your SharePoint site's) /bin folder. (You can get to /bin either by going into IIS and choosing the web application you want it deployed to, or by going to c:\inetpub\wwwroot\wss\VirtualDirectories\<web application>\bin.)

The first step is actually deploying to the above-mentioned location. Once this is done, sure, the web part is right where you want it to be, but it won't run until we do step two, which involves setting the proper permissions to allow it to run from that spot. This second step involves modifying the web.config to look at a custom policy file where we will make changes to the CAS policies.

First, deploy the web part assembly to the /bin:

1. In Solution Explorer, delete the /bin folder. It will reappear in a few seconds with a Debug subfolder, but it will be empty other than that.

2. In Solution Explorer, create a folder called 80, and under that, create a folder called bin. So you will have /80/bin.

3. Right-click the project in Solution Explorer, and on the Compile tab, change Build Output Path from bin\Debug\ to 80\bin\.

4. In Solution Explorer, in AssemblyInfo.vb, you must add two lines:
a. below the other Imports statements, add the following:

Imports System.Security

(Note: this will be a Using statement if you are doing C#)

b. Below one of the other Assembly statements, add the following:

<assembly: AllowPartiallyTrustedCallers()>

(Note: This step doesn't affect the deployment of the web part, but comes into play when you try to actually use the web part on a page after its been deployed to /bin.)

5. Now, when you compile the application you will notice the assembly (the dll) appears in /80/bin instead of where it was being put before, /bin/debug. If you hit F5 to deploy it, you will notice all the other deployment files Visual Studio creates is also placed in this folder. This leads me to my next point.

Visual Studio creating deployment files automatically is no good. Sure, it will get everything up and running on the server, but maybe not the way you want. For instance, even though I have created a /12/TEMPLATE/FEATURES/AddContactFromAD folder structure in my Solution Explorer, and put in my feature.xml, elements.xml (mine is actually called AddContactFromAD.xml), and a web part definitions file AddContactFromAD.webpart, Visual Studio generates its own feature.xml (which doesn't have my pretty description I put in the real feature.xml). It also tends to write its own manifest.xml, wanting to deploy to GAC! So, let's deploy a much better way, using WSPBuilder! You can download WSPBuilder here. Once installed, it will be added to Visual Studio's Tools menu.

6. Assuming you have the above-mentioned 12 hive folder structure with a folder for each web part under FEATURES, and with that, a feature.xml, elements.xml, and .webpart file under each web part's folder, you can simply click Tools -> WSPBuilder -> Build WSP. WSP Builder will create the resulting .wsp and drop it in your project folder. Renaming it to .cab and opening it you will see each web part's feature.xml, elements.xml, .webpart, plus the assembly .dll and an autogenerated manifest.xml. Looking inside the manifest.xml will reveal two things: 1. the DeploymentTarget is WebApplication (no longer GlobalAssemblyCache as it was before), and 2. CAS policy permissions were added.

7. Ok, so let's deploy this bad boy. To do this, I add the solution, deploy the solution, then activate the features (1 feature per web part). Below is my own batch file add.bat:

stsadm -o addsolution -filename contactuswebpart.wsp

stsadm -o deploysolution -name contactuswebpart.wsp -url http://sharepoint2007:1001/ -immediate -allowCasPolicies

stsadm -o activatefeature -name contactlist -url http://sharepoint2007:1001

stsadm -o activatefeature -name emailcontact -url http://sharepoint2007:1001

stsadm -o activatefeature -name addcontactfromad -url http://sharepoint2007:1001

Also, my remove.bat comes in handy when testing:

stsadm -o deactivatefeature -name contactlist -url http://sharepoint2007:1001

stsadm -o deactivatefeature -name emailcontact -url http://sharepoint2007:1001

stsadm -o deactivatefeature -name addcontactfromad -url http://sharepoint2007:1001

stsadm -o retractsolution -name contactuswebpart.wsp -url http://sharepoint2007:1001/ -immediate

stsadm -o deletesolution -name contactuswebpart.wsp

At this point, if you check your web application's /bin, you should see the assembly .dll there. If you go to the Web Part Gallery and click the web part, or if you attempt to add the web part to a page, you will get an error. This is because we still need to do Part 2 of this grand adventure: modify the permissions.

For the second and final step, set the CAS policy permissions to enable the web part to run from /bin:

1. We are going to copy the existing wss_minimaltrust.config, rename it, then make our policy changes in that file. Go to c:\Program Files\Common Files\Microsoft Shared\web server extensions\12\CONFIG, copy wss_minimaltrust.config and rename it wss_webpartbintrust.config.

2. In our new CAS policy file, wss_webpartbintrust.config, we have three changes.

a. First, add a reference to SharePointPermission in the <SecurityClasses> section. Add the following:

b. Next, add a new custom permission set. Find the NamedPermissionSet that is named SPRestricted and copy and paste this below it:

c. Finally, add the code group. This will indicate when the permissions are to be set. It should be noted this can be done one of two ways, either using a strong name membership (assuming your assembly has been strongnamed) or a url membership, which would give you the option of having the permissions apply to all assemblies in the specified bin or the specific assembly itself.

Under <CodeGroup class="FirstMatchCodeGroup"...> you will see several <CodeGroup class="UnionCodeGroup"...> tags. Place the following code as the first one of these.

(Note: The PublicKeyBlob must be the public key blob of your assembly. You may see the PublicKeyBlob in another tag referencing your assembly, in which case, just copy and paste it. Otherwise, you will need to run the command: secutil -hex -s contactuswebpart.dll > publickeyblob.txt, then copy and paste it from the output file publickeyblob.txt.)

3. Almost there... Just two more changes, but this time in your site's web.config. Go to c:\inetpub\wwwroot\wss\VirtualDirectories\<your site>\web.config.

a. In the SecurityPolicy tag, make sure there is an entry for a custom TrustLevel that points to the policy file we just edited:

b. Scroll down a bit and make sure the trust level is set like this:

That's it! Restart IIS and have fun!

Some good pages that helped me figure this all out:

WSPBuilder - Walkthrough of the Visual Studio Add-in

MOSS 2007 and Code Access Security

Gaurav Taneja article on bin and GAC deployment

Deploy dlls to the webApplications bin rather than GAC

Code Access Security in SharePoint 2007 for Administrators

How to create connected web parts: Part 2

2009-07-12T21:28:00.010-04:00

Here in Part 2, you will find my tutorial on how to create Contact List/Email Contact connected web parts, along with entire code to be copy and pasted. I recommend following the tutorial, the at the end I will describe what's happening with respect to the transfer of a selected person from one web part to the other.

At a high level:

In the following project, we will create two web parts, a web part called Contact List that will display data from a custom list also called Contact List; and another web part called Email Contact, which will 1. save the message a user types into its form to a custom list called Sent Emails, then 2. email that message to the selected contact person. When a user clicks a contact in the Contact List web part, the person will then appear at the top of the Email Contact web part above the form the user can enter a message into. This transfer of a selected person from the Contact List web part to the Email Contact web part is what requires the web parts to be connected web parts. This connected web part setup also allows us the flexibility of displaying the Contact List by itself, or pairing it with other consumer web parts we develop down the road.

In summary:

Contact List web part requires a custom list called Contact List. Contact List web part will be the provider web part, providing a person to a consumer web part, in this example it will be the Email Contact web part.
Email Contact web part requires a custom list called Sent Emails. Email Contact web part will be the consumer, consuming a person from a provider web part, in this example it will be the Contact List web part.
The two web parts will both use the same interface, we'll call it IContact.
Once both web parts are built and deployed, they can then be individually added to a page on your SharePoint site, then you will connect them by clicking either web part -> Modify Shared Web Part -> Connections

Ok, so that was the all the high-level stuff. Let's do this step by step from the beginning. All you have to do is click along and paste code.

I. First, the easy part - we have to create the two custom lists Contact List
and Sent Emails in your SharePoint site.

In your SharePoint site, click Site Actions -> Create -> Custom List
for Name, type Contact List
click Create
click Contact List in the left menu
click Settings -> List Settings
click Title column, rename to Contact Name, click OK
click Create Column, for Column name type Job Title, click OK
click Create Column, for Column name type Email Address, click OK
click Create Column, for Column name type Phone, click OK
click Create Column, for Column name type Fax, click OK
Now that you have created the contact list, enter in 2 or 3 contacts by clicking Contact List, then New -> New Item, then fill out ALL the fields (including the phone and fax) and click OK (I still need to add error handling on the web part if a value is empty)
In your SharePoint site, click Site Actions -> Create -> Custom List
for Name, type Sent Emails
click Create
click Sent Emails in the left menu
click Settings -> List Settings
click Title column, and rename to Message Subject, click OK
click Create Column, for Column name type Submitter Name, click OK
click Create Column, for Column name type Submitter Email, click OK
click Create Column, for Column name type Message, click OK
click Create Column, for Column name type Contact Email, click OK

II. Now, we create the interface and web parts in Visual Studio 2008.

load Visual Studio 2008
File -> New -> Project -> Visual Basic -> SharePoint -> Web Part
for Name and Solution Name, type: ContactUs
Click OK
In Solution Explorer, right-click the project name ContactUs, then click Properties
Click the Debug tab and in "Start browser with URL:", type the SharePoint site you want these web parts to be deployed to
Click X to close out of Properties
In Solution Explorer, right-click WebPart1 and click Delete, then OK
In Solution Explorer, right-click project ContactUs, then click Add -> New Item -> SharePoint -> Web Part and for the name type ContactList, then click Add
In Solution Explorer, right-click project ContactUs, then click Add -> New Item -> SharePoint -> Web Part and for the name type ContactList, then click Add
In Solution Explorer, right-click project ContactUs, then click Add -> New Item -> Code -> Interface and for the name type IContact.vb, then click Add

In IContact.vb, copy and paste the following code:


Property ContactName() As String
Property JobTitle() As String
Property EmailAddress() As String
Property Phone() As String
Property Fax() As String

In Solution Explorer, right-click References, then click Add Reference; in the .NET tab, select System.Drawing and click OK
In ContactList.vb, comment out the first two lines, Option Explicit On and Option Strict On

In ContactList.vb, add the following code directly below Public Class ContactList (delete the other pre-generated code within the class):


        Inherits System.Web.UI.WebControls.WebParts.WebPart
Implements IContact

WithEvents oContactNameLink As LinkButton
Private ContactNameToEmail As String = String.Empty
Private JobTitleToEmail As String = String.Empty
Private EmailAddressToEmail As String = String.Empty
Private PhoneToEmail As String = String.Empty
Private FaxToEmail As String = String.Empty


Dim strContactListDataSource As String = ""

<WebBrowsable(True), Personalizable(True), FriendlyName("Contact List Data Source"), SPWebCategoryName("Data")> _
Property ContactListDataSource() As String
Get
    Return strContactListDataSource
End Get
Set(ByVal value As String)
    strContactListDataSource = value
End Set
End Property


Public Sub New()
End Sub


<Personalizable()> _
Public Property ContactName() As String _
Implements IContact.ContactName

Get
    Return ContactNameToEmail
End Get
Set(ByVal value As String)
    ContactNameToEmail = value
End Set
End Property


<Personalizable()> _
Public Property JobTitle() As String _
Implements IContact.JobTitle

Get
    Return JobTitleToEmail
End Get
Set(ByVal value As String)
    JobTitleToEmail = value
End Set
End Property


<Personalizable()> _
Public Property EmailAddress() As String _
Implements IContact.EmailAddress

Get
    Return EmailAddressToEmail
End Get
Set(ByVal value As String)
    EmailAddressToEmail = value
End Set
End Property


<Personalizable()> _
Public Property Phone() As String _
Implements IContact.Phone

Get
    Return PhoneToEmail
End Get
Set(ByVal value As String)
    PhoneToEmail = value
End Set
End Property


<Personalizable()> _
Public Property Fax() As String _
Implements IContact.Fax

Get
    Return FaxToEmail
End Get
Set(ByVal value As String)
    FaxToEmail = value
End Set
End Property



' This is the callback method that returns the provider.
<ConnectionProvider("Contact Provider", "ContactProvider")> _
Public Function ProvideIContact() As IContact
Return Me
End Function


Protected Overrides Sub CreateChildControls()
MyBase.CreateChildControls()


'if ContactListSource is a valid list, display controls
If ContactListIsValid() Then

    Try
        'get the site the web part is running on
        Dim oWeb As SPWeb
        oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

        'get the list we are going to work with
        Dim oList As SPList
        oList = oWeb.Lists(ContactListDataSource)


        'create table object
        Dim oTable As New Table
        'oTable.Width = 100
        oTable.CellPadding = 0
        oTable.CellSpacing = 0


        'add the table row
        Dim oRow As New TableRow
        oTable.Rows.Add(oRow)


        'add the cells
        Dim oCellHeaderName As New TableCell
        oCellHeaderName.Width = 180
        oCellHeaderName.Text = "Name"
        oRow.Cells.Add(oCellHeaderName)

        Dim oCellHeaderJobTitle As New TableCell
        oCellHeaderJobTitle.Width = 180
        oCellHeaderJobTitle.Text = "Job Title"
        oRow.Cells.Add(oCellHeaderJobTitle)

        Dim oCellHeaderEmail As New TableCell
        oCellHeaderEmail.Width = 180
        oCellHeaderEmail.Text = "Email Address"
        oRow.Cells.Add(oCellHeaderEmail)

        Dim oCellHeaderPhone As New TableCell
        oCellHeaderPhone.Width = 100
        oCellHeaderPhone.Text = "Phone"
        oRow.Cells.Add(oCellHeaderPhone)

        Dim oCellHeaderFax As New TableCell
        oCellHeaderFax.Width = 100
        oCellHeaderFax.Text = "Fax"
        oRow.Cells.Add(oCellHeaderFax)


        'for all rows in list, display them
        For Each oContactListItem As SPListItem In oList.Items
            'add the table row for the new list item
            Dim oContactRow As New TableRow
            oTable.Rows.Add(oContactRow)


            Dim strPhone As String = ""
            If Not oContactListItem.Item("Phone") Is Nothing Then
                strPhone = oContactListItem.Item("Phone").ToString
            End If

            Dim strFax As String = ""
            If Not oContactListItem.Item("Phone") Is Nothing Then
                strFax = oContactListItem.Item("Fax").ToString
            End If



            'add the cells
            Dim oCellName As New TableCell
            oContactNameLink = New LinkButton
            oContactNameLink.Text = oContactListItem.Item("Contact Name").ToString
            oContactNameLink.CommandArgument = oContactListItem.Item("Job Title").ToString & "|" & _
                                         oContactListItem.Item("Email Address").ToString & "|" & _
                                         strPhone & "|" & _
                                         strFax & "|"
            AddHandler oContactNameLink.Click, AddressOf ContactSelected
            oCellName.Controls.Add(oContactNameLink)
            oContactRow.Cells.Add(oCellName)


            Dim oCellJobTitle As New TableCell
            oCellJobTitle.Text = oContactListItem.Item("Job Title").ToString
            oContactRow.Cells.Add(oCellJobTitle)

            Dim oCellEmailAddress As New TableCell
            oCellEmailAddress.Text = oContactListItem.Item("Email Address").ToString
            oContactRow.Cells.Add(oCellEmailAddress)

            Dim oCellPhone As New TableCell
            If Not oContactListItem.Item("Phone") Is Nothing Then
                oCellPhone.Text = oContactListItem.Item("Phone").ToString
            Else
                oCellPhone.Text = ""
            End If
            oContactRow.Cells.Add(oCellPhone)

            Dim oCellFax As New TableCell
            If Not oContactListItem.Item("Fax") Is Nothing Then
                oCellFax.Text = oContactListItem.Item("Fax").ToString
            Else
                oCellFax.Text = ""
            End If

            oContactRow.Cells.Add(oCellFax)

        Next

        'add the table to the web part controls collection
        Controls.Add(oTable)

    Catch ex As Exception
        Dim lblErrorMessage As New Label
        lblErrorMessage.ForeColor = Drawing.Color.Red
        lblErrorMessage.Text = "Error: " & ex.Message & _
                  "<BR><BR>" & "Details: " & ex.ToString
        Controls.Add(lblErrorMessage)

    End Try

Else
    'else display message telling user they must configure the ContactListDataSource property
    Dim lblConfigureMessage As New Label
    lblConfigureMessage.ForeColor = Drawing.Color.Red
    lblConfigureMessage.Text = "<BR><BR>" & "You must configure the Contact List Data Source property. " & _
                               "<BR><BR>" & "Please click Modify Shared Web Part -> Data -> Contact List Data Source " & _
                                            "and set it to a list based on the ContactListTemplate list template."
    Controls.Add(lblConfigureMessage)
End If

End Sub


Private Sub ContactSelected(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles oContactNameLink.Click
   'when a contact is selected, assign their info to local variables

   Dim ContactFields As String
   Dim ContactFieldsArray(4) As String

   'assign person's name to local variable ContactNameToEmail
   ContactNameToEmail = CType(sender, LinkButton).Text

   'pull contact fields from button's CommandArgument property
   ContactFields = CType(sender, LinkButton).CommandArgument

   'split contact fields into an array
   ContactFieldsArray = ContactFields.Split("|")

   'assign contact fields to local variables
   JobTitleToEmail = ContactFieldsArray(0)
   EmailAddressToEmail = ContactFieldsArray(1)
   PhoneToEmail = ContactFieldsArray(2)
   FaxToEmail = ContactFieldsArray(3)

End Sub


Private Function ContactListIsValid() As Boolean
'PURPOSE: returns true if specified contact list is valid for the web part

Try
    'get the site the web part is running on
    Dim oWeb As SPWeb
    oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

    'get the list specified by user in property, if list is not found in site, flow will hit Catch
    Dim oList As SPList
    oList = oWeb.Lists(ContactListDataSource)


    'check if fields exist in list

    Dim blnContactNameFound As Boolean = False
    Dim blnJobTitleFound As Boolean = False
    Dim blnEmailAddressFound As Boolean = False
    Dim blnPhoneFound As Boolean = False
    Dim blnFaxFound As Boolean = False

    'loop through the fields in the list and check to see if all the required fields are in the list
    For Each oField As SPField In oList.Fields
        If Not oField.Hidden And Not oField.ReadOnlyField And oField.Type <> SPFieldType.Attachments Then

            If oField.Title = "Contact Name" Then
                blnContactNameFound = True
            End If

            If oField.Title = "Job Title" Then
                blnJobTitleFound = True
            End If

            If oField.Title = "Email Address" Then
                blnEmailAddressFound = True
            End If

            If oField.Title = "Phone" Then
                blnPhoneFound = True
            End If

            If oField.Title = "Fax" Then
                blnFaxFound = True
            End If

        End If
    Next

    'if all fields were found, return true
    If blnContactNameFound And blnJobTitleFound And blnEmailAddressFound And blnPhoneFound And blnFaxFound Then
        Return True
    Else
        Return False
    End If

Catch ex As Exception
    Return False

End Try

End Function

In EmailContact.vb, add the following code below the Imports statements at the top of the file:
```
Imports System.Net.Mail
```

In EmailContact.vb, add the following code below Public Class EmailContact (delete the other pre-generated code within the class):


        Inherits System.Web.UI.WebControls.WebParts.WebPart

Private _provider As IContact
Private _contactName As String
Private _jobTitle As String
Private _emailAddress As String
Private _phone As String
Private _fax As String

Private lblContactNameValue As Label
Private lblJobTitleValue As Label
Private lblEmailAddressValue As Label
Private lblPhoneValue As Label
Private lblFaxValue As Label

Dim oMessageSubject As TextBox
Dim oSubmitterName As TextBox
Dim oSubmitterEmail As TextBox
Dim oMessage As TextBox

Dim lblStatusMessage As New Label

WithEvents btnSave As New Button


Dim strEmailContactDestination As String = ""

<WebBrowsable(True), Personalizable(True), FriendlyName("Email Contact Destination"), SPWebCategoryName("Data")> _
Property EmailContactDestination() As String
   Get
       Return strEmailContactDestination
   End Get
   Set(ByVal value As String)
       strEmailContactDestination = value
   End Set
End Property


Dim strSMTPMailHost As String = ""

<WebBrowsable(True), Personalizable(True), FriendlyName("SMTP Mail Host"), SPWebCategoryName("Data")> _
Property SMTPMailHost() As String
   Get
       Return strSMTPMailHost
   End Get
   Set(ByVal value As String)
       strSMTPMailHost = value
   End Set
End Property


'Public Sub New()
'End Sub


' This method is identified by the ConnectionConsumer
' attribute, and is the mechanism for connecting with
' the provider.
<ConnectionConsumer("Contact Consumer", "ContactConsumer")> _
Public Sub GetIContact(ByVal Provider As IContact)
   _provider = Provider
End Sub


Protected Overrides Sub CreateChildControls()
   MyBase.CreateChildControls()

   'if EmailContactDestination is a valid list, display controls
   If EmailContactDestinationIsValid() Then
       If SMTPMailHostIsValid() Then
           'create table object
           Dim oTable As New Table
           oTable.CellPadding = 0
           oTable.CellSpacing = 0

           'create a row
           Dim oContactNameRow As New TableRow
           oTable.Rows.Add(oContactNameRow)

           'create the cells and add them to the row
           Dim oContactNameLabelCell As New TableCell
           oContactNameRow.Cells.Add(oContactNameLabelCell)
           Dim oContactNameValueCell As New TableCell
           oContactNameRow.Cells.Add(oContactNameValueCell)

           oContactNameLabelCell.Width = 125
           oContactNameValueCell.Width = 350

           'create label objects for field name and field value
           Dim lblContactNameHeader As New Label
           lblContactNameHeader.Text = "Contact Name"
           lblContactNameValue = New Label
           lblContactNameValue.Text = ""

           'add the controls to the cells
           oContactNameLabelCell.Controls.Add(lblContactNameHeader)
           oContactNameValueCell.Controls.Add(lblContactNameValue)



           'create a row
           Dim oJobTitleRow As New TableRow
           oTable.Rows.Add(oJobTitleRow)

           'create the cells and add them to the row
           Dim oJobTitleLabelCell As New TableCell
           oJobTitleRow.Cells.Add(oJobTitleLabelCell)
           Dim oJobTitleValueCell As New TableCell
           oJobTitleRow.Cells.Add(oJobTitleValueCell)

           'create label objects for field name and field value
           Dim lblJobTitleHeader As New Label
           lblJobTitleHeader.Text = "Job Title"
           lblJobTitleValue = New Label
           lblJobTitleValue.Text = ""

           'add the controls to the cells
           oJobTitleLabelCell.Controls.Add(lblJobTitleHeader)
           oJobTitleValueCell.Controls.Add(lblJobTitleValue)



           'create a row
           Dim oEmailAddressRow As New TableRow
           oTable.Rows.Add(oEmailAddressRow)

           'create the cells and add them to the row
           Dim oEmailAddressLabelCell As New TableCell
           oEmailAddressRow.Cells.Add(oEmailAddressLabelCell)
           Dim oEmailAddressValueCell As New TableCell
           oEmailAddressRow.Cells.Add(oEmailAddressValueCell)

           'create label objects for field name and field value
           Dim lblEmailAddressHeader As New Label
           lblEmailAddressHeader.Text = "Email Address"
           lblEmailAddressValue = New Label
           lblEmailAddressValue.Text = ""

           'add the controls to the cells
           oEmailAddressLabelCell.Controls.Add(lblEmailAddressHeader)
           oEmailAddressValueCell.Controls.Add(lblEmailAddressValue)



           'create a row
           Dim oPhoneRow As New TableRow
           oTable.Rows.Add(oPhoneRow)

           'create the cells and add them to the row
           Dim oPhoneLabelCell As New TableCell
           oPhoneRow.Cells.Add(oPhoneLabelCell)
           Dim oPhoneValueCell As New TableCell
           oPhoneRow.Cells.Add(oPhoneValueCell)

           'create label objects for field name and field value
           Dim lblPhoneHeader As New Label
           lblPhoneHeader.Text = "Phone"
           lblPhoneValue = New Label
           lblPhoneValue.Text = ""

           'add the controls to the cells
           oPhoneLabelCell.Controls.Add(lblPhoneHeader)
           oPhoneValueCell.Controls.Add(lblPhoneValue)



           'create a row
           Dim oFaxRow As New TableRow
           oTable.Rows.Add(oFaxRow)

           'create the cells and add them to the row
           Dim oFaxLabelCell As New TableCell
           oFaxRow.Cells.Add(oFaxLabelCell)
           Dim oFaxValueCell As New TableCell
           oFaxRow.Cells.Add(oFaxValueCell)

           'create label objects for field name and field value
           Dim lblFaxHeader As New Label
           lblFaxHeader.Text = "Fax"
           lblFaxValue = New Label
           lblFaxValue.Text = ""

           'add the controls to the cells
           oFaxLabelCell.Controls.Add(lblFaxHeader)
           oFaxValueCell.Controls.Add(lblFaxValue)



           'build form to allow user to submit comments and have them emailed to selected contact

           'create a row
           Dim oMessageSubjectRow As New TableRow
           oTable.Rows.Add(oMessageSubjectRow)

           'create the cells and add them to the row
           Dim oMessageSubjectLabelCell As New TableCell
           oMessageSubjectRow.Cells.Add(oMessageSubjectLabelCell)
           Dim oMessageSubjectValueCell As New TableCell
           oMessageSubjectRow.Cells.Add(oMessageSubjectValueCell)

           'create the field label control
           Dim lblMessageSubject As New Label
           lblMessageSubject.Text = "Message Subject"

           'create the form field control
           oMessageSubject = New TextBox
           oMessageSubject.Width = 300

           'create validator
           Dim oMessageSubjectRequired As New RequiredFieldValidator

           'add controls to the cells
           oMessageSubjectLabelCell.Controls.Add(lblMessageSubject)
           oMessageSubjectValueCell.Controls.Add(oMessageSubject)
           oMessageSubjectValueCell.Controls.Add(oMessageSubjectRequired)

           'configure validator
           oMessageSubjectRequired.ErrorMessage = " * required"
           oMessageSubject.ID = "oMessageSubject"
           oMessageSubjectRequired.Display = ValidatorDisplay.Dynamic
           oMessageSubjectRequired.ControlToValidate = oMessageSubject.ID
           oMessageSubjectRequired.ValidationGroup = "EmailContactValidationGroup"





           'create a row
           Dim oSubmitterNameRow As New TableRow
           oTable.Rows.Add(oSubmitterNameRow)

           'create the cells and add them to the row
           Dim oSubmitterNameLabelCell As New TableCell
           oSubmitterNameRow.Cells.Add(oSubmitterNameLabelCell)
           Dim oSubmitterNameValueCell As New TableCell
           oSubmitterNameRow.Cells.Add(oSubmitterNameValueCell)

           'create the field label control
           Dim lblSubmitterName As New Label
           lblSubmitterName.Text = "Submitter Name"

           'create the form field control
           oSubmitterName = New TextBox
           oSubmitterName.Width = 300

           'create validator
           Dim oSubmitterNameRequired As New RequiredFieldValidator

           'add controls to the cells
           oSubmitterNameLabelCell.Controls.Add(lblSubmitterName)
           oSubmitterNameValueCell.Controls.Add(oSubmitterName)
           oSubmitterNameValueCell.Controls.Add(oSubmitterNameRequired)

           'configure validator
           oSubmitterNameRequired.ErrorMessage = " * required"
           oSubmitterName.ID = "oSubmitterName"
           oSubmitterNameRequired.Display = ValidatorDisplay.Dynamic
           oSubmitterNameRequired.ControlToValidate = oSubmitterName.ID
           oSubmitterNameRequired.ValidationGroup = "EmailContactValidationGroup"





           'create a row
           Dim oSubmitterEmailRow As New TableRow
           oTable.Rows.Add(oSubmitterEmailRow)

           'create the cells and add them to the row
           Dim oSubmitterEmailLabelCell As New TableCell
           oSubmitterEmailRow.Cells.Add(oSubmitterEmailLabelCell)
           Dim oSubmitterEmailValueCell As New TableCell
           oSubmitterEmailRow.Cells.Add(oSubmitterEmailValueCell)

           'create the field label control
           Dim lblSubmitterEmail As New Label
           lblSubmitterEmail.Text = "Submitter Email"

           'create the form field control
           oSubmitterEmail = New TextBox
           oSubmitterEmail.Width = 300

           'create validator
           Dim oSubmitterEmailRequired As New RequiredFieldValidator
           Dim oSubmitterEmailValid As New RegularExpressionValidator

           'add controls to the cells
           oSubmitterEmailLabelCell.Controls.Add(lblSubmitterEmail)
           oSubmitterEmailValueCell.Controls.Add(oSubmitterEmail)
           oSubmitterEmailValueCell.Controls.Add(oSubmitterEmailRequired)
           oSubmitterEmailValueCell.Controls.Add(oSubmitterEmailValid)

           'configure validator
           oSubmitterEmailRequired.ErrorMessage = " * required"
           oSubmitterEmail.ID = "oSubmitterEmail"
           oSubmitterEmailRequired.Display = ValidatorDisplay.Dynamic
           oSubmitterEmailRequired.ControlToValidate = oSubmitterEmail.ID
           oSubmitterEmailRequired.ValidationGroup = "EmailContactValidationGroup"

           'configure validator
           oSubmitterEmailValid.ErrorMessage = " * Not a valid email address"
           oSubmitterEmailValid.ControlToValidate = oSubmitterEmail.ID
           oSubmitterEmailValid.Display = ValidatorDisplay.Dynamic
           oSubmitterEmailValid.ValidationExpression = "\w+\w*\@\w+\w+\w*\.(com|edu|org|gov|net|corp)"
           oSubmitterEmailValid.ValidationGroup = "EmailContactValidationGroup"




           'create a row
           Dim oMessageRow As New TableRow
           oTable.Rows.Add(oMessageRow)

           'create the cells and add them to the row
           Dim oMessageLabelCell As New TableCell
           oMessageRow.Cells.Add(oMessageLabelCell)
           Dim oMessageValueCell As New TableCell
           oMessageRow.Cells.Add(oMessageValueCell)

           'create the field label control
           Dim lblMessage As New Label
           lblMessage.Text = "Message"

           'create the form field control
           oMessage = New TextBox
           oMessage.Width = 300
           oMessage.TextMode = TextBoxMode.MultiLine
           oMessage.Rows = 4

           'create validator
           Dim oMessageRequired As New RequiredFieldValidator

           'add controls to the cells
           oMessageLabelCell.Controls.Add(lblMessage)
           oMessageValueCell.Controls.Add(oMessage)
           oMessageValueCell.Controls.Add(oMessageRequired)

           'configure validator
           oMessageRequired.ErrorMessage = " * required"
           oMessage.ID = "oMessage"
           oMessageRequired.Display = ValidatorDisplay.Dynamic
           oMessageRequired.ControlToValidate = oMessage.ID
           oMessageRequired.ValidationGroup = "EmailContactValidationGroup"




           'set the text for the save button
           btnSave.Text = "Send"
           btnSave.Enabled = False
           btnSave.ValidationGroup = "EmailContactValidationGroup"

           'create the row for the save button
           Dim oRowButton As New TableRow
           oTable.Rows.Add(oRowButton)

           'create the cell for the save button
           Dim oCellButton As New TableCell
           oCellButton.ColumnSpan = 2
           oCellButton.HorizontalAlign = Web.UI.WebControls.HorizontalAlign.Right
           oRowButton.Cells.Add(oCellButton)

           'add save button to cell
           oCellButton.Controls.Add(btnSave)



           'create the row for the status message
           Dim oRowStatus As New TableRow
           oTable.Rows.Add(oRowStatus)

           'create the cell for the status message
           Dim oCellStatus As New TableCell
           oCellStatus.ColumnSpan = 2
           oCellStatus.HorizontalAlign = Web.UI.WebControls.HorizontalAlign.Center
           oRowStatus.Cells.Add(oCellStatus)

           'add status message to cell
           lblStatusMessage.ForeColor = Drawing.Color.Green
           oCellStatus.Controls.Add(lblStatusMessage)



           'add the table to the web part controls collection
           Controls.Add(oTable)
       Else
           'else display message telling user they must configure the SMTPMailHost property
           Dim lblConfigureMessage As New Label
           lblConfigureMessage.ForeColor = Drawing.Color.Red
           lblConfigureMessage.Text = "<BR><BR>" & "You must configure the SMTP Mail Host property. " & _
                                      "<BR><BR>" & "Please click Modify Shared Web Part -> Data -> SMTP Mail Host " & _
                                                   "and set it to a valid SMTP mail host."
           Controls.Add(lblConfigureMessage)
       End If

   Else
       'else display message telling user they must configure the EmailContactDestination property
       Dim lblConfigureMessage As New Label
       lblConfigureMessage.ForeColor = Drawing.Color.Red
       lblConfigureMessage.Text = "<BR><BR>" & "You must configure the Email Contact Destination property. " & _
                                  "<BR><BR>" & "Please click Modify Shared Web Part -> Data -> Email Contact Destination " & _
                                               "and set it to a list based on the SentEmailsTemplate list template."
       Controls.Add(lblConfigureMessage)
   End If

End Sub


Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
   EnsureChildControls()

   If Not (Me._provider Is Nothing) Then
       'assign contact values to local variables
       _contactName = _provider.ContactName.Trim()
       _jobTitle = _provider.JobTitle.Trim()
       _emailAddress = _provider.EmailAddress.Trim()
       _phone = _provider.Phone.Trim()
       _fax = _provider.Fax.Trim()

       'assign contact values to labels on form
       If _contactName <> "" Then
           lblContactNameValue.Text = _contactName
       End If

       If _jobTitle <> "" Then
           lblJobTitleValue.Text = _jobTitle
       End If

       If _emailAddress <> "" Then
           lblEmailAddressValue.Text = _emailAddress
       End If

       If _phone <> "" Then
           lblPhoneValue.Text = _phone
       End If

       If _fax <> "" Then
           lblFaxValue.Text = _fax
       End If


       'enable save button if there is a value passed in otherwise disable button
       If _contactName = "" Then
           btnSave.Enabled = False

           'clear form
           ClearForm()
       Else
           btnSave.Enabled = True

           'clear status message
           lblStatusMessage.Text = ""
       End If

   End If

End Sub 'OnPreRender


Sub SaveAndEmail() Handles btnSave.Click
   'save message to the specified list library
   SaveMessage()

End Sub


Private Sub SaveMessage()
   'PURPOSE: save values from form into list library ContactUs

   Try
       'get the site the web part is running on
       Dim oWeb As SPWeb
       oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

       'get the list where we want to save the form values to
       Dim oList As SPList
       oList = oWeb.Lists(EmailContactDestination)

       'create a new list item
       Dim oNewItem As SPListItem
       oNewItem = oList.Items.Add()

       'populate the new list item with values from the form
       oNewItem.Item("Message Subject") = oMessageSubject.Text
       oNewItem.Item("Submitter Name") = oSubmitterName.Text
       oNewItem.Item("Submitter Email") = oSubmitterEmail.Text
       oNewItem.Item("Message") = oMessage.Text
       oNewItem.Item("Contact Email") = lblEmailAddressValue.Text

       'update the list with the new item
       oNewItem.Update()

       'email the message to the designated contact
       EmailMessage()

   Catch ex As Exception
       Dim lblErrorMessage As New Label
       lblErrorMessage.ForeColor = Drawing.Color.Red
       lblErrorMessage.Text = "Error: " & ex.Message & _
                 "<BR><BR>" & "Details: " & ex.ToString
       Controls.Add(lblErrorMessage)

   End Try

End Sub


Private Sub EmailMessage()
   'PURPOSE: email the contact that was selected

   Dim strFromName As String = oSubmitterName.Text
   Dim strFromEmail As String = oSubmitterEmail.Text
   Dim strSubject As String = oMessageSubject.Text
   Dim strMessage As String = oMessage.Text
   Dim strToName As String = lblContactNameValue.Text
   Dim strToEmail As String = lblEmailAddressValue.Text

   Try
       'build from email address and to email address
       Dim FromEmailAddress As New Net.Mail.MailAddress(strFromEmail, strFromName)
       Dim ToEmailAddress As New Net.Mail.MailAddress(strToEmail, strToName)

       'create email and assign its subject and body
       Dim MailMsg As New MailMessage(FromEmailAddress, ToEmailAddress)
       MailMsg.Subject = strSubject
       MailMsg.Body = strMessage

       'create smtp email object
       Dim smtpmail As New SmtpClient

       'set email's smtp server
       smtpmail.Host = SMTPMailHost

       'send email
       smtpmail.Send(MailMsg)

       'clear form
       ClearForm()

       'display success message
       lblStatusMessage.Text = "Message Sent Successfully!"

   Catch ex As Exception
       Dim lblErrorMessage As New Label
       lblErrorMessage.ForeColor = Drawing.Color.Red
       lblErrorMessage.Text = "Error: " & ex.Message & _
                 "<BR><BR>" & "Details: " & ex.ToString
       Controls.Add(lblErrorMessage)

   End Try
End Sub


Private Sub ClearForm()
   'PURPOSE: clear form of all values

   'clear selected contact person's info
   lblContactNameValue.Text = ""
   lblJobTitleValue.Text = ""
   lblEmailAddressValue.Text = ""
   lblPhoneValue.Text = ""
   lblFaxValue.Text = ""

   'clear form fields
   oMessageSubject.Text = ""
   oSubmitterName.Text = ""
   oSubmitterEmail.Text = ""
   oMessage.Text = ""

End Sub


Private Function EmailContactDestinationIsValid() As Boolean
   'PURPOSE: returns true if specified email list is valid for the web part

   Try
       'get the site the web part is running on
       Dim oWeb As SPWeb
       oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

       'get the list specified by user in property, if list is not found in site, flow will hit Catch
       Dim oList As SPList
       oList = oWeb.Lists(EmailContactDestination)


       'check if fields exist in list

       Dim blnMessageSubjectFound As Boolean = False
       Dim blnSubmitterName As Boolean = False
       Dim blnSubmitterEmail As Boolean = False
       Dim blnMessage As Boolean = False
       Dim blnContactEmail As Boolean = False

       'loop through the fields in the list and check to see if all the required fields are in the list
       For Each oField As SPField In oList.Fields
           If Not oField.Hidden And Not oField.ReadOnlyField And oField.Type <> SPFieldType.Attachments Then

               If oField.Title = "Message Subject" Then
                   blnMessageSubjectFound = True
               End If

               If oField.Title = "Submitter Name" Then
                   blnSubmitterName = True
               End If

               If oField.Title = "Submitter Email" Then
                   blnSubmitterEmail = True
               End If

               If oField.Title = "Message" Then
                   blnMessage = True
               End If

               If oField.Title = "Contact Email" Then
                   blnContactEmail = True
               End If

           End If
       Next

       'if all fields were found, return true
       If blnMessageSubjectFound And blnSubmitterName And blnSubmitterEmail And blnMessage And blnContactEmail Then
           Return True
       Else
           Return False
       End If

   Catch ex As Exception
       Return False

   End Try

End Function


Private Function SMTPMailHostIsValid() As Boolean
   'PURPOSE: returns true if SMTP Mail Host is valid

   Try
       If SMTPMailHost <> "" Then
           Return True
       Else
           Return False
       End If

   Catch ex As Exception
       Return False

   End Try

End Function

III. Finally, we deploy the web parts to the SharePoint site, add them to a page, configure them, connect them to each other, then test them!

in Visual Studio 2008, hit F5 (this should build and deploy the web parts to your site)
in your SharePoint site, select the page you want the web parts on, then click Site Actions -> Edit Page
click Add A Web Part
scroll down to the Miscellaneous section, select ContactList web part and EmailContact web part, then click Add
In the ContactList Web Part, click Edit -> Modify Shared Web Part -> Data, and in Contact List Data Source, type our custom contact list we created, Contact List and hit OK. You should see the people you entered into the list appear in the web part.
In the EmailContact Web Part, click Edit -> Modify Shared Web Part -> Data, and in Email Contact Destination, type our custom email list we created, Sent Emails and hit OK. Next, enter your SMTP Mail Host in the next textbox. If you don't have your server configured for this, just type anything as the validation function in the code just expects any value. If you put in something that isn't your host, the web part just won't be able to email. You can customize the validation code yourself to indicate what you expect the user to enter.
click the Email Contact web part and click edit -> Connections -> Get Contact Consumer From -> Contact List (you could also have set the connection up from the Contact List web part as well)
Click Exit Edit Mode
Test the connected web parts by clicking a person in the Contact List and watching them appear in the Email Contact web part! In the Email Contact web part, enter in values and hit Send. This will save the message in the Sent Emails list. If you set up the SMTP mail host properly and the selected person has a proper email address, then that person will also be emailed the message you entered.

So there you have it! Now, exactly what is happening? In the ContactList web part, we created properties that implemented the interface IContact. The ConnectionProvider function ProvideIContact is what returns the interface. Originally, all the properties are empty, so this function won't have any values. When a contact is clicked, the ContactSelected routine fires off and populates the properties, so now ProvideIContact can return something. Now, the EmailContact web part has a ConnectionConsumer routine GetIContact that gets the values from ProvideIContact. Essentially, when we created a connection between the two web parts on step 7 above, we created a bridge between them via ContactList's ProvideIContact and EmailContact's GetIContact. As a side note, there is an interface called IWebPartRow, and I believe there would be a way to use that instead of the individual properties I created in IContact, but I went with the properties in IContact because it seemed easier at the time. Well, I hope this worked well. If you followed along and it didn't work, let me know in case I forgot something. However, I am pretty sure this should work 100%!

Getting a web part's title and description (in .webpart) to update in the SharePoint site's Web Part Gallery

2009-07-01T12:53:00.010-04:00

Here's one of those fun times with SharePoint, you know, where something simple doesn't work and you have to do backflips to get it to do what you want it to do. Now, to be fair, SharePoint has come a really long way, but there's still some quirky stuff we run into from time to time.

I developed a web part in Visual Studio 2008 and was getting ready to bundle it up for deployment using WSPBuilder. I then realized that I had not changed its default title and description. This information is set in the web part's .webpart file. In my case, its in AddContactFromAD.webpart. Upon deployment, you can see this information in the Web Part Gallery (Site Actions -> Site Settings -> Web Parts (under Galleries). If you click the Edit icon next to your web part, you see the Title and Description fields containing what was set in the .webpart file. When a user goes to add a web part to a page (Site Actions -> Edit Page -> click Add a Web Part), they see this title and description.

So I thought, no biggie, I'll just update the title and description in the .webpart file and redeploy and everything should be updated like usual, right? Wrong! I went back to the Web Part Gallery and the title and description hasn't changed a bit.

So an hour or two later, and after coming across another issue while trying to solve this issue, I finally came up with the solution.

In Visual Studio, make your .webpart file's title and description the way you want them
Delete the web part from the Web Part Gallery - a. Click Site Actions -> Site Settings -> Web Parts (may need to click "Go to top level site settings" for Web Parts to show up; b. Click the Edit icon of the web part; c. Click Delete Item
Deactivate the web part - a. In Site Actions -> Site Settings -> Site Collection Features; b. click Deactivate next to web part
In Central Administration -> Operations -> Solution Management, click web part's solution .wsp file, click Retract Solution and OK, and after its Status has changed to Not Deployed, click the .wsp file again and click Remove Solution
Close out of Visual Studio. This was the other issue I referred to above: at this point, if you attempt to deploy the web part without closing out Visual Studio and reloading it, you will get the error "The language-neutral solution package was not found"
After reloading Visual Studio, redeploy the web part!

How to set a SharePoint web part's list at run time

2009-06-23T21:25:00.056-04:00

Let's say you have a web part that must have a particular custom list you created in order for the web part to function. For instance, in the web part's CreateChildControls() routine, maybe you have some code similar to this:


'get the site the web part is running on
Dim oWeb As SPWeb
oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

'get the list we are going to work with
Dim oList As SPList
oList = oWeb.Lists("Contact List")

...other code that loops through oList and displays the different field values...

So in the above example, the required custom list is called "Contact List". You may run into a few problems with this:

What if the required list doesn't exist?
What if the list exists, but it doesn't have the fields needed by the web part?
Every time you drop the web part on a page, it must have that list when it might be beneficial to have some flexibility with the list the web part is pointing to. A good example of this would be a site with a Marketing page and a Sales page. On the Marketing page, you want to display Marketing Contacts and on the Sales page you want to display Sales Contacts. Marketing Contacts and Sales Contacts are two separate lists.

My solution to this has a few steps.

First off, we need to create a custom property for your Contact List web part. Below is the code for the custom property.


Dim strContactListDataSource As String = ""

<WebBrowsable(True), Personalizable(True), FriendlyName("Contact List Data Source")> _
Property ContactListDataSource() As String
   Get
      Return strContactListDataSource
   End Get
   Set(ByVal value As String)
      strContactListDataSource = value
   End Set
End Property

So, the above code will add a new property called Contact List Data Source to the web part's properties you see when you click the web part in Edit Mode and click Modify Shared Web Part. Scroll down to the section Miscellaneous and you will see it. (Currently it is simply a textbox but it is possible to make it a dropdown list that lists available lists on the site).

Now, if we go back to the first code snippet above that gets the list, we just change it to reference our new property:


'get the site the web part is running on
Dim oWeb As SPWeb
oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

'get the list we are going to work with
Dim oList As SPList
oList = oWeb.Lists(ContactListDataSource)

...other code that loops through oList and displays the different field values...

While this makes my web part dynamic in terms of what list to look at, I still have a problem. What if the user just added the web part to a page? The property is going to be empty initially until the user sets it. So what does the user see? Or, what if the list the user specifies in the property does not exist or is an invalid list?

So, the next thing I do is create a function called ContactListIsValid() which will test to make sure the ContactListDataSource property the user specified is valid. If it is, the function will return true and the above code snippet will fire. If it is not valid, the function will return false and code will fire off that displays a message to the user telling them they need to set the ContactListDataSource property to a valid list.

First, you will see ContactListIsValid(), then below that I will show you how I use it for displaying error messages. Note that this function verifies the list exists and has the required fields.


Private Function ContactListIsValid() As Boolean
'PURPOSE: returns true if specified contact list is valid for the web part

Try
'get the site the web part is running on
Dim oWeb As SPWeb
oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

'get the list specified by user in property, if list is not found in site, flow will hit Catch
Dim oList As SPList
oList = oWeb.Lists(ContactListDataSource)


'check if fields exist in list

Dim blnContactNameFound As Boolean = False
Dim blnJobTitleFound As Boolean = False
Dim blnEmailAddressFound As Boolean = False
Dim blnPhoneFound As Boolean = False
Dim blnFaxFound As Boolean = False

'loop through the fields in the list and check to see if all the required fields are in the list
For Each oField As SPField In oList.Fields
   If Not oField.Hidden And Not oField.ReadOnlyField And oField.Type <> SPFieldType.Attachments Then

       If oField.Title = "Contact Name" Then
           blnContactNameFound = True
       End If

       If oField.Title = "Job Title" Then
           blnJobTitleFound = True
       End If

       If oField.Title = "Email Address" Then
           blnEmailAddressFound = True
       End If

       If oField.Title = "Phone" Then
           blnPhoneFound = True
       End If

       If oField.Title = "Fax" Then
           blnFaxFound = True
       End If

   End If
Next

'if all fields were found, return true
If blnContactNameFound And blnJobTitleFound And blnEmailAddressFound And blnPhoneFound And blnFaxFound Then
   Return True
Else
   Return False
End If

Catch ex As Exception
   Return False

End Try

Finally, below is the code on how I use this in CreateChildControls().


'if ContactListSource is a valid list, display controls
If ContactListIsValid() Then

   Try
      'get the site the web part is running on
      Dim oWeb As SPWeb
      oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

      'get the list we are going to work with
      Dim oList As SPList
      oList = oWeb.Lists(ContactListDataSource)

      ...other code that loops through oList and displays the different field values...

   Catch ex As Exception
      Dim lblErrorMessage As New Label
      lblErrorMessage.ForeColor = Drawing.Color.Red
      lblErrorMessage.Text = "Error: " & ex.Message & _
                "<BR><BR>" & "Details: " & ex.ToString
      Controls.Add(lblErrorMessage)

   End Try

Else
   'else display message telling user they must configure the ContactListDataSource property
   Dim lblConfigureMessage As New Label
   lblConfigureMessage.ForeColor = Drawing.Color.Red
   lblConfigureMessage.Text = "<BR> <BR>" & "You must configure the Contact List Data Source property. " & _
                          "<BR> <BR>" & "Please click Modify Shared Web Part -> Miscellaneous -> Contact List Data Source " & _
                                       "and set it to a list based on the ContactListTemplate list template."
   Controls.Add(lblConfigureMessage)
End If

A final thought. Notice the error message tells the user to set the property to a list based on the ContactListTemplate list template. I created a list template from the Contact List custom list, so that way the user can create their contact list from the list template to make sure they have all the necessary fields. To do this, I went to the List Settings of Contact List and selected Save As List Template.

Well, that's it! I wouldn't be surprised if people have their own way of doing all this, but I like to go for the simplest, most direct approach. I hope this helps!

How to create connected web parts: Part 1

2009-06-17T18:42:00.033-04:00

While this may be lengthy, my hope is that this is made as easy as possible. I begin this with a high level overview of connected web parts (Part 1), followed by a step-by-step tutorial on creating connected web parts where all you need to do is click along and paste code (Part 2).

Let's say you have two web parts: one that takes a zip code and displays the weather for that zip code, and another web part that takes a zip code and displays movies playing in movie theaters in or near that zip code. They both require a zip code textbox with appropriate validation. Plus, what if you need to develop another web part that also requires a zip code and then displays other information based on that zip code?

Eliminate redundancy and welcome connected web parts! Instead of the above, we could make a zip code web part which acts as a provider, providing a zip code to another web part. Then our weather web part and movie web part could act as consumers, consuming a zip code fed to them by the zip code provider web part.

Essentially, this involves creating a zip code interface that all three web parts will understand. Then we make each web part, specifying in the code that the zip code web part is a provider web part while specifying the weather and movies web parts are consumer web parts.

Once the web parts and interface are built and deployed to a SharePoint site, a user can add the zip code web part to a page, add the weather web part to a page, then finally connect the two web parts via the Modify Shared Web Part option for either web part.

In Part 2 of this post is a tutorial on how to create Contact List/Email Contact connected web parts, along with entire code to be copy and pasted. I recommend following the tutorial to get the web parts functional, then look at the comments in the code to understand what everything is doing. Also, I will include a summary explaining the details of whats happening. Good luck!

RequiredFieldValidator in connected web parts

2009-06-16T13:57:00.009-04:00

I plan on posting a tutorial on how to easily create connected web parts, but I wanted to write a short post on a unique issue I just came across, along with a simple solution.

Normally, when you add a RequiredFieldValidator to a form, it triggers when there is an attempted postback for that form. However, I have a scenario where I have two web parts, one called Contact List (this is the provider web part; it simply pulls data from a custom list library called Contact List and displays it) and another web part called Email Contact (this is the consumer webpart; it has a form where a user can enter their name, email, and message they want to email a contact). The Contact List web part provides a person while the Email Contact web part consumes a person. So when a user clicks a person in the Contact List, a postback is performed and the Email Contact web part will display that person's information above the form. A user could then enter their message, then click the Send button and it would email to the selected contact person.

Ok, so did you notice the problem yet? If the Email Contact web part has required field validators on its form fields (ie required on the submitter's name, email, and message), then when a user clicks a person in the Contact List web part, the requiredfieldvalidators in the Email Contact web part will prevent the postback from occurring, thus the person is never sent from the Contact List web part to the Email Contact web part. (Note: this scenario assumed that Contact List and Email Contact are on the same web page in the same WebPartZone).

The solution ended up being pretty simple. I am not going into the details of my specific implementation because the concept here is what it important (plus, I will post the code for this web part anyway in my article on connected web parts that I will do very soon). The solution is to use the ValidationGroup property of the RequiredFieldValidators and the Send button that saves/sends the message. To get this to work, I did the following:

In the Email Contact web part (all this is done in CreateChildControls):
1. create the RequiredFieldValidator controls for each field that needs it
2. add the RequiredFieldValidator controls to the web part's Controls collection
3. set their properties like ErrorMessage and ControlToValidate as you normally would
4. set their ValidationGroup property to "EmailContactValidationGroup"
5. when you create the form's button that saves/sends the email, set the button's ValidationGroup property also to "EmailContactValidationGroup"

The key here is to make sure the ValidationGroup is the same for the button and validators. This way, the validators will only fire off when the button is pressed!

How to populate a custom Contact List from AD

2009-06-13T20:11:00.024-04:00

In a recent project at work, I was required to create a custom Contact List. The only problem was that I didn't want my SharePoint admins to have to go to the list, then click New -> Item and have to sit there and enter in the person's name, email address, title, etc, when all this information is already sitting over in AD (Active Directory) to begin with.

So, I wanted to provide my SharePoint site admins with the ability to search AD, select a person (or people), then with the click of a button, add them into my Contact List, which is a custom list library. My solution ended up being quite straightforward - create a web part with two controls, 1. a PeopleEditor control (the standard SharePoint control for selecting people from AD; it has those two little buttons in the lower right for checking the name you enter and a browse button to let you do searches) and 2. a Button control which will take whatever people have been entered into the PeopleEditor and save them into the Contact List.

First off, this assumes you have created a custom list called "Contact List" on your SharePoint site. The fields are all text fields, called "Name", "Job Title", and "Email Address".

1. Load Visual Studio 2008
2. Click File -> New -> Project... -> Visual Basic -> SharePoint -> Web Part
3. For the name, I called mine AddContactFromAD
4. Notice the web part was named WebPart1. Do a search and replace across the whole project and change WebPart1 to AddContactFromAD wherever it is found. While that just changed the contents of the files in the project, you will notice there is still a folder called WebPart1 with files inside all named WebPart1 with different file extensions. Manually rename the folder and the base names of those files (leaving the extensions alone for each).
5. Copy and paste the code below.
6. In the Solution Explorer, right click the project and click Properties, click the Debug tab on the left, then in "Start browser with URL:" type in the name of the SharePoint site you want to deploy the web part to.
7. Hit F5 to build and deploy the web part.

Code for AddContactFromAD.vb:

1. under your inherits statement and above your constructor, copy and paste:

WithEvents btnAddUsers As New Button
Dim peADLookUp As New PeopleEditor

2. in CreateChildControls(), copy and paste:

'create and add message to web part
Dim lblMessage As New Label
lblMessage.Text = "Add contact(s) from Active Directory into Contact List"
Controls.Add(lblMessage)

'add PeopleEditor control to web part (it was created above)
peADLookUp.Rows = 1
Controls.Add(peADLookUp)

'add button to web part (it was created above)
btnAddUsers.Text = "Add user(s) to Contact List"
Controls.Add(btnAddUsers)

3. below CreateChildControls(), copy and paste the following subroutine.


Sub btnAddUsers_Click() Handles btnAddUsers.Click
'PURPOSE: add selected users to Contact List

'get the site the web part is running on
Dim oWeb As SPWeb
oWeb = Microsoft.SharePoint.WebControls.SPControl.GetContextWeb(Context)

'get the list where we want to save the person to
Dim oList As SPList
oList = oWeb.Lists("Contact List")


Dim strDisplayName As String = ""
Dim strEmail As String = ""
Dim strTitle As String = ""

'loop through each entity in peADLookUp (note DisplayName,
'   Email, and Title are all properties in AD)
For Each account As PickerEntity In peADLookUp.ResolvedEntities
   'get values of  current entity
   strDisplayName = account.EntityData("DisplayName").ToString()
   strEmail = account.EntityData("Email").ToString()
   strTitle = account.EntityData("Title").ToString()

   'create a new list item in Contact List
   Dim oNewItem As SPListItem
   oNewItem = oList.Items.Add()

   'populate the new list item with values from the form
   oNewItem.Item("Name") = strDisplayName
   oNewItem.Item("Job Title") = strTitle
   oNewItem.Item("Email Address") = strEmail

   'update the list with the new item
   oNewItem.Update()
Next

End Sub

Welcome to Simple SharePoint Solutions!

2009-06-13T20:00:00.000-04:00

Welcome to Simple SharePoint Solutions! The point of this site is the sharing of simple, easy to understand SharePoint solutions. Despite the fact that SharePoint has all kinds of wonderful built in functionality, we just about always have unique requirements that are not out of the box. In steps us SharePoint developers, but sadly, there are a lot of posts out there that are not as straightforward as most of us would like. So this site is dedicated to all of us who just want a simple, easy to understand solution to our SharePoint problems! I am actively working on several SharePoint projects and will be posting many more how-to's very soon, so please check in and give some feedback on how helpful these articles are.

D-J