How to set up the Rendition Service for Vizit

Note: As of Vizit 6.3, the Rendition Service will no longer be supported. Instead, click here to check if the formats you want to add are already supported, and use an IPDFConverter plugin to add them if not.

 

In version 1.6 we added support for over 50 different formats by introducing the Rendition Service. The Rendition Service runs on a separate server and leverages third party APIs (the OpenOffice API) to convert documents to Vizit-supported formats (such as PDF).

(Please see Formats supported by Vizit through the Rendition Service using OpenOffice for more information about which file types are supported) 

Running file conversions outside of the SharePoint farm prevents resource-intensive operations from affecting your farm's performance.

The following diagram shows the principle of the Rendition Service operation:

RenditionService.png

  1. User opens a document in Vizit;
  2. One of the Web Front End servers in your farm receives the request and either retrieves the document using the standard SharePoint Object Model, or a previously rendered copy from Vizit's cache;
  3. Vizit downloads the actual document or cached copy from your SharePoint content database, external BLOB storage or external archive;
  4. If the document format is not supported by Vizit natively, its content is sent to the Rendition Service;
  5. The Rendition Service runs a process to convert the document or re-uses a converted copy from its local cache;
  6. Once the conversion is complete, the Web Front End receives a readable copy from the Rendition Service, stores it in its local cache and uses it for displaying the document;
  7. The document is served to the user through Vizit in read-only mode.

NOTE: Unlike with SharePoint document converters, nothing is written back into the SharePoint content database. The whole process is local to Vizit only and does not affect the original document or any metadata in SharePoint.

 

Rendition Service prerequisites

For efficient operation you will minimally need:

  • A server capable of handling a sufficient amount of concurrent conversions. Memory is a critical resource for conversions, since each conversion loads a document into memory and then saves it to a different format. If the conversion is handled by OpenOffice, a worker process will take roughly 100Mb to load average-sized Microsoft Word documents, so one could estimate the required capacity by multiplying number of expected concurrent conversions by 100 Mb. For example, 10 concurrent conversions will require 10x100Mb = 1000Mb of RAM. This corresponds to 10 concurrent users at any given moment; your farm can serve thousands of users, while only few of them may be using the Rendition Service at the same time.
  • Windows 2003 server (workstation will work too, but it is not recommended for production deployment due to scalability limitations);
  • OpenOffice version 3.1+. It can be downloaded from http://download.openoffice.org
  • Microsoft .NET framework 3.5. It can be downloaded here.
  • Vizit 1.6 or later installed and running in your SharePoint farm
  • Microsoft's “installutil” (MSDN documentation). The install utility comes with Microsoft .NET framework 3.5 and should be in your search path.  It is located in C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727 folder.

 

Installing the Rendition Service

  1. In SharePoint 2007, go to “Central Administration”, “Application Management” tab and click “Configure Supported Document Formats”.
  2. In SharePoint 2010, go to "Central Administration" and click "Configure Supported Document Formats".
  3. Scroll to the bottom of the page to the “Extended formats” section:

    Rendition.JPG
  4. Click “Download Rendition Service component” link, a ZIP archive will download.
  5. Extract the ZIP archive into C:\Program Files\Vizit\Rendition Service\ or any other folder of your choice.
    • In SharePoint 2007, you will find three folders: “bin”, “work” and “cache”.  The "bin" folder contains the service program file itself, required third party libraries and a configuration file: "Atalasoft.Transform.RenditionService.config
    • In SharePoint 2010, you will find one folder: "bin".  The “bin” folder contains the service program file itself, required third party libraries and a configuration file: "Vizit.Transform.RenditionService.config".
  6. Edit the configuration file. 
    • In SharePoint 2007: Locate the <Atalasoft> section
    • In SharePoint 2010: Locate the <Vizit> section 
  7. Change “WorkDir”, “OpenOfficeServerPath” and “CachePath” as necessary.  Normally, the "WorkDir" and "CachePath" directories exist inside the "Rendition Service" folder; however, that is not required.  If these folders do not exist, they will be created as needed by the program.
    <Vizit>
       <!--
        Transform server settings.
        All files/directories below must exist
    prior to startup:
      --> <TransformServer
      WorkDir="C:\Program Files\Vizit\Rendition Service\Work"
      OpenOfficeServerPath="C:\Program Files\OpenOffice.org 3\program\soffice.bin"
      CachePath="C:\Program Files\Vizit\Rendition Service\Cache"
      MaxCacheSize="16384"
      CleanupPeriod="00:10:00"/>
    </Vizit>
    • The “WorkDir” should be the full path to the Rendition Service “Work” directory.  This is where all temporary conversions will take place.
    • The “CachePath” is the full path to the Rendition Service “Cache” folder.  It contains all cached files and will be cleaned up by the service automatically.
    • The “OpenOfficeServerPath” is the full path to OpenOffice’s soffice.bin file.
    • The "MaxCacheSize" and "CleanupPeriod" control the Rendition Service's cache behavior.  The "MaxCacheSize" specifies the maximum cache size in megabytes.  If the cache grows over that limit, older entries will be removed automatically.  The "CleanupPeriod" defines the time interval between cache size checks. 
  8. Configure the "system.serviceModel" section according to Microsoft’s guidelines.  If you happen to have the Microsoft Windows SDK installed, you may want to use the configuration editor tool (SvcConfigEditor).  Default settings correspond to insecure TCP/IP communication, which gives maximum speed.  Minimally you need to replace “server.company.com” with the fully-qualified DNS name of your server in two places.  Take a note of the base address (check the "system.serviceModel/services/service/host/baseAddresses" section of configuration file), you will need it later.  Please follow the steps in the section "Running the Rendition Service as a windows service" below.
  9. Return to the Vizit administration page, click “Restore defaults” to populate default formats. 
  10. Check the “Enable Rendition Service” checkbox. 
  11. Type or paste the service URL from step 8 (such as net.tcp://server.company.com:8732/Vizit/TransformService/) into the textbox. 
  12. Click the “Save” button.

Note: Once the settings are saved, you can test the Rendition Service is functioning by clicking the “Test Rendition Service” on the button to check the connectivity between Vizit and the Rendition Service.

Running the Rendition Service as a windows service

To install the Rendition Service as a windows service please do the following:

  1. Open command prompt, go to the Rendition Service "bin" folder (e.g. C:\Program Files\Vizit\Rendition Service\bin) directory
    • For SharePoint 2007 run the following command to install windows service:
      InstallUtil.exe Atalasoft.Transform.RenditionService.exe
    • For SharePoint 2010, replace Atalasoft with Vizit:
      InstallUtil.exe Vizit.Transform.RenditionService.exe
  2. Open the services management console (click “Start”, then “Run…”, and type “services.msc”)
  3. For SharePoint 2007, locate “Atalasoft Rendition Service”, or "Vizit Rendition Service" for SharePoint 2010 and display the service properties by double-clicking the service, or right-clicking and selecting "Properties" from the context menu.
  4. Choose “Startup type” -> “Automatic”.
  5. Click “Start” and make sure service starts up.
  6. Test the service as described in “Debugging the Rendition Service”.
Please noteConsider locking service down in production environment as described in “Security considerations for production environment”.

 

Security considerations for production environment

The Rendition Service uses third party applications, such as OpenOffice, to convert documents.  In order to convert a document, the Rendition Service must open the document, load it in memory and then produce a copy in Vizit-consumable format, which is equivalent to opening the document using the office application.  Although we take all necessary precautions, such as disabling macros, running OpenOffice in thin mode and against temporary profiles, certain risks still exist.  Therefore we recommend the following steps to prevent undesired side effects:

  1. Create a designated local user (for example “Rendition”) and run the service on behalf of that user.  Remove the user from the User group and restrict access to only “bin”, “work” and “cache” folders.  “Work” and “Cache” folders need to be writeable, the “bin” folder may be read-only.  This will prevent third party applications from accessing other files on the server running the Rendition Service.
  2. Make sure the “Rendition” user does not have access to your domain and SharePoint farm.
  3. Restrict all network connections to/from the server running the Rendition Service, except for the Rendition Service port.

 

Practical limitations for converted documents in Vizit

When Vizit uses a converter to show a document, certain functions become unavailable.  In particular:

  • You will not be able to do any document-editing functions, since you are working with a read-only copy;
  • You will be able to rotate/flip document, but will not be able to save the changes;
  • You will be able to annotate document and save the annotations, since annotations are not stored in the document;
  • You will be able to edit and save document’s properties (metadata) since they are external to the document and stored in SharePoint;
  • You will be able to print and export converted documents as PDF documents;
  • Since the document needs to be downloaded from a SharePoint database to a WebFront and then loaded in memory (either on a transform server or locally), there is a practical limitation on the document you can view. Some 250Mb DXF files could significantly increase the load on the server and introduce severe latency to the interface during the conversion. Once conversion is done, Vizit is fast as usual.

 

Debugging the Rendition Service

Running the Rendition Service in a command prompt

Sometimes, it is desired to run the the Rendition Service in command prompt as console application. This may be helpful if you have issues with running as windows service due to permission restrictions or connectivity problems. To run the Rendition Service in command prompt:

  1. Stop the “Vizit Rendition Service” windows service if it is running
  2. Open command prompt, change directory to C:\Program Files\Vizit\Rendition Service\service\bin or other location where you have installed the Rendition Service binaries.
    • For SharePoint 2007, run the following command:
      Atalasoft.Transform.RenditionService.exe --debug
    • For SharePoint 2010, run the following command:
      Vizit.Transform.RenditionService.exe --debug

The Rendition Service will run in console mode and display the address of its endpoint which you can use within Vizit or our test application (described in “Using the Rendition Service test application”).  Please note that console mode is for debugging only.  It should not be used in production, since the Rendition Service will not start up automatically if the server is rebooted.

 

Using the Rendition Service test application

Normally testing connectivity from the “Vizit administration” page is sufficient to ensure your service is up and running.  To test the Rendition Service navigate to the “Vizit administration” page and click the “Test rendition service” button.  If you want to debug the Rendition Service, you may use the Rendition Service test application – a console client tool that connects directly to the Rendition Service and displays all error details. To run the test tool please do the following:

  1. Download the Rendition Service test application (extended formats section of the Vizit administration page).
  2. Extract the ZIP file to “C:\Program Files\Vizit\Rendition Service” or any other folder of your choice.
  3. Depending on whether you're using SharePoint 2007 or 2010, edit the Atalasoft.Transform.RemoteConverter.config or Vizit.Transform.RemoteConverter.config file, respectively. Locate the configuration/system.serviceModel/client/endpoint section and change the address attribute to the URL of your Rendition Service.
  4. Save and close the file.
    • For SharePoint 2007, run the following command:
      Atalasoft.Transform.RemoteConverter.exe <file1> <file2> ...
    • For SharePoint 2010, run the following command:
      Vizit.Transform.RemoteConverter.exe <file1> <file2> ...

The test program will connect to the Rendition Service, convert the specified files and save PDF copies next to them.

 

References

  1. Official OpenOffice download page
  2. WCF configuration editor tool SvcConfigEditor
  3. MSDN documentation on configuring WCF services
Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk