Demonstration Scenario of line-of-business applications - Share Point 2010

To give you an idea of how OpenXML and Word Automation Services can be used together to build useful line-of-business applications, consider the following demonstration scenario: You’ve been engaged by AdventureWorks to design and build a document creation and collaboration tool. The tool will be used by the company’s sales department for producing sales proposals. Each proposal is made up of a number of different documents contributed by various users from different departments. The tool to be built should combine these documents into a single read-only document that can be sent to the customer for consideration. The input documents will be saved in Microsoft Word OpenXML format. The output document should be in Adobe Acrobat (PDF) format.

Architecture

You need to consider the following points to create an architecture that fits this scenario:

• Multiple documents will logically make up a single set. Bearing this in mind, we can use the Document Set functionality discussed in Chapter .
• By using OpenXML, we can combine a number of different types of documents into a single OpenXML document.
• Word Automation Services can be used to convert the output OpenXML document into an Adobe Acrobat–compatible file.
• Because the process of combining documents is likely to be long-running, we have two possibilities: we could use the SPLongOperation object, which will present the user with the familiar spinning disc image while the process runs. Or we could use a custom job on the server, which will free up the user to perform other activities while the process completes. For the purposes of our demonstration, we’ll use the custom job approach since it illustrates functionality that is useful in many development situations. Bearing these points in mind, we can create a custom content type that derives from the Document Set content type. We’ll then develop a custom web part control that will provide a user interface for combining the contents of our custom content set. To do the actual combination, we’ll create a custom job that uses OpenXML and Word Automation Services to put the finished document together and convert the output to PDF.

Creating a Custom Content Type
First we’ll create a new bank site and then provision the Document Set content type before we add a custom content type and define our user interface.

1. From the Site Actions menu, create a new Blank Site named, as shown:
   

   

2. As described in detail in Chapter , enable the Document Sets feature. From the Site Actions menu, select Site Settings | Go To Top Level Site Settings | Site Collection Features. Activate the Document Sets feature.
3. We’ll next add a custom content type for our Sales Proposal. Navigate back to the blank site that we created earlier From the Site Actions menu, select Site Settings. In the Galleries section, select Site Columns, as shown.
   

   

4. Create a new column named JobId of type Single Line Of Text. Save the column in the Custom Columns group.
5. Create a new column named TemplateUrl of type Single Line Of Text. Save the column in the Custom Columns group.
6. Navigate back to the Site Settings page, and then select Site Content Types from the Galleries section.
7. Create a new content type named Sales Proposal. Set the Parent Content Type field to Document Set and save it within the Custom Content Types group, as shown:
   

   

8. With our new content type created, we can add in the site columns that we created earlier. In the Columns section, click Add From Existing Site Columns. From the Custom Columns group, add the JobId and the TemplateUrl columns. Click OK to commit the changes.

Customizing the DocumentSetProperties Web Part

Before we can customize the welcome page for our custom document set, we need to build a web part with the following additional features:

• A Build Sales Proposal button that creates and starts the compilation job
• A status indicator that shows the progress of the compilation job
• A link to the compiled output file

Although we could create a separate web part that could be used in conjunction with the built-in DocumentPropertiesWebPart, it wouldn’t be overly useful as a stand-alone component elsewhere. Instead, we’ll create a web part that inherits from the DocumentPropertiesWebPart and adds our required additional functionality.

1. Using Visual Studio 2010, create a new Empty SharePoint Project named Sales Proposal Application, as shown:
   

   

2. Set the debugging site to be the blank site that we created in the preceding section, and select the Deploy As Farm Solution option. Click Finish to create the project.
3. After the project has been created, add a new Visual Web Part named Sales Proposal Properties WebPart. As you saw earlier , Visual Web Parts provide a design surface when we’re creating web parts. However, since we’re planning to override a built-in web part that already has its own rendering logic, we need to change some of the generated code for the Visual Web Part.
4. Add a reference to the Microsoft.Office.Document Management assembly, located in the %SPROOT%isapi folder, to the project.
5. In the SalesProposalPropertiesWebPart.cs file, add the following code:
   using System.ComponentModel; using System.Web.UI; using Microsoft.Office.Server.WebControls; namespace SalesProposalApplication. SalesProposalPropertiesWebPart { [ToolboxItemAttribute(false)] public class SalesProposalPropertiesWebPart : DocumentSetPropertiesWebPart { // Visual Studio might automatically update //this path when you change the Visual Web Part project item. private const string _ascxPath = @"~/_CONTROLTEMPLATES/SalesProposalApplication/ SalesProposalPropertiesWebPart/ SalesProposalPropertiesWebPartUserControl.ascx"; protected override void CreateChildControls() { Control control = this.Page.LoadControl(_ascxPath); this.Controls.Add(control); base.CreateChildControls(); } protected override void RenderWebPart (HtmlTextWriter writer) { base.RenderWebPart(writer); this.Controls[0].RenderControl(writer); } } }

TIPWhen overriding any built-in SharePoint classes, it can be challenging to work out exactly what you need to do to get the behavior that you expect. In the code snippet, to get our web part to render properly, we explicitly need to render our custom user control by overriding RenderWebPart method. Uncovering details such as this from the documentation is often impossible. With our custom user control properly hooked up to our web part, we can implement the rest of our custom logic via the user control.

1. We’ll make use of Asynchronous JavaScript and XML (AJAX) so that the web part can periodically check on the status of the timer job and redraw the controls. Add an UpdatePanel control to the Sales Proposa lProperties WebPart UserControl .ascxfile.
2. We’ll use an AJAX Timer so that we can automatically refresh the status indicator on our control. Drag the Timer control from the toolbox onto the user control design surface. Name the Timer RefreshTimer and set its Enabled property to False
3. From the toolbox, add a Label control, a Hyperlink control, and a Button control to the Sales Proposal Properties WebPartUserControl.ascx file. Within the UpdatePanel control markup, lay out and rename the controls as follows:
<asp:UpdatePanel runat="server"><ContentTemplate><div width="100%"><br /><asp:Label ID="StatusLabel" runat="server" Text=""></asp:Label><br /><asp:HyperLink ID="OutputHyperlink" runat="server"> Click here to download a compiled copy</asp:HyperLink><br /><asp:Button ID="StartCompilation" OnClick="StartCompilation_Click" runat="server" Text="Start Compilation" /></div></ContentTemplate><Triggers><asp:AsyncPostBackTrigger ControlID="RefreshTimer" EventName="Tick" /></Triggers></asp:UpdatePanel><asp:Timer runat="server" ID="RefreshTimer" Enabled="False"></asp:Timer>
4. In the code-behind file (Sales Proposal Properties WebPart User Control.aspx.cs), andthe following code:

Before our customized web part can be deployed,we need to make a few changes to the solution. The default packaging mechanisms that are set up in Visual Studio work well for creating web parts that are derived directly from System. Web. UI. Web Controls.Webparts. Webpart. However, when creating a web part that’s derived from another base class, we’ll occasionally see an “Incompatible Web Part Markup” error message when we’re trying to use the deployed web part on a page. To resolve this error, we need to use an alternative packaging format.

1. Rename the Sales Proposal Properties WebPart. webpart file to Sales Proposal Properties Web Part.dwp.
2. Replace the contents with the following XML:
<WebPart xmlns="http://schemas.microsoft.com /WebPart/v2"><Assembly> $SharePoint.Project.AssemblyFullName$</Assembly><TypeName> SalesProposalApplication.SalesProposalProperties WebPart.SalesProposalPropertiesWebPart</TypeName> <Title>SalesProposalPropertiesWebPart</Title> <Description>Web Part Description</Description> </WebPart>
3. So that the renamed file is installed properly, edit the Elements.ml file in the Sales Proposal Properties Web Part folder as follows:

Creating a Custom Job Definition
With our user interface largely complete, our next step is to define a custom job that will compile all documents in our document set and send the compiled output to Word Automation Services for conversion to PDF. In Visual Studio, add a new class named DocumentCombinerJob.cs. Add the following code to the file:

Developers familiar with SharePoint 2007 should notice a few interesting elements in this code snippet. First, check out the HasAdditionalUpdateAccess override. In previous versions of SharePoint, only farm administrators could create jobs. This greatly restricted their usefulness for offloading ad hoc tasks. With SharePoint 2010, where the HasAdditionalUpdateAccess method returns true, any user can create a job. Also notice that when we’re creating a job, the job can be associated with either a service or an application pool. These associations are primarily for administrative purposes since most jobs run via the SPTimerV4 service. In our example, we’re associating our custom jobwith the TimerService. The final thing to notice is that job definitions are serialized when a job is created. As a result, not all types of objects can be defined as properties. For example, the SPListItem isn’t serializable and therefore can’t be stored as a property. To get around this problem, we’re storing a number of identifiers that can be used to recover a reference to the appropriate SPListItem object when the job is deserialized.

Combine Documents Using OpenXML
Before we can make use of OpenXML, we need to add a reference to the OpenXML SDK binaries:

1. Download and install the OpenXML SDK; then, in Visual Studio, add a reference to the DocumentFormat.OpenXML assembly.
2. Add a reference to the WindowsBase assembly.
3. To prevent any confusion between similarly named objects within the Open XML SDK, add the following Using statement to the Document CombinerJob.cs file:

using Word = DocumentFormat.OpenXml.Wordprocessing;

4. In the DocumentCombinerJob.cs file, add the following code:

In this code snippet, the CombineDocuments method loads a Microsoft Word format template. The code then searches for all content controls within the document, and where the content control has a title of MergePlaceholder, the contents of all files with a.docx extension within the document set are merged into the template. The merge process makes use of the Alternative Format Import Part control to merge contents. This control inserts a binary copy of data into the template at a specific position. When the completed document is rendered in a client application, the merge is performed dynamically each time the document is opened.

Converting an OpenXML Document to an Alternative Format
Before we can make use of Word Automation Services in our application, we need to add a reference to the appropriate assembly:

1. In Visual Studio, add a reference to Microsoft.Office.Word.Server.dll. At the time of writing, this appears in the Add Reference dialog as one of two components named Microsoft Office 2010 component; this problem may be resolved in the final release.
2. Update the ConvertOutput method in DocumentTimerJob.cs as follows:
private void ConvertOutput(SPSite site, SPWeb web, SPFile output) { ConversionJob convJob = new ConversionJob(_proxyId); convJob.Name = "Document Assembly"; convJob.UserToken = web.CurrentUser.UserToken; convJob.Settings.UpdateFields = true; convJob.Settings.OutputFormat = SaveFormat.PDF; convJob.Settings.OutputSaveBehavior = SaveBehavior. AlwaysOverwrite; string webUrl = web.Url + "/"; convJob.AddFile(webUrl + output.Url, webUrl + output. Url.Replace(".docx", ".pdf")); convJob.Start(); Guid jobId = convJob.JobId; ConversionJobStatus status = new Conversion JobStatus(_proxyId, jobId, null); while (status.Count != (status.Succeeded + status.Failed)) { Thread.Sleep(3000); status.Refresh(); } if (status.Failed == status.Count) { throw new InvalidOperationException(); } With our custom job definition completed, we can cange the implementation in our user interface to create a new instance of the job.
3. In SalesProposalWebPartUserControl.ascx.cs, change the StartCompilation_Click method as follows:

We’ve now completed the code required to implement our demonstration scenario. Deploy the project by selecting Deploy SalesProposalApplication from the Build menu.

Customizing Document Set Welcome Page
As you saw, each document set has a welcome page that contains a list of the documents within the set as well as information about the set itself. The web part that we created earlier will be used to customize the welcome page for our Sales Proposal document set so that whenever the content type is used, our custom control will be displayed instead of the built-in DocumentSetProperties control.

1. Navigate to the site that we created earlier. Select Site Settings from the Site Actions menu.
2. Select Site Content Types from the Galleries section and then click the Sales Proposal content type.
3. Select the Document Set settings link in the Settings section and then, in the Welcome Page section, click the Customize the Welcome Page link, as shown here:



4. From the Page tab in the ribbon, select Edit Page.
5. Delete the Document Set Properties web part, and then click the Add a Web Part link in Zone 2 to show the web part selector.
6. Add the SalesProposal Properties Web Part from the Custom category, as shown:
   
7. Click Stop Editing to commit the changes to the welcome page.

Create a Document Library
Before we can begin creating sales proposals, we need to create a new document library that is bound to our Sales Proposal content type.

1. From the Site Actions menu, select New Document Library. Name the new library Sales Proposals.
2. After the new library has been created, select Library Settings from the Library tab of the ribbon.
3. In the Document Library Settings page, select Advanced Settings, andthe Allow Management Of Content Types option. Click OK to save the changes.
4. From the Content Types section, click Add From Existing Site Content Types, and then select the Sales Proposal content type, as shown. Click OK to save the changes.

Create a Document Template
Our final step before we can see our document set functionality in action is to create a template for our compilation process. Since we need to add Content Controls to our template document, we can create the document using Visual Studio.

1. To our SalesProposalApplication solution, add a new project of type Word 2010 Document, as shown. Name the project SampleTemplate.


2. Drag a RichTextContentControl onto the SampleTemplate.docx file. Type the Title property as MergePlaceholder, as shown:


3. Close the SampleTemplate.docx pane in Visual Studio, and then save the project.
4. Right-click the project node and select Open Folder in Windows Explorer.
5. Create a new document library named Document Templates and upload the SampleTemplate.docx file.

TIPWhen you select the Upload Document | Upload Multiple Documents option from the Documents tab, the file can be uploaded by dragging and dropping it onto the dialog box. We can now make use of our Sales Proposals document set to create a composite document.

1. Navigate to the Sales Proposals document library, and then select New Document | Sales Proposal from the Documents tab of the ribbon.
2. In the New Document Set: Sales Proposal dialog, enter the URL of the sample template in the TemplateUrl box.
3. Upload a few Word documents to the document set, and then click the Start Compilation button. If all is well, after a few minutes a link will appear as shown, allowing us to download a PDF copy of the compiled sales proposal: