Date

27-02-2014

Word Automation Services is a little-known but powerful feature of SharePoint 2010 that allows unattended document conversion (into PDF, no less!) on the SharePoint server.

In this Diversus Deep-Dive, we show you how to set up Word Automation Services on your SharePoint 2010 installation, how to call it from code and how to troubleshoot when things go wobbly.

How it works

Word Automation Services is a SharePoint 2010 service application must be enabled explicitly on a SharePoint farm.

Once the service application has been configured, it uses a timer job to kick off the conversion process. The conversion process takes a source file that lives in a document library on the SharePoint server, converts it the specified format and saves the file into a specified document library location on the server. It is important to remember that:

  • The conversion job is not on demand. The conversion job only runs when the timer job is invoked by the system.
  • The job only accepts files that are saved in a SharePoint 2010 document library.
  • The job can only save converted files into a SharePoint 2010 document library.

The basic premise to call Word Automation Services is to specify and start a conversion job. The job has parameters to specify the source file and destination file and desired conversion format, amongst other things.

Prerequisites

You’ll need to be aware that Word Automation Services is not available in SharePoint Foundation.

Therefore, the only pre-requisite here is that you have a SharePoint 2010 Standard or Enterprise Edition installation.

You’ll also need a Microsoft SQL Server instance running, although this is a given with your SharePoint server installation.

Setting Up Word Automation Services

Word Automation Services is a service application in SharePoint 2010, therefore you’ll need to configure it in SharePoint Central Administration using an administrator account.

  1. Navigate to Central Administration.
  2. Click on Application Management.
  3. Click on Manage Service Applications.
  4. If you don’t see Word Automation Services in the list of applications, you’ll need to create a new instance of the application.
  5. Click New.
  6. Click Word Automation Services.
  7. Enter a name for your service application.
  8. Specify an application pool for your application instance.
    NB: To isolate the application instance, you’ll need to have created an application pool in IIS. This can lead to some problems, especially because the application pool needs to have permission to write to the destination you’ll eventually specify for document conversion jobs. You can specify the SecurityTokenServiceApplicationPool, but this isn’t best practice to give service applications more elevated privileges than required. Proceed with caution!
  9. Click Next.
  10. Specify the database server that that the Word Automation Services database lives on.
  11. Specify a database name for the Word Automation Services database.
  12. Next, it is recommended that you stick with Windows Authentication, although you can specify SQL authentication login details here if you wish.
  13. Click Finish.

SharePoint will finally create the specified database and provision the Word Automation Services for you!

From this point, we need to make sure that the service application is added to the default proxy list and that the application instance is, in fact, turned on.

To add the service application to the default proxy list:

  1. Navigate to Central Administration.
  2. Click on Application Management.
  3. Click Configure Service Application Associations.
  4. Click on default under Application Proxy Group heading.
  5. Ensure Word Automation Services is checked.

To start the service application:

  1. Navigate to Central Administration.
  2. Click on Application Management.
  3. Click Manage Services on Server.
  4. Ensure Word Automation Services is started. If not, click Start to start the service application.

You can check that the Word Automation Services Timer Job actually exists and is running on a schedule. To do this:

  1. Navigate to Central Administration.
  2. Click on Monitoring.
  3. Click Review Job Definitions under the Timer Jobs heading.
  4. Ensure you can see Word Automation Services Timer Job in the list.

Configuring Word Automation Services

It is possible to configure Word Automation Services to dictate the amount of resources that it uses on your SharePoint server. To configure the service:

  1. Navigate to Central Administration.
  2. Click on Application Management.
  3. Click Manage Services Applications.
  4. Click Word Automation Services.

Configuring the percentage of memory, conversion process and number of conversions to start will change the performance characteristics of the service application and, in turn, will affect your overall server performance.

Microsoft makes the following recommendations:

  • Set the number of conversion processes to a maximum of the number of CPU cores on the server minus one.
  • Set the number of document conversions per process per minute to a maximum of 90.

Calling Word Automation Services from Code

Once you have set up and configured Word Automation Services on your SharePoint server, you can call this code.

It’s a fairly simple structure:

string siteUrl = "http://testspserver"; // URL of SharePoint site
string sourceDoc = String.concat(siteUrl, "/Shared%20Documents/Test.docx"); // Location of the source file you wish to convert
string destDoc = String.concat(siteUrl, "/Shared%20Documents/Test.pdf"); // Destination of the converted file
string wordAutomationServiceName = "Word Automation Services"; // Name you gave to the Word Automation Services application
var conversionJobId = Guid.Empty;
        using (SPSite spSite = new SPSite(siteUrl))
        {
            ConversionJob job = new ConversionJob(wordAutomationServiceName);
            job.Name = "Test Conversion Job";
            job.UserToken = spSite.UserToken;
            job.Settings.OutputFormat = SaveFormat.PDF;
            job.AddFile(sourceDoc, destDoc);
            job.Start();
            conversionJobId = job.JobId;
        }

It’s important to keep in mind that this is not an on-demand job. Calling job.Start() only pushes the conversion job onto the job queue – the conversion will not happen until Word Automation Services Timer Job is actually run, either by schedule or by invoking the timer job to run programmatically. Once the job has been added, you can use the JobID to query the job status to find out whether or not your conversion job has completed.

Troubleshooting

Have you called Word Automation Services from code or script and the converted document hasn’t ended up in the right place? Here are some pointers and steps to help you troubleshoot:

  • Handle your exceptions (which you should be doing anyway!) – exceptions can be thrown most commonly when calling job.Start(). At the very least, check the Event Viewer to see if your code has thrown an unhandled exception – you should be able to get more detail about why your code failed from here.
  • Ensure the Word Automation Services Timer Job has actually run when you expected it to. NB: There are situations where clicking on the Run Now button doesn’t run the timer job straight away or even at all. This could be due to a combination of factors like current server load, but you need to check last run time to ensure the job actually ran.
  • Check that the conversion job did not fail. Follow these steps to do so:
  1. On the database server where the Word Automation Services database lives, open a new SQL Server Management Studio instance and set the active database.
  2. Run the following query:

    SELECT * FROM Items
  3. On the row which corresponds to your conversion job, check that the ErrorCode column is NULL. If it has a numerical value, this means that the job failed, and you’ll have to look up the error code to find out what went wrong. Helpfully, Microsoft publishes a list of error codes here.
  • Check that the conversion job was logged in the Word Automation Services database. Follow these steps to do so:
  1. On the database server where the Word Automation Services database lives, open a new SQL Server Management Studio instance and set the active database.
  2. Run the following query:
 SELECT *
 FROM Jobs
 WHERE Name = <Name given to conversion job>

If your job is not in the list, you should check:

  • The Word Automation Services application has been added to the default proxy group
  • The Word Automation Services application has been started
  • The application pool account of the service application has access to the Word Automation Services database

We hope this Diversus deep-dive has been helpful in giving you a technical overview of all things Word Automation Services.

More information can be found here:

Word Automation Services in SharePoint Server 2010
Developing with SharePoint 2010 Word Automation Services
Troubleshooting Word Automation Services