Word Automation Services Object Model
Applies to: SharePoint Server 2010
In this topic, you will learn about the primary objects that you use when you develop with Word Automation Services.
Overview
The programming model for Word Automation Services provides a server-side object model that applications use to request conversions asynchronously by performing the following actions:
Specify the service application that performs the conversion.
Set the required and optional properties for this group of conversions.
Specify one or more files to convert.
Submit the conversion to the document queue.
Once the application submits the conversion request, the service automatically uses a first in, first out (FIFO) queue to start those conversions, based on the schedule that is set for the service application. Each conversion request also specifies a GUID that you can use to query status information about that conversion request.
Creating a Conversion Job
To convert files using Word Automation Services, the object model uses the ConversionJob object to track a set of conversions as a single unit. For example, converting 15 files to PDF format and 30 files to XPS format requires two ConversionJob objects; one for each set of conversions with the same properties.
To initialize the ConversionJob object, the code requires a single parameter that specifies the name, the ID, or the service application proxy that corresponds to the service application. Generally, the name of the service application, which is specified when it is created, is the simplest to use.
Once a ConversionJob object has been created, it is assigned a unique ID. The ConversionJob object exposes this ID through its JobId property, which makes it possible to query the conversion job after it has been submitted.
Configuring Settings
Once you create a ConversionJob object, you can use several settings on the ConversionJob to specify how you want the conversions performed.
The most important of these settings is the UserToken property, which determines the user credentials that are used to access documents to convert and to write documents back to the SharePoint Server 2010 list. By default, anonymous access is used. As a best practice, assign the credentials of the user who submits the conversion job to the UserToken property in order to ensure that the documents are converted successfully.
In addition to the UserToken property, the Settings property contains a collection of other conversion settings. That collection includes settings that specify:
Whether fields should be updated automatically or not.
Whether output files should automatically overwrite existing files.
The output file format.
Monitoring Progress
Once a job has been submitted, it is processed asynchronously in the order that it was added to the document queue. However, you can monitor conversion jobs at any time by using the methods available on the ConversionJobStatus object:
The GetAllJobs(String, Nullable<Guid>) method returns the IDs for all of the conversion jobs for a specific instance of the service (again, filtered by instance name, ID, or proxy), which can then be optionally filtered to those jobs submitted by a specific user.
The GetAllActiveJobs(String, Nullable<Guid>) method returns the IDs for all of the conversion jobs for a specific instance of the service for which one or more items have yet to be processed (again, filtered by instance name, ID, or proxy), which can then be optionally filtered to those jobs submitted by a specific user.
At the conversion job level, you can create the ConversionJobStatus object for a specific job by using its ID (obtained from the methods above, or from a knowledge of the ID from the job creation). This object contains a list of all conversion items that have succeeded, failed, or are yet to be processed.