microsoft word

Following up on my first post
about Word Automation Services, I wanted to continue by talking about
the functionality offered (and not offered) by the service, how it's
exposed, and the types of solutions you will be able to build on top of
it. What the Service Does


Functionally, the service is very simple – this is intentional, as
we wanted to address the pain points that we've heard loud and clear
from you over the past few years, while keeping performance and scale
at the top of our priorities (which meant avoiding the temptation to
bring over everything "just because"). With that mindset, we really only set out to tackle the two most common requests that we hear:

1. I have a bunch of Word documents. I want to convert them to PDF on the server in bulk (e.g. DOCX to PDF).
   
2. I have a template and some data. I want to merge the two and
   create a set of PDF files; one per merge result (e.g. mail merge to
   PDF).
   

Now, when we hear that, the output format's not always PDF (but it's
probably the most common). As we translated that to features, it meant
that the server needed to do one thing really well: file conversions.
Accordingly, Word Automation Services supports conversions to/from
almost all of the formats Word client understands: File formats the service can read:

• Office Open XML (DOCX, DOCM, DOTX, DOTM)
  
• 
  Word 97-2003 Document (DOC) and Word 97-2003 Template (DOT)
  
  
  
  • We also support older versions of Word as far back as Word 2.0 for Windows (!)
    
  
  


• Rich Text Format (RTF)
  
• Single File Web Page (MHTML)
  
• HTML
  
• Word 2003 XML
  
• Word 2007/2010 XML
  

File formats the service can write:

• PDF
  
• XPS
  
• Office Open XML (DOCX, DOCM)
  
• Word 97-2003 Document (DOC)
  
• Rich Text Format (RTF)
  
• Single File Web Page (MHTML)
  
• Word 2007/2010 XML
  

This also meant that we needed to support all of the features that are part of loading/saving documents, i.e.:

• XML data mapping – you can place updated XML in the document, and content controls will automatically be updated
  
• Fields – the service (or the file) can be set to recalculate fields automatically during conversion
  
• AF Chunks – you can embed documents (DOCX, HTML, RTF, DOC)
  within a DOCX file, and have the service merge in the content
  automatically
  
• Upgrade – you can specify whether the file should be upgraded as part of loading it on the server
  
• Add Thumbnail images on save
  
• Etc.
  

How It's Exposed


To expose this capability, we also thought small (and hopefully
simple) – the service exists as a managed API you can utilize on
SharePoint, allowing you to build on top of it as appropriate for your
solutions – maybe that's a WCF service, maybe a custom workflow
activity, etc. That API breaks down into two basic objects:

• ConversionJob – the object that encapsulates 1+ conversions that you want to perform as a logical unit
  
• ConversionJobStatus – the object that allows you to query the status of a ConversionJob while/after it's processed
  

With the first, you ask us to convert files on the server and put
the result back on the server; with the second, you query the progress
of that conversion process. Example


As an example, consider a server solution in which I want to allow
users to schedule self-service conversions: they can right-click on a
file in SharePoint and request a XPS version of that file. On my ASPX page for the conversion, the button handler might contain the following code: public void Convert_Click(…){
ConversionJob job = new ConversionJob("Word Automation Services")
job.UserToken = SPContext.Site.UserToken;
job.UpdateFields = true;
job.OutputFormat = SaveFormat.XPS;
job.AddFile("http://contoso.com/input/foo.docx","http://contoso.com/output/foo.xps");
job.Start();
}

And that's all that's required – I create a ConversionJob object to
encapsulate the action, tell it to convert to XPS and update fields
using my credentials to read/write the files, tell it the file to
convert, and use Start() to kick off the process. Once it's running, I can easily query the status of that
conversion – the job.JobId property specified a unique GUID for that
job that I could have stored and reused, e.g.: public void CheckStatus(Guid jobId)
{
ConversionJobStatus status = new ConversionJobStatus("Word Automation Services", jobId, null);
if (status.Count == status.Succeeded)
{
//success!
//do something
}
else if (status.Count == status.Failed)
{
//failure
//do something else
}
…
}

Just by creating a ConversionJobStatus object, I immediately know
where that item is in the system (Succeeded, Failed, InProgress,
NotStarted) and can react appropriately. That example's probably two-thirds of the API – the goal
really was to keep it simple and focus doing those two things really
well. Back to the Open XML SDK


Now, the one thing I didn't directly address in this post was the "merging documents with data" piece above.
That part of our solution isn't just the service itself – it's
actually solved in combination with the Open XML SDK. I'm going to talk
about the SDK a lot when I talk about the server; as I said in the
first post, it's the combination of the two that provides the
end-to-end story that we believe replaces the need to automate the
client applications. In this case, you'd use the SDK to clone the template and
inject the data (a task well suited to manipulation of the file
format), and use the service to convert the resulting files to PDF/XPS.
I hope that was a useful introduction to what we're doing and
how you'll be able to work with it – in the next post, I'll talk more
about our architecture and how we're leveraging the strengths of the
SharePoint platform. - Tristan


Posted:
Wednesday, December 16, 2009 6:48 AM
by
wrdblog |

7 Comments

Filed under: developer, Word 2010







Quick Co-Authoring Video



A few weeks back we talked about co-authoring in pretty good depth (Word: Co-authoring – Where we are Coming From & Word: Co-authoring (i.e. Simultaneous Editing) in Word 2010).
If you want something a bit more high-level that covers co-authoring
in not only Word, but also in PowerPoint and OneNote 2010 here's a
three minute overview video.