Installation and Configuration of Fabasoft Folio Conversion ServicesPermanent link for this heading

OverviewPermanent link for this heading

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.

Installation Tutorial for Third-party ProductsPermanent link for this heading

Enable Kerberos AuthenticationPermanent link for this heading

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):

  1. In a command line interface, type the following command (<FQDNConvMachine> is the fully qualified domain name of the Fabasoft Folio Conversion Server and <ConvUser> is the Fabasoft Folio Domain user account):
    setspn.exe -A HTTP/<FQDNConvMachine><ConvUser>
    Example:
    setspn.exe -A HTTP/convserver.fabasoft.com convserver\convuser
    Important: Use the fully qualified domain name of the Fabasoft Folio Conversion Server, not the NetBIOS name. Make sure that the service principal name is unique.
  2. Reboot the computer that hosts the Fabasoft Folio Conversion Service (required for enabling the Trust this computer for delegation security option).

Note: Use “Basic Authentication” for the Fabasoft Folio Conversion Service to avoid these critical administrative measures. See chapter “Kerberos Authentication Issues” for details.

Adjust the Regional and Language OptionsPermanent link for this heading

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.

Install and Configure Microsoft OfficePermanent link for this heading

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

  1. Perform a full installation of Microsoft Office. Otherwise Microsoft Office may cause the Microsoft Windows Installer service to pop-up an invisible dialogue box for browsing to the Microsoft Windows Installer package during the conversion of a document. As a result, the conversion is stopped and does not respond.
  2. Afterwards start each Microsoft Office application. This initializes the user’s profile for the Microsoft Office applications.
  3. Disable any automatic checks (e.g. automatic field updates or spelling and grammar checks). This will speed up opening and converting documents.

Adjust the DCOM security settings for Microsoft Office applications

  1. Open the “Component Services” MMC snap-in.
  2. Navigate to “Components Services” > “Computers” > “My Computer” > “DCOM Config”.
  3. Grant access and launch permissions to the Fabasoft Folio Web Service user for the DCOM applications “Microsoft Word Document”, “Microsoft Excel Application” and “Microsoft PowerPoint Presentation”.
    Note: The default DCOM security is accessible through the properties of the computer node.

Install and Configure Adobe Acrobat ProPermanent link for this heading

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

  1. Start the application “Acrobat Distiller”.
  2. On the “Settings” menu, click “Watched Folders”.
    Conversion3
  3. Click “Add Folder” to add a local folder to the list, change the Check watched folders every frequency to “1” second, select the Delete output files older than check box and click “OK”.

    Note: If the client version of Adobe Acrobat Distiller is used, the distiller application must be running on the Fabasoft Folio Conversion Server to generate PDF documents. For that purpose you have to log on interactively to the Fabasoft Folio Conversion Server and start the Adobe Acrobat Distiller application. The server version of Adobe Acrobat Distiller does not require this step.

Install and Configure GhostscriptPermanent link for this heading

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.

Install Ghostscript

  1. Download and install the supported Ghostscript version. A repository of all available Ghostscript products can be found under the following link: https://github.com/ArtifexSoftware/ghostpdl-downloads/releases: new window
  2. Install Ghostscript by executing the installation file.

Configure PDF/A Conversion with Ghostscript

The following steps are only necessary if you want to convert documents to PDF/A file format.

  1. Edit the PDFA_def.ps configuration file (<ghostscript-directory>\lib\PDFA_def.ps).
  2. In the /ICCProfile line replace srgb.icc with the path to the ICC file iccprofiles\srgb.icc in the standard Ghostscript installation path: /ICCProfile <ghostscript-directory>\\iccprofiles\\srgb.icc
    Note: Backslashes in the path must be escaped using a backslash.

Install and Configure FFmpegPermanent link for this heading

The following steps are necessary if you want to convert video contents.

  1. Build or download a static build of FFmpeg: http://ffmpeg.org/: new window
  2. Move the static FFmpeg tool to a location which is referenced by the PATH environment variable.

Install and Configure ExifToolPermanent link for this heading

The following steps are necessary if image properties should be available.

  1. Download ExifTool from http://search.cpan.org/dist/Image-ExifTool/: new window.
  2. Extract the file exiftool and the directory lib to the directory where you want to install ExifTool.
  3. Rename exiftool to exiftool.pl.
  4. Add this directory to the PATH environment variable.

The following step is only required if Perl is not already installed on your system:

  1. Download and install StrawberryPerl from http://strawberryperl.com/: new window.

Install and Configure LibreOfficePermanent link for this heading

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.

Install LibreOffice

  1. Download the supported LibreOffice version from the URL http://www.libreoffice.org: new window.
  2. Extract the downloaded ZIP archive and install LibreOffice by executing the installation file. During the setup, select the following options:
    • In the “File Type” dialogue, clear all check boxes to avoid that Microsoft Office documents are automatically opened with LibreOffice. If they are opened with LibreOffice automatically, they are not converted.

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:

[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Run]

REG_SZ LibreOfficeConversionKey = <libreoffice-directory>\program\soffice.exe -headless -nofirststartwizard -norestore -invisible -accept=socket,host=localhost,port=8100;urp

Start Conversion ToolsPermanent link for this heading

Adobe Acrobat Distiller and LibreOffice have to be started explicitly on the Fabasoft Folio Conversion Server. All other conversion tools are started automatically.

Starting Adobe Acrobat DistillerPermanent link for this heading

Execute the acrobat.exe file. Then Adobe Acrobat Distiller is polling the configured “watched folder”.

Starting LibreOfficePermanent link for this heading

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”).

User SettingsPermanent link for this heading

The user account which is used to run Fabasoft Folio Conversion Services must be a member of the group “Print Operators”.

Installation of Fabasoft Folio Conversion ServicesPermanent link for this heading

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.

  1. Insert the Fabasoft product DVD in the DVD drive of your server. The Fabasoft Server Setup dialog will be displayed automatically.
    Note: If this dialog is not displayed automatically, run setup.exe in the root directory of the Fabasoft product DVD.
  2. The installation works as described in chapter “Installation of Fabasoft Folio Web Services”. Only instead of selecting to install Fabasoft Folio Web Services select the Fabasoft Folio Conversion Services check box.

Configuring a Fabasoft Folio Conversion ServicePermanent link for this heading

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:

  • Tools Host Configuration (FSCTLH@1.1001:StdOleAutomationHost)
    This object manages hosting of external applications used for converting documents.
  • Conversion Configuration (FSCCONV@1.1001:ExternalConversionConfguration)
    This object is the main configuration object.
  • Default Web Services (FSCCONV@1.1001:DefaultWebServices)
    This object defines the location of the Fabasoft Folio Conversion Services.

Tools Host ConfigurationPermanent link for this heading

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.

Application ConfigurationPermanent link for this heading

The FSCTLH@1.1001:StdOleAutomationHostconfiguration object lists the available conversion tools. The following applications are configured by default:

  • Microsoft Office Word
  • Microsoft Office Excel
  • Microsoft Office PowerPoint
  • Microsoft Office Outlook

The Tool Configuration compound property specifies parameters used for managing the configured application:

Field

Description

OLE Automation Server

Specifies the ProgID or ClassID of the OLE Automation server (e.g. “Word.Application”).

Test

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.

Quit

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.

Software Component

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.

Detection of Application CrashesPermanent link for this heading

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.

Detection of Blocking WindowsPermanent link for this heading

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:

Field

Description

Window title

Title of the window

Window class

Class name of the window

Window style

Style flags of the window

Window process

File name of the window process

Software Component

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.

Conversion TimeoutPermanent link for this heading

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.

Conversion ConfigurationPermanent link for this heading

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:

Field

Optional

Description

Source Type

No

Source types separated by a semicolon.

Destination Type

No

Destination types separated by a semicolon.

Priority

No

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.

Conversion Action

No

The conversion request will be passed to the specified action.

Check conversion action

Yes

Validation action for checking the conversion operation. Checks the availability of required tools and configuration.

Application ProgID

Yes

ProgID or ClassID of an application that supports the Microsoft OLE Automation interface (IDispatch).

Printer

Yes

Name of the printer when using printer-based conversions (e.g. PDF conversion).

Web Service

Yes

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.

Software Component

Yes

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:

Source Type

Destination Type

Priority

Action

doc

pdf

100

Use activePDF for PDF generation.

doc

ps

40

Use Microsoft Office Word and the Adobe Acrobat Distiller printer driver to create a postscript file.

ps

pdf

40

Use Adobe Acrobat Distiller to convert a postscript file to PDF.

ps

pdf

35

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~>”

Default Web Services ConfigurationPermanent link for this heading

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:

Field

Optional

Description

URL

No

Specifies the URL of the remote conversion service. The syntax is http://<webserver>/<vdir>.

User

Yes

Basic Authentication only: user name

Password

Yes

Basic Authentication only: user password

Proxy User

Yes

Basic Authentication only: user name for proxy authentication

Proxy Password

Yes

Basic Authentication only: user password for proxy

Client Certificate

Yes

Client certificate for HTTPS connections (SSL). The certificate must be located in the local machine store.

Software Component

Yes

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.

Logging ModePermanent link for this heading

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.

Conversion Service LoggingPermanent link for this heading

The conversion service logging mode can be enabled by creating the following registry key:

HKEY_LOCAL_MACHINE\Software\Fabasoft\FSCCONV@1.1001

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.

Example:

[HKEY_LOCAL_MACHINE\Software\Fabasoft\FSCCONV@1.1001]

REG_SZ LogDetailFolder = C:\Temp\fscconv

REG_DWORD LogDetailCount = 10

Web Service LoggingPermanent link for this heading

The web service logging mode is similar to the conversion service logging mode. It can be enabled by creating the following registry key:

[HKEY_LOCAL_MACHINE\Software\Fabasoft\FSCOWS@1.1001]

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.

Tools Host StatePermanent link for this heading

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:

  • System information
    Hardware and software inventory, list of installed conversion tools.
  • Cached tools
    List of conversion tools with current state.
  • Statistics
    Runtime statistics of the conversion operations.
  • Warnings and errors
    List of warnings and errors occurred so far.
  • Detailed history
    List of all events occurred so far.
  • Open windows
    List of open windows and dialogue boxes owned by the conversion tools, very useful for detecting blocking dialogue boxes.

Call the FSCTLH@1.1001:GetStateReport action via a HTTP/GET request using a web browser. The URL would be as follows:

http://<webserver>/<vdir>/tlhstatus

Necessary Configuration StepsPermanent link for this heading

The Fabasoft Folio Conversion Service has to be configured according to the system and the conversion tools used.

Conversion Server URLPermanent link for this heading

To specify the connection information for the Fabasoft Folio Conversion Service, perform the following steps:

  1. Right-click the FSCCONV@1.1001:DefaultWebServices and click “Properties”.
    Note: If the object is opened in read-only mode, click “Edit”.
  2. Enter the connection information for the Fabasoft Folio Conversion Service and click “Next”.

Adobe Acrobat Watched FolderPermanent link for this heading

If Adobe Acrobat Distiller is used as PDF generator, a watched folder has to be configured. Perform the following steps:

  1. Right-click FSCCONV@1.1001:ExternalConversionConfiguration and click “Properties”.
    Note: If the object is opened in read-only mode, click “Edit”.
  2. On the “Conversion Configuration” tab under Acrobat Distiller watched folder specify the “watched folder”, which has already been configured during the configuration of Adobe Acrobat Distiller and click “Next”.

Printer Pool SizePermanent link for this heading

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:

  1. Right-click FSCTLH@1.1001:StdOleAutomationHost and click “Properties”.
    Note: If the object is opened in read-only mode, click “Edit”.
  2. On the “Ole Automation Tools Host Configuration” tab type a size for the printer pool in the Printer Pool Size field and click “Next”.

LibreOffice InstancesPermanent link for this heading

If LibreOffice is used as PDF generator, perform the following steps to customize the FSCTLH@1.1001:StdOleAutomationHost configuration object:

  1. Right-click FSCTLH@1.1001:StdOleAutomationHost and click “Properties”.
    Note: If the object is opened in read-only mode, click “Edit”.
  2. On the “Ole Automation Tools Host Configuration” tab define the listening ports of the LibreOffice instances in the LibreOffice instance configuration field and click “Next”.

Additional Configuration OptionsPermanent link for this heading

Additional conversion options can be specified in the registry path HKEY_LOCAL_MACHINE\Software\Fabasoft\FSCCONV@1.1001:

  • PreferMSOfficePDFA: A value greater than 0 specifies that a PDF/A document will be created when converting via Microsoft Office, even though the target format is “PDF”. By default, this option is not enabled.
  • PreferOpenOfficePDFA: A value greater than 0 specifies that a PDF/A document will be created when converting via LibreOffice application, even though when the target format is “PDF”. By default, this option is not enabled.
  • DisableWordFillIn: A value greater than 0 disables all Fill-In fields when converting a Microsoft Word document. Enabling this option has a performance impact. By default, this option is not enabled.
  • UpdateFieldsAtPrint: If the value is 1 fields in the document will be updated, if the value is 0 the fields will not be updated.

Web Service InterfacePermanent link for this heading

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:

  • FSCCONV@1.1001:SOAPConvert
    Executes a conversion action on the target machine.
  • FSCCONV@1.1001:SOAPCheckConvert
    Checks whether a conversion operation can be done on the target machine.
  • FSCTLH@1.1001:GetStateReport
    Returns a report in HTML or XML format that contains status information and statistics about the tools host on the target machine.

Other (external) applications may also use this web service. The WSDL definition for the conversion service is available via the following URL:

http://<webserver>/<vdir>/fscdav/wsdl?WEBSVC=FSCCONV_1_1001_ConversionService

Security RequirementsPermanent link for this heading

DCOM SecurityPermanent link for this heading

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:

  • Local administrators
  • The interactively logged-on user
  • Local system account (operating system account)
  • The anonymous accounts of the Internet Information Server: IUSR_machine, IWAM_machine

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

Excel.Application

Microsoft Word Document

Word.Application

Microsoft PowerPoint Presentation

PowerPoint.Application

Outlook Message Attachment

Outlook.Application

{000C101C-0000-0000-C000-000000000046}

IMsiServer

Note:

  • DCOM servers are COM servers associated with so-called AppIDs, where additional configuration settings like security, identity and other settings are stored.
  • The DCOM server for the MSI Installer is used by Microsoft Office applications and is launched indirectly by the Fabasoft Folio Conversion Service user account.
  • The Fabasoft Folio Web Service setup program does not currently change the DCOM security. It is the administrator’s task to grant launch permissions.

File System Security RequirementsPermanent link for this heading

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.

Security Requirements of Microsoft OfficePermanent link for this heading

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.

Fabasoft Folio Security RequirementsPermanent link for this heading

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.

Licensing IssuesPermanent link for this heading

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:

  • Each client user requires a license for the Microsoft Office applications. Currently, there is no server-licensing model available for this product.
  • The Adobe Acrobat Distiller provides both, client and server licensing.
  • activePDF Server is licensed per server and is available as Professional version with an optional “Thread Upgrade” package, which improves the performance.

TroubleshootingPermanent link for this heading

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.

Changing the PasswordPermanent link for this heading

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”).

Changing the Web Service IdentityPermanent link for this heading

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 new Fabasoft Folio Web Service user account must be able to log on to the Fabasoft Folio Domain. Furthermore a user environment has to be specified for this user account.
  • The new Fabasoft Folio Web Service user account must be a member of the local administrator group.
  • The new Fabasoft Folio Web Service user account must be a member of the local group IIS_WPG.
  • If the new Fabasoft Folio Web Service application pool identity is a domain user account, enable Kerberos authentication. See chapter “Enable Kerberos Authentication“.
  • Adjust the DCOM security so that the new user account is able to start and execute the required Microsoft Office applications. See chapter “Install and Configure Microsoft Office“.
  • Make an interactive logon with the new user account on the Fabasoft Folio Conversion Server and start each Microsoft Office application. This step creates a profile and initializes the Microsoft Office applications for the new user account.
  • The Fabasoft Folio Web Service caches static content in the <Program Files>/Fabasoft/Components/Web/<vdir>/ASP/content/tmp directory. The new user account must have full file access permissions on this file system directory in order to synchronize the cached content during web service start-up.

HTTP Client IssuesPermanent link for this heading

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.

  • Resolve Time Out (in sec) (default: unlimited)
    In this field, a maximum time for resolving the DNS name can be defined.
  • Connect Time Out (in sec) (default: 60 seconds)
    In this field, a maximum time for connecting to the target web server can be defined.
  • Send Time Out (in sec) (default: 5 minutes)
    In this field, a maximum time for sending the request to the target web server can be defined.
  • Receive Time Out (in sec) (default: 60 minutes)
    In this field, a maximum time for receiving the response from the target web server can be defined.

Microsoft WinHTTP 5.0 and WinHTTP 5.1Permanent link for this heading

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.

Kerberos Authentication IssuesPermanent link for this heading

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 (Recommended)Permanent link for this heading

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

Disable Integrated Microsoft Windows AuthenticationPermanent link for this heading

In the “Internet Services Manager” MMC snap-in, disable Integrated Microsoft Windows Authentication for the virtual directory of the Fabasoft Folio Conversion Service.

Disadvantage:

  • Basic Authentication is not safe.

IP address forces Basic AuthenticationPermanent link for this heading

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.

Disadvantages:

  • Basic Authentication is not safe.
  • Names are better than IP addresses because IP addresses change more frequently than names.

Local user account as application pool identityPermanent link for this heading

Configure the application pool identity of the Fabasoft Folio Conversion Service as a local user account.

Disadvantage:

  • Local user accounts have to be maintained, which results in a significant increase of administrative effort.

Connect with a local user accountPermanent link for this heading

Configure a local user account in the Default Web Services configuration object.

Disadvantages:

  • Local user accounts have to be maintained, which results in a significant increase of administrative effort.
  • Load balancing using a content switch will not work, because the selected target server may not know the supplied user account.

Simultaneous Use as a Regular Web ServicePermanent link for this heading

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.

Transaction ContextPermanent link for this heading

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.

Enable the Logging ModePermanent link for this heading

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.

Obtaining the Tools Host StatePermanent link for this heading

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:

http://<webserver>/<vdir>/tlhstatus

LibreOffice IssuesPermanent link for this heading

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”.

IIS Time Out IssuesPermanent link for this heading

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.

Microsoft Office IssuesPermanent link for this heading

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.

ReferencesPermanent link for this heading