Tuesday, November 18, 2008

Microsoft Application Architecture Guide 2.0

The Microsoft patterns & practices group has just released a beta version of Application Architecture Guide 2.0 (available for download). Lonnie Wall of RDA was a contributor for this book. I knew a little bit about this as Lonnie met with Colin Murphy and me to discuss workflow. We could not resist talking about K2 but third party platforms are not part of this architecture assessment.

I have just started to read over this and now I am enticed to make time to read the whole thing. Much of the content of this will help architects and decision makers during an Elaboration phase of a project to navigate the Microsoft stack. They have guidance on how to start architecting a solution, design patterns, best practices for layers, etc. They even get down into pro and cons of using things such as ADO.net vs. Entity, when to utilize LINQ, when to use WF and BizTalk, web application design considerations, SharePoint application, etc.

It seems pretty comprehensive so far and should be used as a starting place. There are still limitations on topics discussed in this book (for instance the limitations of Excel and InfoPath services for SharePoint are not really dived into too deeply). There are probably some other similar sorts of things in the book, but from what I know the purpose of this book was to again give a starting place.

New K2 blackpearl Best Practices Whitepaper

I know there are many out who have started doing K2 blackpearl projects and have been looking for more guidance and training. The K2 blackpearl 101 course is a good introduction, mostly for sales, but not great for a heads down developer. The K2 blackpearl Wrox book will be done really soon – I am counting down. You can find it on Amazon right now and pre-order if you wish. I have asked for some deeper dive technical training materials for developers and see where this goes.

However K2 pulled together a new K2 blackpearl Best Practices whitepaper (KB000352). It has tons of good stuff on everything from best practices on designing SmartObjects, gathering requirements, project set up in Visual Studio, logging, data field usage, rules, versioning, process sizing, exception handling, deployment, etc.

I highly recommend you give this a read.

Tuesday, November 4, 2008

WF MOSS Human Workflow Part 2 - Project


This is the second part in a series discussing how to build human workflow with Visual Studio in MOSS. In the first article, I gave some background into considerations and assumptions that for creating a workflow in Visual Studio versus SharePoint Designer. As well, I took a deeper look into how forms work with MOSS workflows and I presented a simple approval process that will be created. This workflow will incorporate all of the basic necessities required for implementing a business workflow with WF and MOSS. One of the goals of this implementation is to make sure the implementation is easy for the business users to use, without requiring them to knowing they are using "SharePoint workflow".

In this posting I will take a deeper dive into how to prepare for the construction of a human workflow process using WF and MOSS. Specifically we will focus on the steps of how to build a project in Visual Studio..

Creating the WF Projects

In this example, I will be using Visual Studio 2008 however all of this can be done using Visual Studio 2005. Some of the steps for 2005 are different when creating the WF project and will need to install the SharePoint Extension for Visual Studio 2005.

Before opening up Visual Studio and starting adding projects, a plan of attack should be made. Nothing is more frustrating than inheriting a project from someone who did not think anything through. We want to ensure that the projects are layered, decoupled, maintainable, and scalable. There is no reason why we should create a solution just like we would anywhere. Remember all WF is a way to create even handlers that will raised in a specified order based on business rules. It is just a schedule of events. These events may call out to SharePoint, enterprise databases or access other resources across platforms.

Knowing the following will be my initiation project:

  • WFDistillery.MyProcess: Solution file that contains code artifacts for the business process.
    • WFDistillery.MyProcess.Business: Class Library project which will contain all business and domain classes used by the workflow. It is planned that Entity, part of the .NET 3.5 Framework, will be utilized.
    • WFDistillery.MyProcess.Data: Class Library project which will do any data persistence for the workflow. There may be places where LINQ is possibly used within this layer. Note at that if Entity is used in the Business library there may not be need for this library. However, it should be part of the solution because there will be other enterprise data sources that you will have to interact with down the road which Entity may not be able to work with. WFDistillery.MyProcess.Form.Request: An InfoPath Form Template project which will contain the InfoPath request form that the user will fill out. Find this under Visual C# >> Office >> 2007 >> InfoPath 2007 Form Template.
    • WFDistillery.MyProcess.Utility: Class Library project with any sort of utilities that are needed for this project.
    • WFDistillery.MyProcess.WebService: Web Service project that will be used by InfoPath forms.
    • WFDistillery.MyProcess.WF: SharePoint 2007 State Machine Workflow project. Find this under Visual C# >> Office >> 2007 >> SharePoint2007 State Machine Workflow.
    • WFDistillery.MyProcess.WF.Form.Association: An InfoPath Form Template project for the workflow association form.
    • WFDistillery.MyProcess.WF.Form.Initiation: An InfoPath Form Template project for the workflow initiation form.
    • WFDistillery.MyProcess.WF.Form.Task0: An InfoPath Form Template project for the workflow task form.

Here are some assumptions and considerations made when creating this project:

  • You will also probably want to change WFDistillery to something like Company.Department.ProcessName. MyProcess is the name of the process. You will probably want to rename this to TravelRequest, PurchaseRequest, SoftwareRequest, etc.
  • WFDistillery.MyProcess.Form.Request project was done this way so if more forms are ever added to the process, you would do something like WFDistillery.MyProcess.Form.Receiving. These forms are not the workflow forms and should thought of as simply as a piece of content. Knowing that, you can use this solution pattern for other things in SharePoint like a list item, calendar item, etc.
  • The InfoPath forms will be using web services to do all of their transactions. I really believe in trying to minimize putting any managed code into InfoPath (even if it requires more clicking). I try to treat them as simple, thin, XML based user interfaces. I have said in my blogs, if you are putting lots of .Net managed code in there; consider using ASP.net and not InfoPath. All the web service will be doing is exposing methods within WFDistillery.MyProcess.Business and WFDistillery.MyProcess.Data.
  • WFDistillery.MyProcess.WF.Form.* projects are InfoPath forms that are used by the workflow. Both the Association and Initiation forms are self-explanatory. The Task0 is the first task form for the workflow. The naming convention corresponds to the <Task0> tag in the Workflow feature files. If you project has more than one task form, you would simply add another project called Task1, Task2, etc. I will go into this deeper in a future however I have found that a best practice is to create on Task form and simply switch the views.
  • Side note, I was pretty excited to be have InfoPath Form Template project templates in Visual Studio 2008. In the past, I have put InfoPath .xsn files in VSS or had to crack them open and get all of the internal files in VSS. Now, I can do all my designing of InfoPath in Visual Studio and get all of the files in VSS for free. The only downside is I can really only do one form per project.
  • Because WFDistillery.MyProcess.Form.Request project is part of this solution, there is an assumption that request form is coupled to this solution. It would be possible to try to write something really generic where we would move all of the projects prefixed with WFDistillery.MyProcess.WF.* into a separate solution; but time is limited J.
  • It is possible to have more than one workflow defined in a WF library. The solution I am building makes the assumption that there will only be one workflow defined in this solution. If I wanted to create multiple business processes in this same solution, I would have done something like the following.
    • WFDistillery.MyProcesses
      • WFDistillery.MyProcesses.Data
      • WFDistillery.MyProcesses.Utility
      • WFDistillery.MyProcesses.Process1.Business
      • WFDistillery.MyProcesses.Process1.Form.Request
      • WFDistillery.MyProcesses.Process1.WebService
      • WFDistillery.MyProcesses.Process1.WF
      • WFDistillery.MyProcesses.Process1.WF.Form.Association
      • WFDistillery.MyProcesses.Process1.WF.Form.Initiation
      • WFDistillery.MyProcesses.Process1.WF.Form.Task0

The resulting Solution Explorer in Visual Studio will look like the following.

Creating the SharePoint 2007 State Machine Workflow Project
When creating a new workflow with Visual Studio 2008, there is a great new feature that allows you to configure your project so that you can debug your workflow from Visual Studio. In Visual Studio 2005 this was not an option. To change the debug configurations, right click the project in the Solution Explorer and select the SharePoint Debug Settings option. What this will effectively do is deploy the workflow as a feature and associate it to a list. Do not use this as a way to deploy your solution into a production environment.

When the project is created you will several files added to the project immediately. A feature.xml, workflow.xml and workflow class Workflow1.cs should be there. We will re-organize these files later on.

Coming Up
I will be taking a deep dive into how to create all of the forms that will be used for this workflow. I will be off for two weeks (11/4/08) here and will come back to this when I return.

Saturday, November 1, 2008

WF MOSS Human Workflow Part 1 - Introduction


There are many situations where you may need to build complex human workflows within MOSS and you do not have an enterprise workflow server like to do it with. This is the first in a series of articles that will show you how to build complete human workflow solutions using Visual Studio WF and InfoPath. This series will not just focus on the nuts and bolts on how to do something; it will also give you insight to design decisions and how workflows function within MOSS.

The following topics will be discussed in this series:

  • What functionality is necessary for human workflow?
  • Introduction into MOSS Workflow.
  • Construction of a request form in InfoPath.
  • How to create a state workflow process.
  • Working with business data.
  • Archiving the request.
  • Task management, task security, delegation, and creating a task queue.
  • Reminders and escalations.
  • Automated deployment across environments.
  • How to create business process performance reporting.
  • How to create a dashboard.

Just note that products like K2 blackpearl and blackpoint make doing much of what I am about to describe as trivial. I have literally seen that this took a few weeks to pull together, get the design pattern hardened and ready for production. The same workflow when using K2 would literally take me a day. After for the first two workflows, the cost justification for K2 will be made.

Getting Started with Requirements

When getting started to build a business process there are several things you need to ask so that you have all the right information when building your human workflow. I think many of us know how to gather requirements these days, but it is worth discussing it. I had written an article on how to gather K2 requirements and after reviewing it, all of the information really holds true. Here are the questions again that I would always try to ask when going into a meeting with business users:

  • Can a business flow diagram be constructed?
    • What are the steps in the business process?
    • What are the decisions a user can make for each step of the process?
    • What role must the user have to make that decision?
    • What stakeholders are there for each decision?
    • What must occur when a decision is made?
    • What should occur when a step is not completed?
    • What are the success criteria for a process to complete? How should a process complete if success criteria cannot be met?
    • What data must be available for a user to make a decision?
    • Are there rules that affect the routing of the business process?
  • What views/dashboards are required to assess that status of the business process?
  • What reporting is required for business processes (in flight, completed, user performance, etc.)?
  • What is the user experience desired? Where do users go to complete tasks? How should users be notified when a task has been assigned?

What I will show throughout this series is how these questions will drive the actual implementation.

Workflow Design

After going through a requirements gathering process, you should be able to draw a diagram such as the following. Although this process may seem pretty simple, there is some work that needs to be done. As well, this diagram does not capture all of the usability requirements that are needed to support such a process. What this diagram does show us is the human/system steps of the workflow, the actors both system and human, actions/decisions that can be made and success criteria.

This workflow is a basic approval process where a requestor makes request, a manager must approve, then the request is sent to a queue where it is opened and finished. Along the way, the request may be sent back to the requestor for revisions. That is pretty simple.

Now the next question is how should I do this? There will be lots of things that will be done but the first step will be to create a workflow. Looking at the requirements, it becomes evident that doing a workflow in SharePoint Designer is not going to work. The problem is that the workflow is sequential and SharePoint Designer does not really work well with calling systems that reside outside of MOSS. It possible to create custom activities in SharePoint Designer to do such things as call out to a database, however this is difficult to accomplish. Plus getting to the data in InfoPath form is not clean either and processes created in SharePoint Designer cannot be deployed across MOSS environments. At this point, that option is out. The only other option would be to create a workflow in Visual Studio. Given the type of workflow this is, making this a state workflow process would be best rather than doing a sequential. The main reason is that the sequential really cannot handle the flow of this process because the process literally goes from one "state" to another "state".

As for the user interface, we are going to go ahead and use InfoPath. Really, InfoPath is not that bad if you are trying to shave some time off the delivery. There are tons of reasons why you may not want to use InfoPath and you can review those considerations by reading this. In this case, the data is really flat and I really do not have any "special" user interface rules. All we need to do is capture data and use it to make decisions. Data validation rules will be extremely simple. Plus I strive to make sure that I put as little business layer logic into my user interfaces as possible. Knowing that, there is no real good reason why I should not be able to use InfoPath.

Understanding Workflows Form and Workflow Life-Cycle

I have seen several examples out there where people spend the time wiring up a sequential workflow but do not take the time to explain the forms that you have and how you should use them. When building a MOSS workflow there are three basic forms: Association, Initiation and Task forms. There is also a modification form but that is outside the scope of this.

The association form will be displayed when the workflow is first added to a list or library. This form will only ever be displayed once and will not be seen again as workflow instances are later created for content items. The association form will be displayed after you have gone through the "Add a Workflow" page.

The initiation form will be shown when a form is started. However, this form may not be seen by a user depending on how the workflow is configured for the SharePoint list. When adding a process to a SharePoint list you have the ability to say how the workflow will be initiated. Keeping this simple, the workflow can be manually started, started when an item is created or when it is changed. The initiation form will not be displayed when a file is uploaded or submitted to a SharePoint list. It will be shown when a user manually starts a workflow.

The task form, for all intensive purposes, overrides the out of the box view of a task item in a Task List. The underpinning of everything for workflow in MOSS is a task. Whether it is a state or sequential workflow, the workflow is waiting for an event to make the workflow go to the next step in the process and nine times out of ten that is a user completing a task. The need for overriding the task form is required because based on the state of the workflow you will want to display specific information to a user. A task item is not scalable.

Now the association, initiation and task forms are NOT the request form in my opinion. This is a big point which many people do not make when talking about how to make a workflow in MOSS. Many try to embed the request form as part of the association, initiation and task forms where they are constantly trying to get the initial data from the initiation form and then loading it back into the task form. I think that is wrong approach for several reasons:

  • Association, Initiation, and Task InfoPath forms only have a short life-span. They are not a form that resides in a Form Library. Once the form has been displayed and the user submits, the form is basically gone. I like this approach well because it works with content that may not be an InfoPath request form. Calendar items, list items, pdf, etc. can be used with the workflow.
  • Both the Association and Initiation InfoPath forms can be viewed by the user once. If these forms have complex data structures (repeating information) you have the ability to access it. However, that is not the case with an InfoPath Task form. You have the ability to access data in the Task form before and after the user takes action however, you cannot work with repeating data structures. The only way accomplish this is to have the InfoPath form save the data externally to a database and then in the workflow process you will have to add more code to get that data. Just this alone, turned me off completely to trying to use the Task Form as request form as so many try to do.

The following is a diagram that should hopefully clearly explain how the forms are used in a workflow.

As you can see in the diagram, the Association form is shown only once when the form is added to a list. The Initiation Form may be shown when a workflow instance is created and the Task form will be shown for every task that is created for the workflow. The diagram shows that the Request form is not one of the workflow forms and the request form should be treated as a piece of content that is within MOSS.

Coming Up

The next thing I plan to write about is how to create a State Workflow project and start diving into how to create the InfoPath forms that will be used in the workflow.