Converting files

PDF is not one 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 conversion flow

Configured flavours are defined using the signingOrders.usePdfAFlavours property where administrators can set a list of all approved PDF flavours. The available flavours are:

  • PDFA_1_A
  • PDFA_1_B
  • PDFA_2_A
  • PDFA_2_B
  • PDFA_2_U
  • PDFA_3_A
  • PDFA_3_B
  • PDFA_3_U
  • PDFA_4
  • NO_FLAVOUR - Means all flavours

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.

Configuring file conversion

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

  • enabled - Whether 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 available file converters. The first implementation will be tried first, and if that fails, the second is tried, then the third, etc.
  • implementationConfigurations - Implementation specific configuration

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).
  • Docker creates the container and publishes port 8105.
  • Docker 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 implementation in SWF needs the base route to work.