Troubleshooting Word Automation Services
Applies to: SharePoint Server 2010
This topic provides basic information about how Word Automation Services document conversions fail as well as general guidance for handling those failures in your custom application.
Troubleshooting Word Automation Services
How File Conversions Fail
Word Automation Services can fail for several reasons. When the service is healthy, the most common reasons for a failed conversion are as follows:
The file type is intentionally blocked by the administrator (using the SharePoint Server 2010 Central Administration web site).
The file is password-protected or requires Information Rights Management (IRM) permissions in order to be viewed.
The file type is not supported by this version of Word Automation Services. The service does not support converting documents created by using Preview versions of Word before Word 2010.
The user who submitted the conversion job had insufficient permissions to read or write to the source or destination location of the conversion.
In each case, the end user can to act to correct the cause of the failure. Ideally, a solution that uses the Word Automation Services object model should present error messages to the end user when reporting that a conversion item did not convert. The error messages educate the end user why the file did not convert and what action to take for Word Automation Services to successfully convert the file.
Another less common reason for conversion failure is because the file is corrupt. This type of failure can result in a variety of outcomes: some files will simply fail to open; some files might open but fail to convert; other files might start to open and cause the conversion process to fail or stop responding. If this occurs, the conversion process is restarted and the file that caused the process to fail or stop responding is marked as a failed conversion item.
Corrupt files can often be repaired by opening and resaving the file in the client version of Word (Word Automation Services does not support any form of file repair). Once this is done, the file can be resubmitted to Word Automation Services for conversion.
In addition, system failures might occur which in turn could cause multiple conversion item failures. When this occurs, Word Automation Services is in an unhealthy state and the system administrator should take immediate action.
How Solutions Should Handle Failed Conversions
When a conversion fails for any reason, the ErrorMessage property of the conversion item can be queried using the object model. This information can then be presented to the user so that they know why and how the failure occurred and, if possible, what can be done to correct the problem. Every known failure condition that can lead to a failed conversion has a corresponding message. When a failure cannot be resolved by an end user (for example, the Microsoft SQL Server database has become unreachable), the message directs the end user to contact his or her system administrator.
The ErrorMessage property returns a string that can be localized to the browser language of the user. If the proper language pack is not installed on the Web front end that is serving the user then the default language for the SharePoint Server 2010 installation is used. The following is an example of a Word Automation Services error message:
“The file could not be converted; it may be corrupt or otherwise invalid. Try opening the file in Microsoft Word, resaving it, and then resubmitting the file for conversion. If this does not resolve the issue, contact your system administrator.”
An ErrorMessage is stored as a unique integer-based Error Message Code in the document queue. Error Message Codes are used in combination with the browser culture setting to determine the proper localized string to return at runtime. An Error Message Code can be determined programmatically using the ErrorCode property. It is recommended that custom applications include the error code along with the error message when alerting end users of an error event. The following is an example of an error message with the error code included:
“The file could not be converted; it may be corrupt or otherwise invalid. Please try opening the file in Microsoft Word, resaving it, and then resubmitting the file for conversion. If this does not resolve the issue, contact your system administrator. (ErrorCode: 131174)”
System administrators can use the error code to search for troubleshooting information specific to the error condition.