Setting Up a Document Conversion Server

Some documents -- including PDFs and those from Microsoft Office -- are supported in a preview view in Jive. If you want to convert content from its native format into a form that can be previewed without altering the original document, you'll need the Document Conversion plugin, which you'll need to deploy on a server that is separate from your core Jive production instances.

Note: For information about managing conversion attempts, where you can reconvert documents if necessary, see Managing Document Conversion.

This document describes a simple Jive environment with a single conversion machine. In the following, "application node" will specify the server running just the Jive application and "conversion machine" will specify the server running the conversion utilities.

There are two services dedicated to document conversion:

Note: For versions 4.0.7 and later, on new application installations conversion-specific features such as the JOOSD and JDCD services are off by default.
Setting up a conversion machine involves the following high-level steps:
  1. Set up a production instance of the application.
  2. Install and configure one or more conversion machines.
  3. On the application node, configure the application to communicate with the conversion machine(s).
The remainder of this topic assumes that you've set up the application according to the following high-level steps:
  1. Install the application as described in the installation documentation (Linux, Solaris ).
  2. Restart the application to complete configuration.
    su - jive
    apprestart
  3. Finish customizing the community as described in the documentation.
  4. If you haven't already, disable the JOOSD and JDCD Services on application node (these are off by default on new installs of versions 4.0.7 and later). You can use a command such as the following:
    On Linux
    
    service jive-joosd stop && chkconfig jive-joosd off
    Stopping jive-joosd:
    OK
    service jive-jdcd stop && chkconfig jive-jdcd off
    Stopping jive-jdcd:
    OK
    
    On Solaris
    
    svcadm disable jive/joosd:default
    svcadm disable jive/jdcd:default

    You can verify these services no longer start with the following command:

    On Linux
    
    chkconfig --list
    
    On Solaris
    
    svcs -a |grep jive

Installing and Configuring the Conversion Machine

Run all of these commands as root unless otherwise noted.
Note: Before attempting to use the connection to the conversion machine, the application node will attempt to test the connection. To support this test (and avoid errors), open TCP port 7 on the conversion machine. (If you prefer not to open the port, you can disable the test by setting the jive.dv.service.connection.verification system property to false.)
  1. Install the application as described in the installation documentation (Linux, Solaris ).
  2. Because this machine's only function will be operating as a document conversion service, you should consider disabling all unnecessary services.

    You can list all services with the following command; use discretion with the services you disable:

    chkconfig --list

    Consider disabling the following:

    On Linux
    
    chkconfig acpid off
    chkconfig atd off
    chkconfig autofs off
    chkconfig avahi-daemon off
    chkconfig cpuspeed off
    chkconfig cups off
    chkconfig gpm off
    chkconfig haldaemon off
    chkconfig kudzu off
    chkconfig lvm2-monitor off
    chkconfig messagebus off
    chkconfig netfs off
    chkconfig nfslock off
    chkconfig portmap off
    chkconfig rpcgssd off
    chkconfig rpcidmapd off
    chkconfig smartd off
  3. (Optional) Enable ports 8200, 8850, and 8810 - 8814 on the conversion machine. If you have a firewall enabled you will need to open those ports. You might need to coordinate this with your network administrator.
  4. Disable unused services on the conversion machine and remove the default application. Enable conversion services on the conversion machine:
    On Linux
    
    su - jive -c 'apprm sbs'
    
    service jive-application stop && chkconfig jive-application off
    Stopping jive-application:
    
    OK
    
    service jive-httpd stop && chkconfig jive-httpd off Stopping jive-httpd:
    Stopping jive-httpd:
    
    OK
    
    service jive-database stop && chkconfig jive-database off
    Stopping jive-database:
    waiting for server to shut down.... done
    server stopped
    
    On Solaris
    
    svcadm disable jive/application:default 
    
    svcadm disable jive/httpd:default 
    
    svcadm disable jive/database:default
    You can verify these services no longer start through the following commands:
    On Linux
    
    chkconfig --list
    
    On Solaris
    
    svcs -a |grep jive
  5. Configure JOOSD to accept connections from a remote host and restart the service to pick up the changes. As the default jive user jive, modify /etc/jive/conf/jive-joosd.conf (you may need to create this file):
    vi /etc/jive/conf/joosd.conf

    Add the following line:

    OPTIONS='--debug -a 0.0.0.0 -z 0.0.0.0'

    Restart the service:

    On Linux
    
    /etc/init.d/jive-joosd restart
    Stopping jive-joosd:
    OK
    Starting jive-joosd:
    joosd started successfully.
    OK
    
    On Solaris
    
    svcadm restart jive/joosd:default
  6. Configure JDCD to accept connections from a remote host and restart the service to pick up the changes. As the default jive user jive, modify /etc/jive/conf/jive-jdcd.conf (you may need to create this file):
    vi /etc/jive/conf/jdcd.conf

    Add the following line to the file:

    OPTIONS=' --debug -a 0.0.0.0'

    Restart the service:

    On Linux
    
    /etc/init.d/jive-jdcd restart
    Stopping jive-jdcd:
    OK
    Starting jive-jdcd:
    jdcd started successfully.
    OK
    
    On Solaris
    
    svcadm restart jive/jdcd:default

Configuring the Application to Use a Conversion Machine

On the node that hosts the application, you use the admin console to configure the application to communicate with conversion machines you've set up.

The admin console's Document Conversion Settings page is set up so that most of the values you'll likely need are prepopulated so that you don't have to set them. Most of these needn't change.

  1. On Solaris: Tell the convertor to use OpenOffice directly to convert documents to PDF. In the admin console, at System > Management > System Properties, set the converters.openoffice.skipodf system property to true.
  2. Restart the application to complete configuration.
    su - jive
    apprestart
  3. Finish customizing the community as outlined in the documentation.
  4. In the admin console, on the Document Conversion Settings page, be sure to read the quickstart steps at the top of the page. Settings you make on this page assume, for example, that you've already enabled the JOOSD and JDCD services on your conversion machines.
  5. Near the top of the page, click Enabled to enable the conversion service. (Note that changing this setting requires that you restart the application in order to have the settings take effect. This must be done for every node in your cluster.)
  6. Click Add a Node to start configuring a conversion machine.
  7. Enter the IP address for a conversion machine you set up.
  8. Under File Transfer Settings, the protocol, domain, port, and context settings comprise the location that conversion machines should call when converted documents are ready for return to the application. It's unlikely you'll need to make changes to this. However, changes might be needed to account for special configurations, such as a single sign-on (SSO) configuration.
    Note that you probably don't need to change the settings in the bottom half of the page. The settings in the following list apply to all conversion machines you create, and you typically need never make changes to their values. If you do change any of their values, you must ensure that the corresponding value on every conversion machine matches the setting you make in the admin console on the application node.
    • Open Office ports -- Port numbers to support a pool of connections to conversion machines.
    • JOOSD port -- Port number for the Jive Open Office Service Daemon on conversion machines.
    • JDCD port -- Port number for the Jive Document Conversion Daemon on conversion machines.

    By the same token, the JMS Settings port number should typically stay at its default value.

  9. Under Disabled Extensions, in the Extensions box, enter a comma-separate list of the extensions for files for which a preview shouldn't be created. For example, if you don't want Excel files converted, you might enter:
    xls, xlsx
  10. If you have more than one conversion machine, repeat steps 3 and 4 for each. All of the other settings apply across conversion machines.

Troubleshooting Document Conversion Machine Setup

Confirming That the Ports are Open

If you're seeing evidence that might indicate that ports are closed where they should be open, try using netcat (nc) to verify that the ports you need are open.

  1. In a command prompt on the server whose port you want to verify, use the nc command to start listening on the port in question. For example, you might type the following to start listening on port 8850 on a server whose IP address is 10.61.32.156:
    nc -l 8850
  2. In another command prompt, use the telnet command to connect to the port specified in the first command. Here's an example:
    telnet 10.61.32.156 8850
  3. Verify the connection by typing in the first command prompt. What you type should appear in the second window if the port is open.

Corrupted Queuing Database

The application uses a small database to queue documents for conversion. If this database becomes corrupt, you might see a logged error with the message "Failed to create database 'derbydb'." If this occurs, try clearing the directory at /usr/local/jive/applications/<app_name>/home/jms/ and restart the application. If you have the application deployed in a cluster, you'll need to do this for each application node.