Installing

Alfresco Enterprise 4.0.2 Administrator 73

Installing and configuring the Alfresco Transformation Server
This section describes how to install and configure the Alfresco Transformation Server.
Transformation server overview
The Alfresco Transformation Server is a stable, fast, and scalable solution for high-quality
transformations of Microsoft Office documents. It is an enterprise-scale and enterprise quality
alternative for OpenOffice.
The server features an open architecture, and it offers the following features:
High quality
The Alfresco Transformation Server uses genuine Microsoft Office software to transform MS
Word, Excel, and PowerPoint documents to PDF and SWF. This guarantees the handling of
all Office files and pixel-perfect transformations, and it corrects previous layout issues in the
Share preview feature.
Scalable
The Alfresco Transformation Server communicates with Alfresco using an HTTP REST API,
which means that you can scale up by adding multiple instances of the server and connecting
them through a standard HTTP Network Load Balancer.
Installing
74 Enterprise 4.0.2
Stable
If Microsoft Office can open and transform your document, then so can the Alfresco
Transformation Server. Robust error handling will take care of corrupt and encrypted
documents. A Web Console shows you a detailed report if there is a problem during
transformation, allowing you to correct documents.
Fast
The Alfresco Transformation Server is two to three times faster when transforming multi-
megabyte Office documents when compared with OpenOffice on the same hardware.
Extensible format support
The Alfresco Transformation Server supports the transformation of MS Office formats.
Upcoming versions will support image and video transformations. Please contact Alfresco
Support if you need support for other formats.
Transformation Server prerequisites
The Alfresco Transformation Server consists of two software modules:
Standalone Transformation Server
Alfresco Transformation Client
The Standalone Transformation Server runs on Windows and takes care of the file
transformations.
The Alfresco Transformation Client runs as a part of the Alfresco ECM server and takes care of
the communication between Alfresco and the Transformation Server.
The Transformation Server is available for the following Alfresco versions:
alfresco-4.0-transformationserver-2.0.0.zip for Alfresco 4.0.0
alfresco-4.0-transformationserver-2.0.1.zip for Alfresco 4.0.1
Make sure that you select the correct Transformation Server ZIP file for the version of Alfresco
that you are running.
Standalone Transformation Server prerequisites
The Alfresco Transformation Server requires the installation of the following software
components:
Microsoft Windows 2008 Server R2 SP1 x64 with the latest hot fixes (English)
Microsoft Office 2010 SP1 x86 (English)
Java Development Kit 1.6 update 30 x86 (or later updates of the JDK 1.6)
The following points are important to note before you install the Transformation Server:
Install only the English versions of MS Windows Server 2008 and Office 2010
because other languages result in unpredictable behavior
Make sure that the Windows print spooler service is running
Java 7 is not supported
Java 6 x64 is not supported
Alfresco Transformation Client prerequisites
The Alfresco Transformation Client is available for Alfresco Enterprise 4.0.0 or 4.0.1.

Installing
Alfresco Enterprise 4.0.2 Administrator 75
Transformation Server License
The Alfresco Transformation Server is sold as a separate product, which can only be enabled
with a separate license key.
The license key replaces your existing Enterprise license key.
Request your Transformation Server license key from Alfresco Support.
Installing the Alfresco Transformation Server
This section describes how to install all the components required for the Alfresco Transformation
Server.
The following artifacts are shipped for the Alfresco Transformation Server:
alfresco-4.0-transformationserver-2.0.0.zip for Alfresco 4.0.0
alfresco-4.0-transformationserver-2.0.1.zip for Alfresco 4.0.1
Make sure that you select the correct Transformation Server ZIP file for the appropriate version of
Alfresco that you are running.
The Transformation Server zip file contains the following artifacts:
alfresco-transformationserver-repo-version.amp
alfresco-transformationserver-server-1.0.0.msi
Transformation_Server_Release_Notes-version.pdf
Installing the Transformation Server consists of two parts:
1. Installing the MSI installation package on the standalone Transformation Server.
2. Installing the relevant AMP package and updating the license on the Alfresco server.
Installing the standalone Transformation Server
This section describes how to install the standalone Transformation Server.
Before you start the installation, verify that you have:
installed and activated Windows 2008 Server
installed and activated Microsoft Office 2010
logged on to the Windows Server as a user with administrator rights
1. Double click the MSI installer package alfresco-transformationserver-
server-1.0.0.msi.
The Welcome screen opens.
2. Click Next.
The license information screen displays.
3. Click Next.
4. Select an installation folder or accept the default folder, and then click Next.
5. Select the TCP/IP ports used by the Transformation Server.
The default values are 8080 (HTTP) and 8443 (HTTPS) but you can also use the standard
ports 80 and 443 (or any other port) if this fits better into your network infrastructure.
6. Click Next to start the installation.
You see a progress bar and a command line window during the installation. The installer
will show a confirmation when the installation is finished.
7. Click Next to finish the installation.
Installing
76 Enterprise 4.0.2
8. Verify that the installation has completed successfully.
a. Check the Windows Services in the management console.
b. Locate the new service called Transformation Service, and check that it is Started.
Installing the Transformation Server on Alfresco
This section describes how to install the Transformation Server AMP and to update the required
license.
Before you start, make sure that you verify the following prerequisites:
Check that your Alfresco Enterprise server is correctly configured and tested
Make sure that you have the correct Transformation Server ZIP file for the version of
Alfresco that you are running
Make sure that you have an updated license file (a *.lic file)
1. Stop the Alfresco server.
2. Open a terminal (Linux) or command line window (Windows).
3. Navigate to the <ALFRESCO_HOME>/amps directory.
4. Copy the alfresco-transformationserver-repo-version.amp file to the
<ALFRESCO_HOME>/amps folder.
5. Install the AMP package using the apply_amps command.
Linux: bin/apply_amps.sh
Windows: bin\apply_amps.bat
6. Copy your updated license file into the Alfresco installation folder.
Delete all files with extension *.installed in this directory.
7. Start the Alfresco server.
8. Monitor your Alfresco log.
You will see successful log entries about the license installation and the installation of the
Alfresco Module Package (depending on the configuration of your log level).
Configuring the Alfresco Transformation Server
This section describes how to configure the components installed for the Alfresco Transformation
Server.
Configuring the Alfresco Transformation Server consists of two parts:
1. Configuring the Standalone Transformation Server using the Web Console.
2. Configuring the Alfresco Transformation Client using a properties file or JMX.
Configuring the Standalone Transformation Server
This section describes how to configure the Standalone Transformation Server. only need to
change the password of the transformation service.
1. Open your browser and navigate to the following URL:
http://<tranformation-host>:<port>/transformation-server/settings
(or https:// when using SSL)
2. Enter your login name and a password.
By default, the login name is set to alfresco, and the password is set to alfresco. The
login name alfresco cannot be changed.
3. Enter a new password, and then click Change to save the password.
Installing
Alfresco Enterprise 4.0.2 Administrator 77
If you close and reopen your browser, youll have to reenter your login and new password.
Configuring the Transformation Client
This section describes how to configure the Transformation Client by defines several parameters
like using HTTP or HTTPS, quality settings, and so on.
There are two different ways that you can configure the Alfresco Transformation Client:
Using the alfresco-global.properties file
Using a JMX client
Configuration using the global properties file
You configure the Transformation Client by adding the relevant properties to the Alfresco global
properties file.
1. Open the alfresco-global.properties file.
2. Add the required properties for configuration settings on the Transformation Client.
3. Save the alfresco-global.properties file, and then restart your Alfresco server.
The following table shows an overview of the available properties:
Property Default
value
Description
transformserver.aliveCheckTimeout 2 Sets the timeout for
the connection tester
in seconds. If the
transformation server
does not answer in
this time interval, it is
considered to be off line.
transformserver.test.cronExpression 0/10 * * *
* ?
Sets the cron expression
that defines how often
the connection tester
will check. The default is
every 10 minutes.
transformserver.disableSSLCertificateValidation false Set this property to true
to allow self-signed
certificates (that is, it is
not issued by an official
Cert Authority).
transformserver.fallbackIfUnavailable true If the Transformation
Server is not available,
when this property is set
to true, the OpenOffice
transformer is used
instead. Availability
is tested with the
transformation
connection tester.
transformserver.fallbackOnTransformationFailure false If the transformation
using the Transformation
Server fails for some
reason, when this
property is set to true,
the transformation will be
retried with OpenOffice
instead.
Installing
78 Enterprise 4.0.2
Property Default
value
Description
transformserver.username alfresco The user name used
to connect to the
Transformation Server.
Do not change this
default.
transformserver.password alfresco The password used
to connect to the
Transformation Server.
Always change the
password from the
default.
transformserver.qualityPreference QUALITY There are two values for
this property:
QUALITY:
optimizes the
SWF preview for
quality.
SIZE: optimizes
the SWF preview
for size. This is
interesting if you
have a lot of big
office docs, for
example, PPT >
100 MB.
transformserver.transformationTimeout 300 Sets the time in
seconds to wait for
the transformation
to complete before
assuming that it has
hung and therefore stop
the transformation. If you
are transforming very
large or complex files,
this time may need to be
increased.
transformserver.url The URL of your
Transformation Server
(or the network load
balancer if you are
using more then
one Transformation
Server). Use
https:// if you
want to use encrypted
communication between
the Alfresco server and
the Transformation
Server.
In a normal setup, you will always overwrite the transformserver.password
and transformserver.url properties. If you want to use SSL encryption
Installing
Alfresco Enterprise 4.0.2 Administrator 79
with the default certificate of the transformation server, make sure that you set
transformserver.disableSSLCertificateValidation=true.
Configuration using JMX
The Transformation Client configuration parameters are exposed as JMX MBeans, which means
that you can view and set the parameters using a JMX client.
See Runtime administration with a JMX client on page 89 for instructions on how to connect a
JMX client to your Alfresco server.
Using the Transformation Server
Whenever you upload your Office files in Share, you will now be using the Alfresco
Transformation Server, and you can see results in the Share preview.
Administrators can view information about the server and transformation errors using the Web
Console.
Using the Transformation Server Web Console
Use the Transformation Server Web Console to view information about the server and
transformation errors. The server lets you view the status of the server, a historical view of all the
transformations completed, and the number of successful and failed transformations.
Only Administrators can access and use the Transformation Server Web Console.
1. To open the Transformation Server Web Console, open a browser, and then navigate to
the following URL:
http://<transformation-host>:</port>:/transformation-server/
Use https:// if you use SSL.
The Server Status view is the default view when you open the Transformation Server
Web Console. The Server Status view shows an overview of the health and the memory
use of the Transformation Server. Ensure that you have the flash plug-in to see the Active
Threads and Memory Usage graphics.
2. Click History view.
Alternatively, you can go directly to the History view by opening a browser, and then
navigating to the following URL:
http://<transformation-host>:<port>:/transformation-server/
transformations
The History view shows the details of the document transformations. It provides a number
of search functions that allow administrators to find transformation problems for specific
documents.
3. You can query the transformation history using the following parameters:
Date-time From and To
File name
Status
User name
4. To investigate errors, set the Outcome field to Error. Hover over the warning sign to view
an indication of the problem with the file.
5. Click the Statistics view.
Alternatively, you can go directly to the Statistics view by opening a browser, and then
navigating to the following URL:
Installing
80 Enterprise 4.0.2
http://<transformation-host>:<port>:/transformation-server/stats
The Statistics view indicates the number of transformations, and the success or failed
ratio.
6. Click the reset link to reset the counter.
Integrating with monitoring tools
You can integrate the Alfresco Transformation Sever with monitoring tools, for example Nagios or
Hyperic, by using HTTP REST calls.
The tool should call the Transformation Server URL with a set of parameters, and then monitor
the response.
Two calls are available:
1. Connection tester call.
This call is also used by the Alfresco Transformation Client to test availability. It checks the
transformation service is up and responding.
a. URL: http://<transformation-host>:<port>:/transformation-server/ /service/transform/v1/
version
b. HTTP Method: GET
c. Make sure that you include basic authentication credentials to your call.
2. Transformation execution call.
This call posts an Office file to the Transformation Service to check whether the
transformation engine is still functioning. This can be used for more in-depth monitoring.
a. URL: http://<transformation-host>:<port>:/transformation-server/ /service/transform/v1/
available
b. HTTP Method: POST
c. Make sure that you include basic authentication credentials to your call.