Walkthrough: Creating a Workflow with Association and Initiation Forms

Artykuł
02/04/2013

This walkthrough demonstrates how to create a basic sequential workflow that incorporates the use of association and initiation forms. These are ASPX forms that enable parameters to be added to a workflow when it is first associated by the SharePoint administrator (the association form), and when the workflow is started by the user (the initiation form).

This walkthrough outlines a scenario where a user wants to create an approval workflow for expense reports that has the following requirements:

When the workflow is associated with a list, the administrator is prompted with an association form where they enter a dollar limit for expense reports.
Employees upload their expense reports to the Shared Documents list, start the workflow, and then enter the expense total in the workflow initiation form.
If an employee expense report total exceeds the administrator's predefined limit, a task is created for the employee's manager to approve the expense report. However, if an employee's expense report total is less than or equal to the expense limit, an auto-approved message is written to the workflow's history list.

This walkthrough illustrates the following tasks:

Creating a SharePoint list definition sequential workflow project in Visual Studio.
Creating a workflow schedule.
Handling workflow activity events.
Creating workflow association and initiation forms.
Associating the workflow.
Manually starting the workflow.

Note

Although this walkthrough uses a sequential workflow project, the process is the same for state machine workflows.

Also, your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Working with Settings.

Prerequisites

You need the following components to complete this walkthrough:

Supported editions of Microsoft Windows and SharePoint. For more information, see Requirements for Developing SharePoint Solutions.
Visual Studio 2010.

Creating a SharePoint Sequential Workflow Project

First, create a sequential workflow project in Visual Studio. A sequential workflow is a series of steps that executes in order until the last activity finishes. In this procedure, you will create a sequential workflow that applies to the Shared Documents list in SharePoint. The workflow's wizard lets you associate the workflow with either the site or the list definition and lets you determine when the workflow will start.

To create a SharePoint sequential workflow project

Display the New Project dialog box by pointing to New on the File menu, and then click New Project.
Expand the SharePoint node under either Visual C# or Visual Basic, and then click 2010.
In the Templates pane, select Sequential Workflow.
In the Name box, type ExpenseReport and then click OK.

The SharePoint Customization Wizard appears.
In the What is the local site you want to use for debugging? page, click Next to accept the default site.

This step also sets the trust level for the solution as farm solution, which is the only available option for workflow projects.
In the Specify the workflow name for debugging page, accept the default name (ExpenseReport - Workflow1). Keep the default workflow template type value (List Workflow). Click Next.
In the Would you like Visual Studio to automatically associate the workflow in a debug session? page, clear the box that automatically associates your workflow template if it is checked.

This step lets you manually associate the workflow with the Shared Documents list later on, which displays the association form.
Click Finish.

Adding an Association Form to the Workflow

Next, create an .ASPX association form that appears when the SharePoint administrator first associates the workflow with an expense report document.

To add an association form to the workflow

Click the Workflow1 node in Solution Explorer.
Click Add New Item on the Project menu to display the Add New Item dialog box.
In the dialog box tree view, expand either Visual C# or Visual Basic (depending on your project language), expand the SharePoint node, and then click 2010.
In the list of templates, select Workflow Association Form.
In the Name text box, type ExpenseReportAssocForm.aspx.
Click the Add button to add the form to the project.

Designing and Coding the Association Form

In this procedure, you introduce functionality to the association form by adding controls and code to it.

To design and code the association form

In the association form (ExpenseReportAssocForm.aspx), locate the asp:Content element that has ID="Main".

Directly after the first line in this content element, add the following code to create a label and textbox that prompts for the expense approval limit (AutoApproveLimit):

<asp:Label ID="lblAutoApproveLimit" Text="Auto Approval Limit:" runat="server" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<asp:TextBox ID="AutoApproveLimit" runat="server" />
<br /><br />

Expand the ExpenseReportAssocForm.aspx file in Solution Explorer to display its dependent files.

Note

If your project is in Visual Basic, you must click the View All Files button to perform this step.
Right-click the ExpenseReportAssocForm.aspx file and select View Code.

Replace the GetAssociationData method with:

Private Function GetAssociationData() As String
    ' TODO: Return a string that contains the association data that 
    ' will be passed to the workflow. Typically, this is in XML 
    ' format.
    Return Me.AutoApproveLimit.Text
End Function

private string GetAssociationData()
{
    // TODO: Return a string that contains the association data that 
    // will be passed to the workflow. Typically, this is in XML 
    // format.
    return this.AutoApproveLimit.Text;
}

Adding an Initiation Form to the Workflow

Next, create the initiation form that appears when users run the workflow against their expense reports.

To create an initiation form

Click the Workflow1 node in Solution Explorer.
Click Add New Item on the Project menu to display the Add New Item dialog box.
In the dialog box tree view, expand either Visual C# or Visual Basic (depending on your project language), expand the SharePoint node, and then click 2010.
In the list of templates, select Workflow Initiation Form.
In the Name text box, type ExpenseReportInitForm.aspx.
Click the Add button to add the form to the project.

Designing and Coding the Initiation Form

Next, introduce functionality to the initiation form by adding controls and code to it.

To code the initiation form

In the initiation form (ExpenseReportInitForm.aspx), locate the asp:Content element that has ID="Main".

Directly after the first line in this content element, add the following code to create a label and textbox that displays the expense approval limit (AutoApproveLimit) that was entered in the association form, and another label and textbox to prompt for the expense total (ExpenseTotal):

<asp:Label ID="lblAutoApproveLimit" Text="Auto Approval Limit:" runat="server" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<asp:TextBox ID="AutoApproveLimit" ReadOnly="true" runat="server" />
<br /><br />
<asp:Label ID="lblExpenseTotal" Text="Expense Total:" runat="server" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<asp:TextBox ID="ExpenseTotal" runat="server" />
<br /><br />

Expand the ExpenseReportInitForm.aspx file in Solution Explorer to display its dependent files.
Right-click the ExpenseReportInitForm.aspx file and select View Code.

Replace the Page_Load method with the following example:

Protected Sub Page_Load(ByVal sender As Object, ByVal e As 
  EventArgs) Handles Me.Load
    InitializeParams()
    Me.AutoApproveLimit.Text = workflowList.WorkflowAssociations(New 
      Guid(associationGuid)).AssociationData
    ' Optionally, add code here to pre-populate your form fields.
End Sub

protected void Page_Load(object sender, EventArgs e)
{
    InitializeParams();
    this.AutoApproveLimit.Text = 
      workflowList.WorkflowAssociations[new 
      Guid(associationGuid)].AssociationData;
}

Replace the GetInitiationData method with the following example:

' This method is called when the user clicks the button to start the workflow.
Private Function GetInitiationData() As String
    Return Me.ExpenseTotal.Text
    ' TODO: Return a string that contains the initiation data that 
    ' will be passed to the workflow. Typically, this is in XML 
    ' format.
    Return String.Empty
End Function

// This method is called when the user clicks the button to start the workflow.        
private string GetInitiationData()
{
    // TODO: Return a string that contains the initiation data that 
    // will be passed to the workflow. Typically, this is in XML 
    // format.
    return this.ExpenseTotal.Text;
}

Customizing the Workflow

Next, customize the workflow. Later, you will associate two forms to the workflow.

To customize the workflow

Display the workflow in the workflow designer by double-clicking Workflow1 in the project.
In the Toolbox, expand the Windows Workflow v3.0 node and locate the IfElse activity.
Add this activity to the workflow by dragging it into the designer and dropping it just under the onWorkflowActivated1 activity in the workflow. This creates an activity called IfElseActivity1 in the designer.
In the Toolbox, expand the SharePoint Workflow node and locate the CreateTask activity.
Add this activity to the workflow by dragging and dropping it onto one of the two Drop Activities Here areas within IfElseActivity1.
In the Properties window, enter a property value of taskToken for the CorrelationToken property.
Expand the CorrelationToken property by clicking the plus sign () next to it.
Click the drop-down arrow on the OwnerActivityName sub property and select Workflow1.
Click the TaskId property and then click the ellipsis () button to display the Bind Property dialog box.
Click the Bind to a new member tab, select Create Field, and then click OK.
Click the TaskProperties property and then click the ellipsis () button to display the Bind Property dialog box.
Click the Bind to a new member tab, select Create Field, and then click OK.
In the Toolbox, expand the SharePoint Workflow node and locate the LogToHistoryListActivity activity.
Add this activity to the workflow by dragging and dropping it onto the other Drop Activities Here area within IfElseActivity1.

Adding Code to the Workflow

Next, add code to the workflow to give it functionality.

To add code to the workflow

Double-click the createTask1 activity in the workflow designer to generate an empty method for the MethodInvoking event.

Replace the MethodInvoking method with:

Private Sub createTask1_MethodInvoking(ByVal sender As 
  System.Object, ByVal e As System.EventArgs)
    createTask1_TaskId1 = Guid.NewGuid
    createTask1_TaskProperties1.AssignedTo = "somedomain\\someuser"
    createTask1_TaskProperties1.Description = "Please approve the 
      expense report"
    createTask1_TaskProperties1.Title = "Expense Report Approval 
      Needed"
End Sub

private void createTask1_MethodInvoking(object sender, EventArgs e)
{
    createTask1_TaskId1 = Guid.NewGuid();
    createTask1_TaskProperties1.AssignedTo = "somedomain\\someuser";
    createTask1_TaskProperties1.Description = "Please approve the 
      expense report";
    createTask1_TaskProperties1.Title = "Expense Report Approval 
      Needed";
}

Note

In the code, replace somedomain\\someuser with a domain and user name for which a task will be created, such as, "Office\\JoeSch". For testing it is easiest to use the account you are developing with.

Below the MethodInvoking method, add the following example:

Private Sub checkApprovalNeeded(ByVal sender As Object, ByVal e As 
  ConditionalEventArgs)
    Dim approval As Boolean = False
    If (Convert.ToInt32(workflowProperties.InitiationData) > 
      Convert.ToInt32(workflowProperties.AssociationData)) Then
        approval = True
    End If
    e.Result = approval
End Sub

private void checkApprovalNeeded(object sender, ConditionalEventArgs 
  e)
{
    bool approval = false;
    if (Convert.ToInt32(workflowProperties.InitiationData) > 
      Convert.ToInt32(workflowProperties.AssociationData))
    {
        approval = true;
    }
    e.Result = approval;
}

In the workflow designer, click the ifElseBranchActivity1 activity.
In the Properties window, click the drop-down arrow of the Condition property and select Code Condition.
Expand the Condition property by clicking the plus sign () next to it and then set its value to checkApprovalNeeded.
In the workflow designer, right-click the logToHistoryListActivity1 activity and select Generate Handlers to generate an empty method for the MethodInvoking event.

Replace the MethodInvoking code with the following:

Private Sub logToHistoryListActivity1_MethodInvoking(ByVal sender As 
  System.Object, ByVal e As System.EventArgs)
    Me.logToHistoryListActivity1.HistoryOutcome = ("Expense was auto 
      approved for " + workflowProperties.InitiationData)
End Sub

private void logToHistoryListActivity1_MethodInvoking(object sender, 
  EventArgs e)
{
    this.logToHistoryListActivity1.HistoryOutcome = "Expense was 
      auto approved for " + workflowProperties.InitiationData;
}

Press F5 to debug the program.

This compiles the application, packages it, deploys it, activates its features, recycles the IIS application pool, and then starts the browser at the location specified in the Site Url property.

Associating the Workflow to the Documents List

Next, display the workflow association form by associating the workflow with the Shared Documents list on the SharePoint site.

To associate the workflow

Click Shared Documents on the QuickLaunch bar.
Click Library on the Library Tools ribbon tab and then click the Library Settings ribbon button.
In the Permissions and Management section, click the Workflow Settings link and then click the Add a workflow link on the Workflows page.
In the top list in the workflow settings page, select the ExpenseReport - Workflow1 template.
In the next field, type ExpenseReportWorkflow and then click the Next button.

This associates the workflow with the Shared Documents list and displays the workflow association form.
In the Auto Approval Limit text box, type 1200 and then click the Associate Workflow button.

Starting the Workflow

Next, associate the workflow to one of the documents in the Shared Documents list to display the workflow initiation form.

To start the workflow

On the SharePoint page, click the Home button and then display the Shared Documents list on the SharePoint site by clicking the Shared Documents link on the QuickLaunch bar.
Upload a new document into the Shared Documents list by clicking the Documents link on the Library Tools tab at the top of the page, and then clicking the Upload Document button on the ribbon.
Point the mouse at the uploaded document to display a drop-down arrow. Click the drop-down arrow and select Workflows.
Click the image next to the ExpenseReportWorkflow.

This displays the workflow initiation form. (Note that the value displayed in the Auto Approval Limit box is read-only because it was entered in the association form.)
In the Expense Total text box type 1600 and then click Start Workflow.

This displays the Shared Documents list again. A new column named ExpenseReportWorkflow with the value Completed is added to the item the workflow just started.
Click the drop-down arrow next to the uploaded document and then click Workflows to display the workflow status page. Click the value Completed under Completed Workflows. The task is listed under the Tasks section.
Click the title of the task to display its task details.
Go back to the Shared Documents list and restart the workflow, using either the same document or a different one.
Enter a amount on the initiation page that is less than or equal to the amount entered on the association page (1200).

When this occurs, an entry in the history list is created instead of a task. The entry displays in the Workflow History section of the workflow status page. Note the message in the Outcome column of the history event. It contains the text entered in the logToHistoryListActivity1.MethodInvoking event that includes the amount which was auto–approved.

Next Steps

You can learn more about how to create workflow templates from these topics:

To learn more about SharePoint workflows, see Workflows in Windows SharePoint Services.

Udostępnij za pośrednictwem