Step 2: Design the Workflow

Article
07/24/2014

Applies to: SharePoint Server 2010

This topic shows how to design a workflow that initiates a Word Automation Services conversion job.

Designing the Workflow

The solution that you create in this walkthrough initiates a Word Automation Services conversion job based on the status of a document in a document library and then archives the converted document. When the document status is changed to Final, a SharePoint workflow begins that creates a Word Automation Services conversion job and then places the document that was output from the conversion into the same document library as the input document.

The workflow consists of two steps with an optional third step: the first step checks the Status property of the input document has been set to Final; if so, the second step converts the document. The third step monitors the conversion job through completion.

Checking the Document Status Property

The first step of the workflow checks the Status property of the document in the input library.

To check the document status

In the Visual Studio 2010 project that you created in Step 1 of this walkthrough, add a While activity after the existing onWorkflowActivated activity. The While activity is under Windows Workflow v3.0 in the Toolbox.
From the Toolbox, under SharePoint Workflow, add an OnWorkflowItemChanged activity inside the While activity.
Click the activity. From the Properties window, set the value of the CorrelationToken property to workflowToken (the only item in the drop-down list). This associates the ItemChanged event with the correct workflow.
In the Properties window, click the lightning bolt to switch to Events view, and press ENTER in the Invoked method to create a blank event handler.
In the code window, add a global variable to the class to track whether the Status property has been set to the desired value.
```
bool documentReady = false;
```

In the event handler for the onWorkflowItemChanged event, add code to check the value of the Status column, and set the documentReady variable appropriately.

//Check if the Status is set to "Final"; if so, the document is ready to archive
if (workflowProperties.Item["Status"] != null)
{
    documentReady = ((string)workflowProperties.Item["Status"] == "Final");
}

In the workflow designer window, click on the While activity. In the Properties window, click the drop-down next to Condition and then select Declarative Rule Condition.
Expand Condition, exposing ConditionName and Expression.
In the ConditionName field, enter a name for the condition, for example, Ready to Archive.
In the Expression field, click the ellipsis button next to Condition Expression.
In the Rule Condition Editor dialog, add code that sets the condition.
```
documentReady == false
```
Click OK to save the condition.
The resulting workflow now looks like the following diagram.

Converting the Document

When the document Status property is set to Final, the second step of the workflow converts the document using Word Automation Services.

To convert the document

In the code page for the workflow, add a using directive for the namespace that contains the Word Automation Services object model that you use to perform document conversions.
```
using Microsoft.Office.Word.Server.Conversions;
```
In the workflow designer page, add a Code activity from the Visual Studio 2010 Toolbox after the existing While activity.
With the Code activity selected in the workflow designer page, click the lightning bolt in Properties to switch to the Events view, and then press ENTER in the ExecuteCode field to create an empty event handler.
In the resulting empty event handler for the ExecuteCode event, add code to perform the document conversion.
```
// Create a Word Automation Services conversion job
ConversionJob job = new ConversionJob("Word Automation Services");

// Specify conversion settings
job.UserToken = workflowProperties.OriginatorUser.UserToken;
if (workflowProperties.Site.SiteSubscription != null)
    job.SubscriptionId = workflowProperties.Site.SiteSubscription.Id;
job.Settings.OutputFormat = SaveFormat.XPS;
job.Name = "Archive Document Workflow";

// Add the file
string fileUrl = workflowProperties.WebUrl + "/" + workflowProperties.ItemUrl;
job.AddFile(fileUrl, Path.ChangeExtension(fileUrl, "xps"));

// Schedule the conversion
job.Start(); 
```
This code creates a new ConversionJob, which defines a set of conversions, by calling the constructor for the ConversionJob that takes the name of the service application as an argument.

Note

This example assumes the name of the service application is Word Automation Services, which is the default name when it is created using the SharePoint Server 2010 Farm Configuration Wizard. If you have used a different name for the service application, use that name as the argument for the ConversionJob constructor in the preceding code example.

Next, the code sets the necessary settings for document conversion:
- UserToken - specifies the user credentials used to read the input file and to write the output file.
- SubscriptionId - specifies the site subscription ID of the site.
  
  Note
  
  This parameter is only required if the SharePoint farm has been configured in partitioned mode.
- OutputFormat - specifies the output file format for the conversion.
In addition, the code specifies one optional setting for the conversion:
- Name - specifies a friendly name for the conversion.
The resulting workflow now looks like the following diagram.

Monitoring the Conversion

Once a document conversion is scheduled, it is processed asynchronously. Optionally, you can add a step to the solution to monitor the result of the conversion before terminating the workflow, so that the workflow completes after the conversion.

To monitor the document conversion

In the workflow designer page, add a While activity from the Visual Studio 2010 Toolbox after the existing Code activity.
From the Toolbox, under Windows Workflow v3.0, add a Sequence activity inside the While activity.
From the Toolbox, under Windows Workflow v3.0, add a Delay activity inside the Sequence activity.
With the Delay activity selected in the workflow designer page, in the Properties window, click on the TimeoutDuration field and set it to 00:00:30 (30 seconds). This means that the workflow will be re-checked at most every 30 seconds.

Note

From the Toolbox, under Windows Workflow v3.0, add a Code activity immediately after the existing Delay activity.
With the new Code activity selected in the workflow designer page, click the lightning bolt in Properties to switch to the Events view, and then press ENTER in the ExecuteCode field to create an empty event handler.
In the code page for the workflow, add a using directive for the namespace that contains the ReadOnlyCollection<T> class used later in this procedure.
```
using System.Collections.ObjectModel;
```
Add two global variables to the class: a Guid value to store the JobId of the conversion job, and a Boolean value to track whether the conversion completed successfully.
```
Guid jobId;
bool conversionComplete = false;
```
In the first code method, codeActivity1_ExecuteCode, store the JobId of the conversion job in the jobId variable by adding the following code after the Start method.
```
// Schedule the conversion
job.Start();

// Save the conversion job ID
jobId = job.JobId;
```

In the new event handler created in this procedure, codeActivity2_ExecuteCode, add code to check the status of the conversion.

// Monitor the conversion
// Get the site subscription ID
Guid? siteSubscription = null;
if (workflowProperties.Site.SiteSubscription != null)
    siteSubscription = workflowProperties.Site.SiteSubscription.Id;

// Check if the conversion is complete; if it is, refresh
ConversionJobStatus status = new ConversionJobStatus("Word Automation Services", jobId, siteSubscription);

if (status.Count == status.Succeeded)
{
    // Success!
    conversionComplete = true;
}
else if (status.Count == status.Failed)
{
    // Conversion failed
    ReadOnlyCollection<ConversionItemInfo> failedItems = status.GetItems(ItemTypes.Failed);
    throw new Exception(failedItems[0].ErrorMessage);
}
else if (status.Count == status.Canceled)
{
    // Conversion was canceled
    throw new Exception("Conversion was canceled.");
}

// Since the conversion is not yet completed, keep waiting

The code checks the status of the conversion using the ConversionJobStatus object.

Note

This example assumes the name of the service application is Word Automation Services, which is the default name when it is created using the SharePoint Server 2010 Farm Configuration Wizard. If you have used a different name for the service application, use that name as the argument for the ConversionJobStatus constructor in the preceding code snippet.

The code checks the conversion job status to determine whether the item has been successfully converted or not, and reacts accordingly. Otherwise, the code takes no action because the conversion is in progress.

With the While activity selected in the workflow designer, in the Properties window, click the Condition field and then select Declarative Rule Condition.
Expand Condition, exposing ConditionName and Expression.
In the ConditionName field, enter a name, for example, Conversion Complete.
In the Expression field, click the ellipsis button next to Condition Expression.
In the Rule Condition Editor dialog, add code that sets the condition.
```
conversionComplete == false
```
Click OK to save the condition.
In the workflow designer, the final workflow should look like the following diagram.