The Fabasoft Folio Conversion Service is based on the Fabasoft Folio Web Service. The conversion of documents is implemented as an XML web service. Other Fabasoft Folio Web Services may use that conversion service for converting documents.
The Fabasoft Folio Conversion Service hosts third-party software tools required for converting documents. Microsoft Office Word for example is used to convert Microsoft Office Word documents to HTML documents. Usually it is not possible to run Microsoft Office Word within a web service. It is designed as a client application only. Supposing special conditions, it is possible to run such applications within a service (see Microsoft Knowledge Base Article - 257757).
The Fabasoft Folio Conversion Service provides an infrastructure for client applications to be executed in a service environment. For example, the applications are started and invoked in the security context of the Fabasoft Folio Conversion Service account and not in the requesting client’s security context. This is necessary for the Microsoft Office applications that rely on a user profile.
Another important aspect is to cache these applications. This results in a significant performance gain. The caching mechanism can be controlled by defining the maximum number of instances and the maximum run time of a pooled application. This allows for avoiding known memory leaks or stability issues. The conversion service also checks whether a pooled application is responding. If not, the application will be restarted automatically.
If the application pool identity of the Fabasoft Folio Conversion Service is configured as a domain user and Integrated Microsoft Windows Authentication should be used, some extra tasks have to be performed to enable the Kerberos authentication protocol (see Microsoft Knowledge Base Article - 832769):
Note: Use “Basic Authentication” for the Fabasoft Folio Conversion Service to avoid these critical administrative measures. See chapter “Kerberos Authentication Issues” for details.
On the Fabasoft Folio Conversion Server, log on as the user specified in the Fabasoft Folio Web Service setup. Adjust the regional settings as required. This setting will have an effect on how some kinds of information (date, currency etc.) are displayed in the converted documents.
To install and configure Microsoft Office for converting documents and to grant launch and access permissions for Microsoft Office applications to the Fabasoft Folio Web Service user account, perform the following steps:
On the Fabasoft Folio Conversion Server, log on as the user specified in the Fabasoft Folio Web Service setup.
Install Microsoft Office
Adjust the DCOM security settings for Microsoft Office applications
To install and configure Adobe Acrobat Pro for converting documents, perform the following steps:
On the Fabasoft Folio Conversion Server log on as the user specified in the Fabasoft Folio Web Service setup.
Install Adobe Acrobat Professional
Install Adobe Acrobat Pro by executing the installation file.
Adjust Acrobat Distiller
To install and configure Ghostscript for converting documents, perform the following steps:
On the Fabasoft Folio Conversion Server log on as the user specified in the Fabasoft Folio Web Service setup.
Configure PDF/A Conversion with Ghostscript
The following steps are only necessary if you want to convert documents to PDF/A file format.
The following steps are necessary if you want to convert video contents.
The following steps are necessary if image properties should be available.
The following step is only required if Perl is not already installed on your system:
To install and configure LibreOffice for converting documents, perform the following steps:
On the Fabasoft Folio Conversion Server log on as the user specified in the Fabasoft Folio Web Service setup.
Setting the environment variable
After finishing the installation, the LibreOffice installation path has to be specified in the environment variable PATH, otherwise the conversion fails.
Example: PATH=<existing path>;<libreoffice-directory>\program
Setting the registry key
In order that conversion works, after rebooting the computer the following registry key has to be set:
REG_SZ LibreOfficeConversionKey = <libreoffice-directory>\program\soffice.exe -headless -nofirststartwizard -norestore -invisible -accept=socket,host=localhost,port=8100;urp
Adobe Acrobat Distiller and LibreOffice have to be started explicitly on the Fabasoft Folio Conversion Server. All other conversion tools are started automatically.
Execute the acrobat.exe file. Then Adobe Acrobat Distiller is polling the configured “watched folder”.
Verify that LibreOffice is not already running (soffice.exe process in the process manager). In a command line interface, switch to the LibreOffice installation directory and enter the following command:
soffice -headless -accept=socket,host=localhost,port=8100;urp
Thus LibreOffice is running as a service and is able to receive requests on IP port 8100. Several instances LibreOffice may be started, each of them listening on a unique IP port.
Note: Be sure to use the same port numbers as configured in the Tools Host configuration (see chapter “Configuring a Fabasoft Folio Conversion Service”).
The user account which is used to run Fabasoft Folio Conversion Services must be a member of the group “Print Operators”.
For software requirements and prerequisites see chapter “Requirements for Installing Fabasoft Folio Conversion Services” and chapter “Prerequisites for Fabasoft Folio Conversion Services”.
Note: The machine that hosts the Fabasoft Folio Conversion Service should be a machine that is dedicated for conversion purposes only. If this installation is also used as a regular Fabasoft Folio Web Service, serious problems may be encountered (see chapter “Simultaneous Use as a Regular Web Service” for details).
To install Fabasoft Folio Conversion Services via the automated setup, perform the following steps.
Open a Fabasoft Folio Web Client, navigate to the Domain Administration and click the “Configuration Objects” tab. There are three configuration objects that contain configuration data for the Fabasoft Folio Conversion Service:
The Tools Host software component manages conversion tools that support the Microsoft OLE Automation interface. It provides the infrastructure for client applications to run in a server environment. The default settings should be sufficient in most cases.
The FSCTLH@1.1001:StdOleAutomationHostconfiguration object lists the available conversion tools. The following applications are configured by default:
The Tool Configuration compound property specifies parameters used for managing the configured application:
OLE Automation Server
Specifies the ProgID or ClassID of the OLE Automation server (e.g. “Word.Application”).
Specifies an OLE Automation Dispatch Identifier (DISPID) of a test function. This function will be called when checking if the application is still alive. Usually this is a function that reads a global property, for example the version number of the application.
Specifies an OLE Automation Dispatch Identifier (DISPID) of a function that terminates the application.
Restart after (Calls)
Specifies the maximum number of uses of the application. The current instance will exit and a new instance of the application will be created when exceeding this limit.
Maximum life time (in seconds)
Specifies the maximum lifetime of an application. The current instance will exit and a new instance of the application will be created when this limit is exceeded.
Monitoring time interval (in seconds)
If the tool has a separate process, then this process can be monitored. This attribute defines a time interval for calculating average CPU utilization.
Maximum CPU utilization (in percent)
The maximum CPU utilization of the process associated with the tool. If the monitored value exceeds this configured value then the process will be terminated.
Wait time for graceful process termination (in seconds)
The associated process of a tool should terminate automatically when it is no longer in use. To avoid hanging tool processes specify a time interval within which the process can terminate automatically. If the specified amount of time is exceeded, the process will be terminated.
This field is used when adding new applications to the Tools Host configuration object. Specify a software component if the settings should be kept after updating.
To ensure optimal stability, the reuse of instances is deactivated by default. Therefore, no applications are cached after they have been used in conversion operations. To speed up the conversion significantly the Restart after (Calls) value has to be increased. The Tools Host invokes the specified test function to determine if the application is still alive and responding. The Restart after (Calls) and Maximum life time (in seconds) fields are maximum thresholds for application usage. This helps to avoid known memory leaks and stability problems.
Sometimes, a process of a conversion tool crashes and is caught in an endless-loop. The Tools Host component is able to handle such situations.
The Monitoring time interval (in seconds) and Maximum CPU utilization (in percent) settings of the Tool Configuration compound property define additional conditions for tools that have separate processes. If a process exceeds the configured threshold value, it will be terminated and a Microsoft Windows event log is written to denote failure of the tool.
The average CPU utilization of the conversion tool processes also can be traced. If the HKEY_LOCAL_MACHINE\SOFTWARE\Fabasoft\FSCTLH@1.1001 registry key contains the named REG_DWORD-value TraceWatchedProcesses and its value is set to “1”, then the currently used conversion processes are traced to the Fabasoft DUCX Tracer. This may be useful for determining an appropriate threshold value for the Maximum CPU utilization (in percent) for a specific conversion tool.
A conversion tool may not be able to continue when it is displaying a modal dialogue box. The configuration object FSCTLH@1.1001:StdOleAutomationHost provides a list of window descriptions of potential blocking windows (FSCTLH@1.1001:blockingwindows property). The boxes of the aggregate Blocking windows describe a window:
Title of the window
Class name of the window
Style flags of the window
File name of the window process
This field is used when adding new entries to this compound property. Specify a software component if the settings should be kept after updating.
All windows in the invisible web service desktop are compared to the values specified in the fields of this compound property. The fields are linked together using a logical AND operator. If a field is omitted it will not be taken into account when detecting a window.
The detection of potential blocking dialogue boxes is done at regular intervals. The Polling frequency for detecting blocking windows (in seconds) property (FSCTLH@1.1001:blockingwindowspollinginterval) specifies this interval. In this field a value greater than zero must be typed in order to take effect, otherwise no detection will occur.
A Microsoft Windows event log will be generated if a blocking dialogue box has been detected and closed. The event log contains the window title, window class, style flags, window process, and a list of the controls within this window so that the reason for the failed conversion can be identified.
The tools host state report contains a list of currently open windows (see chapter “Tools Host State”). This is very helpful when encountering a hanging conversion operation and suspecting a blocking dialogue box. The window descriptions written to the state report may be taken to the Blocking windows aggregate of the Tools Host configuration object.
Be careful when extending the Blocking windows compound property. It may lead to unexpected side effects if an added entry identifies a normal window instead of a blocking dialogue box.
The maximal conversion duration can be configured via the property Conversion Timeout (in Seconds) (FSCTLH@1.1001:conversiontimeout). The limit will be enforced using Microsoft Office or LibreOffice as external conversion tool. If the timeout is expired the conversion will be cancelled.
The configuration object FSCCONV@1.1001:ExternalConversionConfiguration contains the supported document formats and additional parameters needed for the conversion operations.
The supported document format conversions are described in the Conversion table field. One line in this compound property defines a single conversion step. It consists of the following fields:
Source types separated by a semicolon.
Destination types separated by a semicolon.
Priority of the current aggregate line. It is possible to have different implementations for the same document format. In this case the row with the highest priority (lowest number) will be selected.
The conversion request will be passed to the specified action.
Check conversion action
Validation action for checking the conversion operation. Checks the availability of required tools and configuration.
ProgID or ClassID of an application that supports the Microsoft OLE Automation interface (IDispatch).
Name of the printer when using printer-based conversions (e.g. PDF conversion).
Specifies the web service end-point(s) of remote conversion services. If this box is empty or in the specified web service object no URL is specified then the conversion takes place locally.
Helps to preserve configured values beyond updates.
A conversion can also be “multi-staged”. The shortest way from the source type to the destination type will be found automatically using Dijkstra’s “single source - shortest path“ algorithm.
Example: A Microsoft Office Word document should be converted to a PDF document and the conversion configuration has the following settings:
Use activePDF for PDF generation.
Use Microsoft Office Word and the Adobe Acrobat Distiller printer driver to create a postscript file.
Use Adobe Acrobat Distiller to convert a postscript file to PDF.
Use Ghostscript to convert a postscript file to PDF.
In this example the conversion from Microsoft Office Word format (“doc”) to PDF format is done in two steps (doc ps, pspdf), because it is less expensive than using the direct conversion (40 + 35 < 100).
The configuration object FSCCONV@1.1001:ExternalConversionConfiguration is already populated with default values for HTML and PDF conversions. Ghostscript is the default application for creating PDF documents.
The Content Converter component is also able to do conversions by executing command lines. The conversion configuration can be extended by adding the FSCCONV@1.1001:CmdLineConvert action. The printer field is used to configure the command line. It contains place holders for input and output files.
Example: “fop.bat -opt <~src~><~dest~>”
The configuration object Default Web Services (FSCCONV@1.1001:DefaultWebServices) stores end-points for remote web services. By default, all conversion formats that require a remote web service reference the Default Web Services object.
Create new web service objects that contain other end-points. By assigning different web service objects to conversion formats in the main conversion configuration, server affinity can be achieved: certain document formats will be converted on dedicated conversion servers.
The Default Web Services object and other instances of the FSCOWS@1.1001:HttpConnectors represent abstract endpoints for remote web services.
The concrete connection information for each FSCOWS@1.1001:HttpConnectors instance is defined via the "HTTP Connectors" list within the Local Web Service Configuration. This configuration is accessible within the Domain's settings on the page "Components Configuration" in the field "Web Service". The following settings are available:
Specifies the URL of the remote conversion service. The syntax is http://<webserver>/<vdir>.
Basic Authentication only: user name
Basic Authentication only: user password
Basic Authentication only: user name for proxy authentication
Basic Authentication only: user password for proxy
Client certificate for HTTPS connections (SSL). The certificate must be located in the local machine store.
Helps to preserve configured values after updating.
If no values are defined in this compound property conversion takes place on the local kernel. In most cases this is no appropriate solution. The conversion tools would be activated and invoked on the local machine using the security context of the client user. This is not applicable for Fabasoft Folio/Web with a potentially high number of Fabasoft Folio Web Clients. As a result, the conversion tools (e.g. Microsoft Office) would have to be installed and configured for each client user on the Fabasoft Folio Web Server.
If one or more connection entries are specified for the Default Web Services configuration object then the conversion operations will be executed on these web services. The conversion tools are invoked in the security context of the web service user of the remote web service. This is the user account that has been specified during the installation of the remote conversion service.
If there are multiple entries for the Default Web Services configuration object then a simple load-balancing algorithm is used to select an appropriate end-point. This algorithm keeps records of response times and throughput for each conversion service. This statistical information forms the basis for choosing a web service end-point on a subsequent conversion request.
All essential input and output parameters of a conversion operation can be logged to the file system. Two kinds of logging modes are available: the conversion service logging mode and the web service logging mode.
The conversion service logging mode can be enabled by creating the following registry key:
Furthermore, the named values LogDetailFolder and LogDetailCount need to be created within this key. The REG_SZ value LogDetailFolder specifies an existing directory on the file system for storing the logging information. The REG_DWORD value LogDetailCount specifies the maximum number of logging entries to be made. This value is decremented each time a conversion operation is logged. If the counter reaches zero, logging will be disabled.
REG_SZ LogDetailFolder = “C:\Temp\fscconv”
REG_DWORD LogDetailCount = 10
The web service logging mode is similar to the conversion service logging mode. It can be enabled by creating the following registry key:
REG_SZ LogDetailFolder = <destinationfolder>
REG_DWORD LogDetailCount = <maximum number of logs>
Note: The Fabasoft Folio Conversion Service is implemented as a web service. Hence, each conversion corresponds to a SOAP request.
State and statistical information about the tools host on the conversion server can be queried using the FSCTLH@1.1001:GetStateReport action. Such a report is available in an XML or HTML format and contains the following information:
Call the FSCTLH@1.1001:GetStateReport action via a HTTP/GET request using a web browser. The URL would be as follows:
The Fabasoft Folio Conversion Service has to be configured according to the system and the conversion tools used.
To specify the connection information for the Fabasoft Folio Conversion Service, perform the following steps:
If Adobe Acrobat Distiller is used as PDF generator, a watched folder has to be configured. Perform the following steps:
The pre-defined size of the printer pool is 8, which should be sufficient for most cases. To change this setting, perform the following steps:
If LibreOffice is used as PDF generator, perform the following steps to customize the FSCTLH@1.1001:StdOleAutomationHost configuration object:
Additional conversion options can be specified in the registry path HKEY_LOCAL_MACHINE\Software\Fabasoft\FSCCONV@1.1001:
The Fabasoft Folio Conversion Service is implemented as a web service. Fabasoft Folio Web Services use this web service for submitting conversion requests.
The web service definition FSCCONV@1.1001:ConversionService describes a SOAP service that contains the following web methods:
Other (external) applications may also use this web service. The WSDL definition for the conversion service is available via the following URL:
The Fabasoft Folio Conversion Service user account starts external applications using the DCOM interface. Ensure that this user account has permissions to launch the DCOM servers of the conversion tools. Start the dcomcnfg.exe configuration program to modify the security of the DCOM servers. Grant launch permissions for each individual application or for all applications by adjusting the default launch permissions. The initial default launch security includes the following users and groups:
Be careful to check the permissions of each conversion application. If custom permissions are selected, the default launch permissions will have no effect.
A set of conversion applications is already configured in the Tools Host configuration object (FSCTLH@1.1001:StdOleAutomationHost). Launch permissions for the following applications must be granted to the Fabasoft Folio Conversion Service user in order to be used for conversion operations:
Name or AppID
ProgID of COM Server
Microsoft Excel Application
Microsoft Word Document
Microsoft PowerPoint Presentation
Outlook Message Attachment
The Fabasoft Folio Conversion Service must be able to create temporary files. The directory for these temporary files was configured during setup. In order to be able to create temporary files, the Fabasoft Folio Conversion Service user account must have full access to this directory.
Each Fabasoft Folio Web Service instance contains a directory for static web content. This directory will be created and synchronized when the web service starts. Therefore the Fabasoft Folio Web Service user account needs full access to this directory. The default location of this directory is <Program Files>/Fabasoft/Components/Web/<vdir>/ASP/content/tmp, where the first part of the path (till <vdir>) specifies the physical location of the installed virtual directory.
Note: The Fabasoft Folio Web Service setup program adjusts the security on these directories.
The Microsoft Office applications are installed either per user or per machine, depending on the privilege level of the user who installs or accesses these applications. If an administrative user starts a Microsoft Office application then the installation configuration is managed per machine. Otherwise, the installation configuration is stored per user in the user profile. Install Microsoft Office as an administrator of the local machine to ensure these applications are available for all users of the machine.
As most client applications, Microsoft Office relies on a user profile. Hence, the Fabasoft Folio Conversion Service loads a user profile before it uses these applications. This operation requires administrative privileges. For this reason the Fabasoft Folio Conversion Service user account must be a member of the local administrator group.
Note: The conversion is done using the macro security settings of the user who runs the Fabasoft Folio Conversion Service.
Final form views of file objects are created using templates, which contain Fabasoft DUCX Expressions for the content parts to be assembled. The evaluation operations are invoked in the security context of the configured Fabasoft Folio Conversion Service account. Thus this user account must have the appropriate permissions to read attributes and contents referenced by these Fabasoft DUCX Expressions.
It is highly recommended that the Fabasoft DUCX Expressions in the final form template are designed independently of the permissions of the Fabasoft Folio Conversion Service user account. Pass a “global scope dictionary” to the FSCCONV@1.1001:Convert action. This dictionary may contain any user related objects and attributes referenced by Fabasoft DUCX Expressions evaluated by the Fabasoft Folio Conversion Service.
Each client user that utilizes the Fabasoft Folio Conversion Service indirectly uses the conversion tools (Microsoft Office, Adobe Acrobat Distiller, activePDF). The license requirements for the conversion tools are as follows:
If problems occur when converting documents, take a look at the Microsoft Windows Event Viewer on both, the Fabasoft Folio Web Server and the Fabasoft Folio Conversion Server. In many cases the source of the problem can be found by viewing these log data.
If the password for the web service user is changed, also the identity of the web service application pool has to be reconfigured. This can be done in the “Internet Services Manager” (“Start” > “Programs” > “Administrative Tools” > “Internet Services Manager”).
For the Fabasoft Folio Web Service user account some security settings are required. If the identity of the Fabasoft Folio Web Service is changed, consider the following:
The Fabasoft Folio Web Client does not communicate directly with the Fabasoft Folio Conversion Server. Server/server communication is implemented.
The XMLHTTP object of Microsoft XML (based on the Microsoft WinINet API) is used for client/server communications. All internet settings (security, proxy etc.) apply for this mode. However, WinINet is not server-safe. Hence, the ServerXMLHTTP object of Microsoft XML (based on Microsoft WinHTTP) is used for server/server communication.
The Microsoft WinHTTP client HTTP stack does not depend on the WinINet settings. The proxycfg.exe configuration tool is used to set up WinHTTP. For more details see the MSDN library article “How To Use ProxyCfg.exe”.
The configuration object Default Web Services contains time out thresholds among other connection properties. Change these values, if the requirements differ from the default settings.
The Fabasoft Folio Web Service uses Microsoft WinHTTP to communicate with the Fabasoft Folio Conversion Service. The supported versions are Microsoft WinHTTP 5.0 (winhttp5.dll) and Microsoft WinHTTP 5.1 (winhttp.dll), whereas version 5.1 is preferred.
Loading the operating system component Microsoft WinHTTP 5.0 will fail if more than 63 thread-local-storage (TLS) slots have already been allocated. The “Error in the DLL (0x800401F9)” error message is displayed. Typically this error occurs when the Fabasoft Folio Web Service tries to connect to the conversion service after it has been running for a long time while doing certain kinds of operations. This issue has been fixed in Microsoft WinHTTP 5.1.
By default, Kerberos authentication cannot be used if the application pool identity of the Fabasoft Folio Conversion Service is configured as domain user. Contacting a Fabasoft Folio Conversion Service would result in a HTTP 401 status code. To solve or work around the problem, the following options are available.
Register a Service Principle Name (SPN) for the domain user account that the application pool is running as. This is the proposed solution according to Microsoft Knowledge Base Article 832769. See chapter “Enable Kerberos Authentication” for details.
On Microsoft Internet Information Service 7.0 following command needs to be executed for each application pool:
c:\Windows\System32\inetsrv>appcmd set config "Default Web Site/fsc" -section:windowsauthentication /useAppPoolCredentials:true
In the “Internet Services Manager” MMC snap-in, disable Integrated Microsoft Windows Authentication for the virtual directory of the Fabasoft Folio Conversion Service.
If a TCP/IP address is configured instead of a NetBIOS name in the connection URL (in the Default Web Services configuration object), the HTTP XMLHTTP/ServerXMLHTTP client implementations will use Basic Authentication.
Configure the application pool identity of the Fabasoft Folio Conversion Service as a local user account.
Configure a local user account in the Default Web Services configuration object.
The usage of a Fabasoft Folio Conversion Service as a regular Fabasoft Folio Web Service may lead to a problem. Reading a certain attribute may trigger a “Get Action” that initiates a conversion request. This request would cause a web service round trip to the local Fabasoft Folio Kernel instance, which results in a dead lock.
Hence, it is recommended to install the Fabasoft Folio Conversion Service on a dedicated machine.
Take into account that transactions cannot be shared between multiple Fabasoft Folio Kernel processes. Objects created in the current transaction do not exist unless the transaction is committed. This may impact the evaluation of Fabasoft DUCX Expressions on the Fabasoft Folio Conversion Server. In this case ensure that the Fabasoft DUCX Expressions within the source template do not depend on the current transaction context.
If the conversion operation returns incorrect documents, enable the conversion logging mode (see chapter “Conversion Service Logging”). The documents stored into the logging directory are very valuable for analyzing the problem.
If conversion fails narrow down the error cause via the tools host status report. It contains occurred errors, pending conversions, statistics, and other information. The tools host status report can be obtained by navigating to the following URL:
Be sure to specify the installation and URE (UNO Runtime Environment) path of LibreOffice in the environment variable PATH. Otherwise conversion fails and the following error message is displayed: “fsccnv.dll not found”.
The standard value for the server-side connection timeout of Microsoft Internet Information Services is set to 120 seconds. This means that if a conversion takes longer than two minutes, the Fabasoft Folio Web Server will cancel the request. Increase this value if longer conversion times are expected.
Be sure that Microsoft Excel can use the printers of the Fabasoft Folio Conversion Service (Fabasoft-CONV-<no>) when running Microsoft Excel in the context of the Fabasoft Folio Conversion Service user. If the printers are not available in Microsoft Excel specify explicit security permissions for the Fabasoft Folio Conversion Service user on the security tab of the printers.
Note that the number of Microsoft Office processes, which can be started and used by the Fabasoft Folio Conversion Service is limited and depends on the system configuration.