Step by Step Tutorial. Creating Workflows for Windows Sharepoint Services and MOSS2007 (part 15/20). Easy ASPX Initiation Forms-(by using my small generic framework)

By Serge Luca

MVP

1. Download the startup project
2. Download the startup files
3. Download the framework code (optional)
4. Download the final code(optional)

Introduction

After the previous post, I’ve upgraded my generic framework to support Association and Initiation Forms. In this post I will illustrate how to create initiation forms.

The assembly and the main namespace have been renamed “SergeLuca.WorkflowTools.AspxForms”.

The framework now provides 2 main classes your association or initiation page must be derived from:

• public abstract class GenericWFAssocPage<TA> : Microsoft.SharePoint.WebControls.LayoutsPageBase

(TA is the Association Data class )

• public abstract class GenericWFInitPage<TI, TA> : Microsoft.SharePoint.WebControls.LayoutsPageBase

(TI is the Initiation Data class)

These classes make use internally of the classes :

 

• WorfklowAssociationContext<TA>
• WorkflowInitiationContext<TI, TA>

 

1.Use the existing project in the startup folder

This startup project is  more or less the project you build in step 14.

The main differences are :

• My generic aspx form framework has been compiled in an assembly called SergeLuca.WorkflwTools.AspxForms which has been referenced to the project. The framework code can be downloaded here and it is an upgraded version of the one described in step 14.
• The FromAssocDataToPage function defined in WFAssoc.aspx provides the association data directly (the context has been hidden in the library).

[Fig 1.Generic framework assembly referenced in the project]

An initiation form, WFInit.aspx, has been provided in the LAYOUTS\DemoAspxFormWorkflow folder :

[Fig 2. WFInit.aspx Initiation form provided with the project]

• Open this file, analyze the code : this page is very similar to the association page created in the previous post except that we don’t have the radSerial and radParallel checkboxes.
• Observe the @Page directive : the code behind will be implemented in a class named WFInit that we are going to create.

2. Add and implement the Initiation form Page : the GenericWFInitPage

• Add a new class to the project, call it WFInit and derive this class from a class provided by my framework: GenericWFInitPage; this class takes 2 generic parameters : the class storing the Initiation Form Data which will must implement and the class storing the association form data (AssocFormData provided in the previous post).
• Add the file InitFormData.cs from the startup files folder and examine its content.
• Specify the generic parameters in the GenericWFInitPage definition like this:

public class WFInit : GenericWFInitPage<InitFormData,AssocFormData>

 

• In WFInit, define members for the aspx controls (grab the code from snippet1.txt)
• GenericWFInitPage is an abstract class defined in my framework: you must implement 2 abstract methods:

1. FromPageToInitData()  (grab the code from snippet2.txt)
2. FromAssocToInitPage(AssocFormData assocFormData) (grab the code from snippet3.txt)

• Submit the Initiation data to the workflow by providing an event handler to the OK button

       public void BtnOK_Click(object sender, EventArgs e)
        {

            this.SubmitInitiation();

        }

• Modify the provided install.bat file to make sure your feature is activated at your site collection url.
• Rebuild your project and test the workflow.

3.Using the Initiation or Association form data from the workflow

• In the workflow double click the OnWorkflowActivated1 activity to generate an event handler.
• In this event handler add the code provided in snippet4.txt.
• Rebuid and test your workflow

This hands-on training is the property of Redwood S.L sprl and may not be organized in class or in group without the prior written permission of Serge Luca. Should you wish to organize this hands-on training in your company or institution, please contact Serge Luca first to enter into a licence agreement. Each trainer or teacher using this hands-on training should have a licence agreement. Please ask your trainer or Serge Luca whether he or she has entered into a licence agreement with Redwood S.L sprl.

The hyperlink to this hands-on training may be placed on your website for free, on the condition that the name Serge Luca is clearly mentioned in the reference. Please send us a mail containing the link to the web page our reference is used on.

Step by Step Tutorial. Creating Workflows for Windows Sharepoint Services and MOSS2007 (part 14/20). Easy ASPX Association Forms-(by using my small generic framework)

By Serge Luca

MVP

Download the startup code

Download the final code

Download the framework code

Introduction

There are many reasons to associate workflows with aspx forms in Sharepoint instead of Infopath forms (IP):

• aspx forms are more robust
• more flexible than IP forms
• can be debugged
• support very well javascript/Ajax/Silverlight
• work with Windows Sharepoint Service which is free.

The black sides of aspx forms in Sharepoint workflows are :

• they are not integrated in Office 2007 rich client
• they are more complex to develop than IP forms
• the main sample in the Sharepoint sdk doesn’t work (see my previous post where I show  how to fix it).

The first kind of form you need to create is the association form; I’ve encapsulated and abstracted the complexity of association forms in a small framework; this framework will be upgraded in the future to handle other kind of forms and will be available in CodePlex.

There will be 3 parts in this post :

• In parts 1 and 2, I will show you how to quickly create an association form by using my framework.
• In part 3, I will detail how association forms work under the cover.

Part 1. Creating a basic association form

Creating the workflow

• Let’s create a very basic Sharepoint workflow by using the Sharepoint sequential workflow template and name the project DemoAssocFormWorkflow (Fig 1).

[Fig 1. Basic workflow project]

• Untick the “Automatically Associate…” option in the third form form” (Fig 2).

[Fig 2. Don’t automatically associate the workflow]

• Add a reference to the SergeLuca.WorkflowTools.WorkflowAssociation.dll (Fig 3) (this dll can be grabbed from the startup files).

[Fig 3.Add a reference to my small framework]

• Set the Copy Local property of this assembly to true.
• Create the classic TEMPLATE-LAYOUTS folder with you custom sub folder: DemoAssocFormWorkflow

[Fig 4.Create the “12 like” folders for the Layout page (association form)]

Add a FEATURES folder with a DemoAssocFormWorkflow custom folder under the TEMPLATE folder and move the feature.xml and workflow.xml over there :

[Fig 5.Add the Features folder and the features files]

• Add the file WFAssoc.aspx into this folder; you can get it from my startup code; this page is very primitive WorkflowAssociation page; I’ve kept it simple on purpose. This page just displays an Ok button.
• Add the WFAssoc.cs page(from the startup code) to your project root; this file is the association page code behind (fig 6).

[ Fig 6.Generic Page class]

• GenericWFAssocPage is an abstract class; implements its methods :

[Fig 7.Implementing the Abstract class]

• Remove the generated throw new NotImplementedException() statements and return null in the FromAssocDataToPage member :

[Fig 8.Basic generic page implementation]

[Update 11/24 : in the next release the Function FromAssocDataToPage will only have an AssocFormData parameter]

• Compile the project and use Reflector to retrieve the assembly strong name.Modify the assembly directive of WFAssoc.aspx (Fig 9).

Fig 9.Modify the @Assembly directive to point to your code behind assembly

• You still need to specify somewhere that you want WFAssoc.aspx to become your association form: do it in workflow.xml :

[Fig 10. Defining the association forms in the feature manifest]

That’s it! Now it’s just a matter of installing the workflow, the page layout and the Framework assembly.

Installing the workflow

Add the install.bat file into the project root; double check the file to make sure everything is ok (in the Install.bat file we assume the application pool name is SharepointPool), change the url (which here is http://blog.redwood.com) ; add a Post-Build event to the project :

[Fig 10.Install.bat file in the Post-build event]

• Rebuild the project and check the output windows for any error (if you don’t find this window, you can display it from the View menu).

The final code can be found here.

Association forms testing

Normally the install.bat file activates the feature for the whole site collection.

We are going to test the 3 kinds of workflow associations

Association type 1 :  workflow associated with a list

• Go to a list or document library and add the association.

Since an association form has been provided, the next button will show up :

[Fig 11. Standard workflow association form]

• Click on the Next button and our form will show up :

[Fig 12. Custom workflow association form]

• Click ok and the the association will be created.
• You can modify the association by asking to select new Task and History list (Fig 13):

[Fig 13.Modification of a workflow association]

• Modify the association and View the site content : you will see your new Task and History lists  (Fig 13):

[Fig 14.New Task and History lists ]

Association type 2 :  workflow associated with a content type

• Create 2 item content types : Vehicule  and Car which inherits from Vehicule
• Associate these content types to a  generic list named Parking.
• Associate the DemoAssocFormWorkflow with the Vehicule content type (in the Site Content Type gallery)

[Fig 15.Associate a workflow with a content type]

• Add a new Vehicule in the parking list
• Start the workflow in the list item ECB (menu linked to the list item).
• If you add a new Car (not just a Vehicule), the workflow association will aslo show up.

Association type 3 :  Workflow associated with a content type in a specific list

• In the parking list, create a new association with the Vehicule content type (Fig 16).

[Fig 16.Workflow associated with a content type in a specific list]

This  association will be available on every Vehicule in this list, but not on the cars !

Part 2. Extending the association form

We want to be able to create the following association form (Fig 17) :

[Fig 17.The final association form]

• Add the following control declaration in WFAssoc.aspx (get the code from snippet1.txt in the startup files).

<%@ Register TagPrefix="wssuc" TagName="InputFormSection" src="/_controltemplates/InputFormSection.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormControl" src="/_controltemplates/InputFormControl.ascx" %>
<%@ Register Tagprefix="wssawc" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

• In WFAssoc.aspx, replace the existing code in “Placeholdermain” just above the hidden fields with code provided in snippet2.txt in the starter files (keep the hidden fields, remove everything else).
• Rebuild you workflow and test the association form to make sure it can show up.
• In WFAssoc.cs define the form fields as protected members (snippet3.txt).
• Define the fields namespace (Resolve) :

using System.Web.UI.WebControls;
using Microsoft.SharePoint.WebControls;

• We need to add a class that will allow data transfer between the association form and the workflow; Add the file AssocFormData  to your project from the starter files, and examine the code.
• since AssocData is the data transfer class, replace the <object> generic with <AssocData>:

[Fig 18. specifying the AssocFormData class in the generic]

• by implementing FromAssocDataToPage(), you will transfer your association data from the workflow association to the association form. (snippet4.txt).
• by implementing FromPageToAssocData(), you will transfer your association data from the association form to the workflow association.(snippet5.txt).
• Now you can rebuild the project, your workflow will be deployed and you can test it on a list, on a content type and on a content type on a list.

Part 3.Inside Association Forms

• The concept is pretty simple: when you add a workflow association, the Sharepoint framework provides a first generic page: AddWrkfl.aspx (Fig 19).

[Fig 19.Generic workflow association page (AddWrkfl.aspx)]

• The query string parameters will depend on the association type.

Association on a Content type:

query string :  ctype=<cont typeid>

[Fig 20.Query string generated by the association to a Content type]

Association on a List:

query string: List=<list id>

[Fig 21.Query string generated by the association to a list]

Association on a Content type in a List :

query string: ctype=<content typeid>&List=<list id>

• The association form must be a layout page (derived directly or indirectly from Microsoft.SharePoint.WebControls.LayoutsPageBase).
• This query string and others variables described below will be sent to your Association Form and  your custom association page must  handle them (my small WorkflowAssociationContext class will do that for you).
• The picture below illustrates most variables (in red) you association form will have to manage (for a content type).

[Fig 22.variables generated in the context of the association of a workflow with a content type]

[Fig 23. variables generated in the context of the association of a workflow with a list or with a content type in a specific list]

• If you click on the Next button, the association form specified in your feature manifest file (here workflow.xml, (fig 8) will show up .
• When you click on the Ok button, you will have to create the association by using one of the following methods of the SPWorkflowAssociation class :

public static SPWorkflowAssociation CreateListAssociation

(
    SPWorkflowTemplate baseTemplate,
    string name,
    SPList taskList,
    SPList historyList
)

public static SPWorkflowAssociation CreateSiteContentTypeAssociation

(
    SPWorkflowTemplate baseTemplate,
    string name,
    string strTaskList,
    string strHistoryList
)

public static SPWorkflowAssociation CreateListContentTypeAssociation

(
    SPWorkflowTemplate baseTemplate,
    string name,
    SPList taskList,
    SPList historyList

)

The SPWorkflowTemplate is actually a wrapper around the workflow type.

• When you click on the Ok button of your custom association form, you need to make sure the http variables have been stored somewhere; it is mandatory to provide hidden fields that will keep a trace of all variables provided by the Sharepoint framework (AddWrkfl.aspx) between postbacks. That’s reason why I’ve added the hidden fields into the WFAssoc.aspx :

[Fig 24.Hidden field to keep workflow association variables between postbacks]

My WorkflowAssociation class hides all the details of getting/storing these variables values and creating/updating the corresponding Sharepoint objects.

That’s it! Congratulations! Don’t forget that I still have to fully test this code and that I will upgrade the framework to take the other kinds of forms into account.

This hands-on training is the property of Redwood S.L sprl and may not be organized in class or in group without the prior written permission of Serge Luca. Should you wish to organize this hands-on training in your company or institution, please contact Serge Luca first to enter into a licence agreement. Each trainer or teacher using this hands-on training should have a licence agreement. Please ask your trainer or Serge Luca whether he or she has entered into a licence agreement with Redwood S.L sprl.

The hyperlink to this hands-on training may be placed on your website for free, on the condition that the name Serge Luca is clearly mentioned in the reference. Please send us a mail containing the link to the web page our reference is used on.

By Serge Luca

MVP

1. New version of WF: WF4  
2. WCF-WF integration
3. Our workflows can run in the cloud 
4. New host for WF (not just for WF) : Dublin (will ship just after VS2010)
5. New language family: M
6. Oslo : focused on Modeling (creation & storing)
7. Office 14/Sharepointx will be based on WF 3.5
8. What do you need to do next ?

1.New version of WF: WF4 

The Workflow Foundation team has recreated WF ; they started from the ground up !

What’s new in WF4 ?

1. Activity
2. Runtime
3. Tools

1.Activity

 

• Authoring is simpler and takes much less code
• Fully declarative workflows and activities expressed in Xaml (Event handler, data management, expressions, rules...). Detail: .xoml files have been renamed .xaml…) ; to author the workflow or the activities code, we can :

1. use the visual Designer
2. directly write Xaml code
3. use the Oslo M language combined with a xaml parser to generate Xaml code

• Alignment across Expressions, Rules, and Activities
• Seamless Composition Across Flow Styles
• New paradigm after sequential Workflow and State machine workflow : the FlowChart (see Fig 1)

[Fig 1.Flow Chart activity, designer usability improved; from Kenny Wolf PDC2008 session]

• An activity can have arguments (fig 2); arguments define the activity signature. Arguments have a type (any type), a name and a direction(in, out, in-out).Arguments are successors of dependency properties.

 

[Fig 2.Activity arguments: here the WinPrize activity has 3 arguments; from Kenny Wolf PDC2008 session]

• Activities can share data with other activities by using variables:

 

[ Fig 3.Variables available in the activity; from Matt Winkler PDC2008 session]

For instance, in fig 3, Generate Order activity can bind its arguments on Sequence and State Machine activity, and Send Report activity can bind its arguments on State Machine only.

In the next picture for instance we have 3 activities: Sequence, CollectVotes and AnalyzeVotes; CollectVotes has 3 arguments : Polling Place (In), ElectionDate (In) and Votes(Out); the AnalyzeVotes activity needs to get the Votes: to achieve this, we can define a Votes variables in Sequence and we can store de Out Votes arguments into the Votes variables; when Sequences closes we won’t need the variable anymore, and it’s not necessary to persist the data as we would have done in WF3.0/3.5.

 

[ Fig 4. Arguments and Variables;from Matt Winkler PDC2008 session]

• The arguments and variables of the currently running activity define the active state of the workflow (and only this state will be persisted, not the whole workflow as before).
• The activity state model has changed  :

 

1. The activity state model is different (simpler, but compatible with the 3.0/3.5 activity model) (Fig 5): Initialized state, Compensating state seem to be gone.

             [Fig 5. New simpler activity lifecycle; from Matt Winkler PDC2008 session]

2. 4.0 activities are derived from a new class WorkflowElement:

    

   
   [Fig 6. An activity is a WorkflowElement]

System.WorkflowModel.WorkflowElement  can interact with the runtime (via the SystemWorkflowModel.ActivityExecution context)

->There are now 2 blocks of execution : Activities and WorkflowElements; we can schedule a WorkflowElement.

We will be able to run 3.0/3.5 activities alongside 4.0 activities by using a new kid on the block, the Interop activity.

Code activities are gone, the Initialize method is gone.

WF 4 activities will run on the CLR 4.0

The WorkflowInvoker.Invoke method allows you to run an activity directly (not through the workflow), which is great for unit testing.  

2.Runtime

 

• 10-100X Performance Improvements :

1. execution speed
2. the persistence services doesn’t always persist the whole workflow anymore, but just the state of the running activity (the state is the variables + the arguments of the activity) –>more efficient
3. activities can be multithreaded, the scheduler is still single threaded. We can now create scalable systems by using the APM (Asynchronous Programming Model): this is not recommended in WF 3.0/3.5 because we don’t have any guarantee that when the operation returns the worflow is still there; in WF 4.0 we can use the  SetupAsynchOperationBlock() method of theWorkflowExecutionContext class.Even if the asynch operation returns when the workflow is persisted, the workflow runtime is smart enough to rehydrate the workflow. Under the cover the asynchronous activity will leave the scheduler thread and will be replaced in the scheduler thread when to operation return. Same logic for real parallel activity.

• Full control over persistence :

1. we can persist the workflow without unloading it,...)
2. we can define no persist zone (zone of the workflow where persistence will not occur, interesting in some asynchronous operations)
3. persistence state can be schematized : we can store some variables in some specific places : for instance purchase orders can be stored in a specific table.

• Flow-in Transactions : the workflow runtime knows when the host is running in a transaction and can transmit the transaction context to the activities; of course if the transaction is aborted the workflow state will be rolled back to its previous state.
• Partial Trust Support (was full trust in WF 3/3.5)
• Integrates with WCF, WPF, ASP.NET

3.Tools

 

• Designer Performance and Usability (fig 1). The designer is now based on WPF, but won’t be hosted in Silverlight in VS2010. This will probably be possible after VS2010…
• Re-hosting Improvements ( 3 lines of code to rehost the WF designer in your application instead of several hours of coding in WF 30/3.5)
• Unified Debugging Experience (we can step into expressions, rules, xaml based event handler… ).

2.WCF – WF Integration

• Message Correlation (message related to each other and to the workflow instance, fig 7) :

1. WF 3.0 : Channel (transient).
2. WF 3.5 : WorkflowContext (based on cookie/soap) (improvement in WF 4.0 : it can work over one way messages.
3. WF 4.0 : WorkflowContent : you can use your own value to specify the correlate messages and workflow instances. A Correlation Query allows to specify the value of the correlation and is used for inbound and outbound messages.  The workflow Dispatcher will retrieve the correlation value and associate the message with the workflow instance. The correlation value is associated with workflow in the Instance store; This correlation values provide a unified correlation mechanism across WF3.0-3.5-4.0

[ Fig 7.Message Correlation]

• Management Endpoint

WCF also provide a management endpoint to allow better workflow management (cancelling workflows, resuming workflows,…); this Management Endpoint is also used by Dublin.

[ Fig 8.Management Endpoint]

3.Our workflows can run in the cloud