Document Conversions

  • Article

Hi everyone, Brandon Taylor here from the Document Lifecycle team. In a previous post, George described how to use Smart Client Authoring to convert documents to web pages. In order to use that feature, you need to enable document conversions in your environment.

Setting up this feature in a farm environment involves some amount of planning and setup. The process here has changed somewhat since Beta2 and Beta2 TR. While we're working on the full documentation, this post will help walk you through that planning and setup and get you unblocked from trying out and using document conversions in your farm environment right away.

Review of the Document Conversions Feature

First, let's talk about document conversions and how they work. Office SharePoint Server supports installing executables on the server that transform documents from one format to another. Conversions can be run either from the user interface or programmatically, such as from a custom workflow. The relationship between source documents and their transformed counterparts is maintained.

The primary infrastructure for conversions includes two components:

  • The Document Conversions Load Balancer, which manages the availability of document converters.
  • The Document Conversions Launcher, which launches document conversions on an application server.

Each component is run as a service in the SharePoint environment and the Load Balancer and Launcher must be available for conversions to work. When installed in a farm environment, both services should be enabled on application servers in the farm. For example, you may have one server running both a Load Balancer and Launcher service. Or, you could have one server running a Load Balancer service and one or more servers running a Launcher service.

As a first step, you'll want to think about what server, or servers, will run the Load Balancer and Launcher services. You may not wish to run these services on the same application server that is also doing a lot of processing for other services, such as Excel Services or Search. Similarly, if you expect that your environment will need to serve a lot of document conversions, you may wish to run the Launcher service on multiple servers, to allow for load balancing.

The following diagrams show a sample topology, with document conversions enabled. The first image shows how document conversion works, from the time the conversion is initiated to the time the conversion is done. The second image shows how multiple servers can be devoted to document conversion, if the load demands it. As a rule, each Web application can communicate with a single Load Balancer and a Load Balancer can balance conversions across as many Launcher servers as there are available.

To be available to users, a converter must be installed on the server farm and then enabled by a server administrator. After a converter is enabled for a server, it is available to run on source documents on that server.

Farm Configuration

Once you've decided what server or servers you want to run the Load Balancer and Launcher services, you'll need to configure your farm appropriately. A farm configuration is different from single-box installations, because certain services are disabled by default or cannot be used in that configuration.

The Document Conversions Launcher Service Admin UI is available for any server that is hosting the Central Administration web application. In general, most servers in a farm installation won't be running the Central Administration web application. For these servers, the services UI will not reflect the current state of the services for Document Conversions. For example, the Conversions Launcher Service will always be in a "starting" state in the services on the farm page.

To enable the Launcher Service, you must specify the necessary Launcher information that the UI normally provides. Keep in mind that by doing the below, you're effectively superseding the Central Administration Services UI, so you'll want to do the below on every server that you want to run the Launcher service on.

Ports

If you have more than one server you will need to determine which ports to use for the launcher services. Of course, you will want to make sure those ports aren't being used by anything else. To check, start the Load Balancer service and see what port it's on (this port will be used a little later). To determine the current port being used, go to the registry on the Load Balancer server and check and record the port value in the following key:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office Server\12.0\LoadBalancerSettings]

The default port is 8093.

Registry Settings

Configuring the Launcher settings in the registry is done by updating two values in a registry key located on the server on which you want to run the Launcher service. You want to configure the location of the Load Balancer and the Port to use for the connection. First, find the following key:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office Server\12.0\LauncherSettings]

Then, specify the following for this key:

LoadBalancerUrl=https://server:port/HtmlTrLoadBalancer

Port=dword:portm

Here's what these values mean:

LoadBalancerUrl: This is the full URL to the .NET Remoting channel that the Load Balancer opens. The scheme should be:

https://[ Load Balancer server]:[ Load Balancer port from above]/HtmlTrLoadBalancer

Port: This is the port that the launcher service will open for incoming .NET Remoting requests to do Conversions. The default is 8082.

Managing Multiple IP Addresses

If your server has multiple IP addresses (for example, as a result of having multiple network cards), you may see the following error in the ULS logs for servers running the service:

Event Type: Error

Event Source: Office SharePoint Server

Event Category: [Launcher Service or Load Balancer Service]

Event ID: [6062 or 0000]

Date: [date]

Time: [time]

User: N/A

Computer: [computer name]

Description: Found n valid ip addresses for this machine. Choosing this one: nnn.nnn.nnn.nnn

To fix this you will want to configure the Launcher or Load Balancer service to only listen on the IP address that can be used by the rest of the farm. The Launcher services must be able to communicate with the Load Balancer service, therefore you need to make sure the Load Balancer service opens the communication channel on the IP address that the servers running the Launcher service can use. The best way to determine the IP address to use is to ping the server running the Load Balancer service from the server running the Launcher Service and note which IP address is used in the ping.

You can set the IP address for the service to use in the service .config file, which is located in the same location as the service executable. For example, if the Launcher service executable is in Program Files\Microsoft Office Server\12.0\Bin\Microsoft.Office.Server.Conversions.Launcher.exe, then the .config file would be Program Files\Microsoft Office Server\12.0\Bin\Microsoft.Office.Server.Conversions.Launcher.exe.config.

You will want to update the keyIPExclude key in the appropriate .config file to exclude all incorrect IP addresses. The value of the key is a regular expression that is compared against all IP Addresses. Any that match are not used. If you want to specify the IP address to use, make the regular expression filter out everything except that IP address. There are three possible states as a result:

  • 0 left -- an error is logged
  • >1 -- the above error (6062) is logged
  • Exactly 1 – this IP is used

This key works for both IPv4 and IPv6.

For further information on .NET Regular Expressions, look here for the MSDN documentation.

Restart Services

After changing these settings, you must stop and start the Launcher service (Office Document Conversions Launcher Service) in the Services control panel (Start|Control Panel|Administrative Tools|Services). The services should be set to "Enabled" and set to start automatically (Automatic). If you modified the .config file for the load balancer, you will need to stop and start the Office Document Conversions Load Balancer service as well.

At this point, your services should be running, and you can now enable Document Conversions in Central Admin, and use features like Smart Client Authoring!

Notes

Any future changes to the Load Balancer settings (such as port or server) will require updating the Launcher settings on each server to reflect those changes. The services will also have to be stopped and then started again to pick up the new changes once updated.

Also, as a reference, you can find more information about document conversions in MSDN and TechNet here:

Hopefully these instructions will help those who want to enable document conversions on their farm environments. I welcome comments and questions!

--Brandon Taylor, Program Manager