Configure PDF downsize

The Downsize PDF server action offers the possibility to reduce the size of PDFs if the file is too large. Learn how to configure the server actions and configure the parameters to calculate the downsized PDF.

By default, these server actions are not installed on your system.

Context

The censhare Admin Client is needed to configure the server actions.
The parameters for the calculation of the downsized PDF are stored in a module asset.

Prerequisites

censhare Server or censhare Service Client with installed Ghostscript.
Deeper knowledge of Ghostscript, if you want to adapt the PDF calculation parameters to your own needs.
Installed PDF downsize module asset in the censhare Admin Client. This module asset is optional and therefore not installed by default.

Introduction

The Downsize PDF server actions provide you with a simple built-in solution to reduce the size of a PDF.

censhare uses the "Ghostscript" open-source tool for the calculation of the downsized PDF. For the conversion, it calls the tool with the parameters that are configured in censhare. There are two possibilities to start the conversion: By a user and by asset automation:

The Downsize PDF (manual) server action for user.
The Downsize PDF (automatic) server action for asset automation.

Users can call the Downsize PDF (manual) server action within censhare Web or the censhare Client. The server action is available for assets that have the PDF document MIME type. The Downsize PDF (automatic) server action is executed if one of the events occurs that are defined for this server action. Typically, these can be asset events like Save and close or Asset workflow changed.

There are two places where configuration takes place:

On the censhare Admin Client: the PDF downsize module with the two server actions.
On censhare Web or censhare Java Client: the Preset Downsize PDF configuration asset that contains the parameters for the conversion by Ghostscript.

Note: By default, the Downsize PDF functionality is not installed on your system. Before you can configure it for the first time, you have to install the PDF downsize module on your system. This is done by the Synchronize module assets server action in the Admin Client.

For the Downsize PDF (manual) server action, there is not much configuration needed. You just have to activate the server action.

For the Downsize PDF (automatic) server action there are three configuration topics: the activation of the server action, the definition of the Trigger events and the adaption of the Asset filters. The trigger events tell censhare when to execute the conversion. The asset filters define for which assets the server action is applied to.

For the configuration of the parameters applied by Ghostscript, censhare provides a set of parameters. These parameters can be used without modification. But you can adapt them if needed.

censhare does not allow you to have multiple configuration assets that can be used side by side. There can only be one configuration asset in the system. This means the values stored in this configuration asset are used for all PDF downsize operations.

Asset XML

When censhare has converted the original PDF, it attaches the new file to the asset and names it Downsize PDF. You can see this also in the asset XML (presentation shortened):

CODE

<storage_item asset_id="26543" … 
    key="pdf-downsize"
    mimetype="application/pdf"  … />

"<storage_item" refers to a file attached to the asset. The new created "Downsize PDF" file has the pdf-downsize file type (attribute = "key"). The MIME type for the file is set to PDF (application/pdf).

You can use the file type in censhare Client or censhare Web to search for all assets that have a Downsize PDF file. In the censhare Client, open the search and go to the Expert tab and select File type as search parameter. In censhare Web use the Expert search in the top navigation and select File type as search parameter, too.

Configuration of the Ghostscript parameters

censhare stores the parameters for the conversion in the master file of the Preset Downsize PDF configuration asset. This configuration asset needs to have a resource key with the preset-downsize-pdf value. This setting must not be changed. If the system does not find a configuration asset containing this resource key, the calculation of a downsized PDF will fail.

The parameters at Preset Downsize PDF configuration asset can be used without modification. But you can adapt them if needed.

Note: You should change the parameters only if you have a deeper understanding of PDFs and should know how Ghostscript is working. Otherwise, you might not get the expected results.

In the following, you find some more information about the configuration of the parameters for the downsizing of the PDF. Besides, you will learn how censhare invokes the Ghostscript command and what is written into the log when executing the command. This might help you in case of troubleshooting.

The configuration for Ghostscript is an XML file attached with the Preset Downsize PDF asset. This file contains the following parameters by default:

CODE

<!-- Preset GhostScript transcoding-->

<parameters> 
  <parameter key="-dUseCIEColor"/> 
  <parameter key="-dNOPAUSE"/> 
  <parameter key="-dBATCH"/> 
  <parameter key="-dVERBOSE"/> 
  <parameter key="-r144"/> 
  <parameter key="-dSAFER"/> 
  <parameter key="-sDEVICE" value="pdfwrite"/> 
  <parameter key="-dNumRenderingThreads" value="4"/> 
  <parameter key="-dEmbedAllFonts" value="true"/> 
  <parameter key="-dCompatibilityLevel" value="1.4"/> 
  <parameter key="-dSubsetFonts" value="true"/> 
  <parameter key="-dCompressPages" value="true"/> 
  <parameter key="-dMaxInlineImageSize" value="4"/>
</parameters>

If you want to know more about the different parameters, see the Ghostscript website.

censhare reads these parameters and invokes Ghostscript from the command line. With the parameters above it looks like this:

"INSTALL_PATH/ghostscript/bin/gs -dUseCIEColor -dNOPAUSE -dBATCH -dVERBOSE -r144 
    -dSAFER -sDEVICE=pdfwrite -dNumRenderingThreads=4 -dEmbedAllFonts=true 
    -dCompatibilityLevel=1.4 -dSubsetFonts=true -dCompressPages=true 
    -dMaxInlineImageSize=4 -sOutputFile=PATH1/OUTPUT.pdf PATH2/ORIGIN.pdf"

"INSTALL_PATH" is the place where Ghostscript is installed. "sOutputFile=PATH1/OUTPUT.pdf" indicates where to write the output file. "PATH2/ORIGIN.pdf" is the input file for the calculation. You can use this command line to test your parameters before you add them to the configuration file in censhare.

When censhare executes Ghostscript it writes the call also into the log file. Therefore, you can use the command line call to find the place in the log file where the Downsize PDF server action (manual or automatic) was executed. Depending on whether the conversion is manually or automatically started, the entries slightly differ from each other.

Installation of the Downsize PDF configuration asset

If you do not have to configure the Downsize PDF module for the first time, you can skip this step. It is only necessary if the module asset for PDF Downsize configuration is not yet installed. The module asset is only optional and therefore might not have been installed.

You install the Downsize PDF module asset in the Admin Client using the Synchronize module assets server action. The configuration for the module is stored on your server within the following path:

"../censhare-Server/install/system/optional/pdf-presets"

Configure the installation path

Before you can execute the Synchronize module assets asset action, you need to configure the path for the desired module. censhare needs to know where to find the configuration of the desired module. When you execute the server action, you then select this stored path for the installation.

In the Admin Client, go to the "Configuration/Modules/Administration/Module Assets" folder.
Double-click to open Synchronize module assets.
Go to the end of the Search paths in the Configuration asset import section.
Click the "+" icon and enter "optional/pdf-presets" in the Path field.
Uncheck the Enabled field. It prevents the installation option is enabled by default when calling the Synchronize module assets server action.
Click OK at the top of the dialog.

Update the server configuration

Now, you have to transfer the configuration from the Admin Client to the Master server and then to Remote servers if existing:

Click the Update server configuration icon at the top of the Admin Client to transfer the changed configuration to your Master server.
If there are remote servers, you have to update them, too. Click the Synchronize remote server icon at the top.

Synchronize the Downsize PDF Module

Now, perform the installation of the Downsize PDF module asset itself:

Click the Server action icon at the top of Admin Client and select Synchronize module assets
A dialog opens where you have to choose the modules you want to synchronize. Only activate optional/pdf-presets. Make sure that you uncheck all other boxes. Otherwise, you will synchronize those modules, too.
Click OK. After that the PDF downsize folder is visible in Configuration/Modules folder and you can configure it.

Configure Downsize PDF (manual) server action

To use the Downsize PDF (manual) server action you just need to activate it:

In the Admin Client select the Configuration/Modules/PDFdownsize folder.
Double-click to open PDF downsize (manual).
Activate the Enabled field in the General setup section and click OK.
Update the server configuration.

The manual server action is then available in the censhare Client and censhare Web.

Configure Downsize PDF (automatic) server action

To use the Downsize PDF (automatic) server action you have to do three things:

Activate the server action.
Configure the triggers to execute the action.
Adapt the Asset filters.

There should be a filter that the action is only applied with assets that have a master file with the MIME type PDF document. This prevents the action is called at all for assets that do not have an appropriate master file attached. Besides, you can define a filter to only generate a downsized PDF from files that exceed a certain file size.

Activate the server action

In the Admin Client, select the Configuration/Modules/PDF downsize folder.
Double-click to open PDF downsize (manual).
Activate the Enabled field in the General setup section.

Configure the triggers

To configure the triggers select the Trigger events section.
censhare provides different kinds of triggers: Asset events, Timer event, Cron event and Generic asset events. Configure the triggers according to your needs.

Adapt the asset filters

Each automatic server action also has an asset filter set. You can restrict which assets are considered if the server action is triggered. You can adapt the filter search to your needs:

Double click the Search field in the Asset filters section to open the search dialog.
Add additional search parameters.

As the Downsize PDF server actions only work with assets that have the PDF document MIME type we recommend that you add a filter for this:

Go to the Advanced tab.
Click the + icon and select MIME type as search parameter.
Select PDF document as search value.

This ensures that the server action is only raised for PDF assets. Of course, the server action itself would at least check if the passed asset is an appropriate one for conversion.

For each asset file attached to an asset, censhare stores the file size in the asset in the according File length property. You can use this value to ensure that a PDF with the reduced size is only calculated for larger PDFs:

Go to the Advanced tab.
Click the + icon and select File length as search parameter.
Enter the minimum file size for PDFs in bytes in the search field and choose the ">=" comparison operator.

When you are finished, close the search dialog with OK and the configuration dialog with OK, too. Then, update your system: see Updating the server configuration.

Result

The Downsize PDF (manual) server action is available for users in the censhare Client and censhare Web. The server automation for Downsize PDF (automatic) is configured. Whenever the defined events occur, the Downsize PDF is executed for the respective assets.