File conversion

PDF is not a single format; it comprises multiple flavours. For archival purposes, some flavours are more suitable than others. To simplify compliance, SWF can now integrate with a conversion service that converts files to an approved flavour. Administrators can define which flavours are acceptable, and the service will attempt to convert incoming files accordingly. We have also added support for converting other file types to PDF. However, not all files can be converted to every PDF flavour, so administrators must decide how to handle files that do not meet, and cannot be converted to, the required flavour.

The conversion service operates outside SWF as a standalone service, with its connection strings specified in the SWF configuration. Currently, the only publicly available integration is Gotenberg.

The flow

Configured flavours are defined with the signingOrders.usePdfAFlavours property (see all available flavours here). This property also drives the conversion mechanism. If an uploaded file does not conform to any configured PDF flavour, the conversion flow is presented to the user.

When the user selects Convert, SWF converts the file to the first configured PDF flavour and validates the output. If validation fails, SWF attempts the next flavour, continuing until a valid result is produced or all flavours have been tried.

If conversion and validation succeed, the user must review the file and select Approve. If all flavours fail, the user must upload a new file to proceed.

If rejectInvalidPdfA is set to false, the user may proceed with a PDF that does not conform to a configured PDF/A flavour. If all flavours fail for a PDF and rejectInvalidPdfA is set to false, SWF proceeds with the original PDF. If all flavours fail for a .doc or .docx, SWF proceeds with the first conversion candidate.

Configuring file conversion

The file conversion feature can be configured using the documentConversion property in the main config file. There are four properties that needs to be configured:

  • enabled - Whether or not to enable the feature.
  • availableFileSuffixes - What file suffixes to accept. pdf will always be included, regardless of configuration. Currently available suffixes:
    • doc - The older version of Word files
    • docx - The current version of Word files
  • preferredFlavour - A global preferred flavour. If not set (or set to null) SWF will use the flavours configured in usePdfAFlavours.
  • implementation - An array of the implemented file converter. The first implementation will used first and if that fails, we will try the second, then the third and so on.
  • implementationConfigurations - Implementation specific configuration

This configuration only enables the file conversion on the API, not in the UI. To also enable it in the UI, you must set the convertFile property to true in the config.json file in your overlay settings folder.

Example configuration 

  "documentConversion": {
    "enabled": true,
    "availableFileSuffixes": ["doc", "docx"],
    "implementation": ["Phenix-G"],
    "implementationConfigurations": {
      "Phenix-G" : {
        "url": "https://myConverter.com/convert"
      }
    }
  }
Click to copy

Configuring Gotenberg

Gotenberg is a file conversion service that can convert to three different PDF flavours:

  • PDF/A -1B
  • PDF/A -2B
  • PDF/A -3B

You can find more information here. However, the simplest way is to use this Docker command:

docker run --rm -p 8105:8105 gotenberg/gotenberg:8.21.0 gotenberg --api-port=8105 --api-timeout=10s --log-level=debug
Click to copy

What the command does:

  • docker run — start a new container.
  • --rm — delete the container automatically when it stops. The container does not contain any critical information so it is safe to remove it. If needed, for instance for log storing, this part can be removed.
  • -p 8105:8105 — map host port 8105 → container port 8105.
  • gotenberg/gotenberg:8.21.0 — The latest Gotenberg image as of this writing.
  • gotenberg — run the Gotenberg server binary inside the container.
  • --api-port=8105 — make the API listen on port 8105 (inside the container).
  • --api-timeout=10s — set the API request timeout to 10 seconds.
  • --log-level=debug — enable debug logging.

What happens when you run it:

  • Docker pulls the image (if not found locally).
  • It creates the container and publishes port 8105.
  • It starts the Gotenberg server; logs stream to your terminal.
  • The API is reachable at http://localhost:8105/.
  • Stop with Ctrl+C; the container is removed due to --rm.

The Gotenberg implemenation in SWF needs the base route to work.