Configuring PDF Conversion for CloudBlue Commerce 21.0
Original Publishing Date:
2021-10-18
TABLE OF CONTENTS
Overview
This article describes how to configure PDF conversion for CloudBlue Commerce 21.0.
You need to perform the instructions of this article because:
- In CloudBlue Commerce 20.5, due to security reasons, the ability to customize PDF conversion commands in the UI was disabled. As a result, you can customize which PDF converters are used and how PDF conversion is performed by updating the /usr/local/bm/bin/pdfconversion.sh and /usr/local/bm/bin/pdfmassconversion.sh scripts located on the BSS application node.
- In CloudBlue Commerce 21.0, the deployment model became cloud-native, meaning that CloudBlue Commerce is deployed in a Kubernetes cluster as a set of components. As a result, the way of configuring and customizing PDF conversion was noticeably changed.
Preconditions
Before upgrading your installation to CloudBlue Commerce 21.0, go to System > Settings > Notifications > PDF Conversion Settings and make sure that the PDF Conversion Command and PDF Conversion Command for Mass Printing settings are set to their default values (/usr/local/bm/bin/pdfconversion.sh "@@SrcName@" "@@DstName@" and /usr/local/bm/bin/pdfmassconversion.sh "@@SrcName@" "@@DstName@"). If these settings have custom values, you must move your customizations to the pdfconversion.sh and pdfmassconversion.sh scripts and reset these settings to their defaults by clicking the Reset To Default button.
Configuration
After upgrading to CloudBlue Commerce 21.0, all your customizations will be discarded, and your installation will use the following default configuration for PDF conversion:
pdfconversion.sh and pdfmassconversion.sh:
wkhtmltopdf --disable-javascript --header-left [section] --header-font-size 8 --header-right "Page [page] of [toPage]" --page-size A4 --orientation portrait --encoding utf-8 -B 5 -L 5 -R 5 -T 5 $SrcName $DstName
If this configuration does not meet your requirements, you have the following options to adjust how PDF conversion is performed and which PDF conversion tools are used:
Option 1: Use a Custom PDF Conversion Tool Placed on the Persistent Volume of the BSS Component
Prepare a custom PDF conversion tool. For simplicity, let us assume that it is a binary file named customconverter.
Prepare new scripts pdfconversion.sh and pdfmassconversion.sh, where each script invokes customconverter with the required parameters. For example:
#!/bin/sh
SrcName="$1"
DstName="$2"
customconverter -parameter value $SrcName $DstName
Place customconverter, pdfconversion.sh, and pdfmassconversion.sh to the /k8s_data/customization_bin/ directory of the conf-volume persistent volume used by the BSS component. For example:
export NS=NAMESPACE_OF_YOUR_CBC_INSTALLATION
bss_worker=`kubectl get pod -l stellart=worker -n $NS -o name | head -1 | sed -e 's#pod/##'`
kubectl cp pdfconversion.sh $bss_worker:/k8s_data/customization_bin/ -n $NS
kubectl cp pdfmassconversion.sh $bss_worker:/k8s_data/customization_bin/ -n $NS
kubectl cp customconverter $bss_worker:/k8s_data/customization_bin/ -n $NS
Recreate the pods of the BSS component. For example:
kubectl delete pod -l app=bss -n $NS
As a result, the BSS component will start using the new configuration for PDF conversion.
Important: When placing the binaries of a custom PDF converter tool on the persistent volume, you must take into account all necessary libraries of those binaries and their compatibility with the OS of the images used by the BSS component.
Option 2: Use a Standalone PDF Conversion Service
Prepare the API URL and credentials of a standalone PDF conversion service. For instance, you can use an online service such as Pdfcrowd, or a service deployed on a server or in a Kubernetes cluster located in your datacenter.
Make sure the API of the service is accessible from your Kubernetes cluster.
Prepare new scripts pdfconversion.sh and pdfmassconversion.sh, where each script makes calls to the API of the service with the required parameters. For example:
#!/bin/sh
SrcName="$1"
DstName="$2"
curl -f -u demo:ce544b6ea52a5621fb9d55f8b542d14d -o $DstName -F "file=@$SrcName" https://api.pdfcrowd.com/convert/
Place your pdfconversion.sh and pdfmassconversion.sh to the /k8s_data/customization_bin/ directory of the conf-volume persistent volume used by the BSS component. For example:
export NS=NAMESPACE_OF_YOUR_CBC_INSTALLATION
bss_worker=`kubectl get pod -l stellart=worker -n $NS -o name | head -1 | sed -e 's#pod/##'`
kubectl cp pdfconversion.sh $bss_worker:/k8s_data/customization_bin/ -n $NS
kubectl cp pdfmassconversion.sh $bss_worker:/k8s_data/customization_bin/ -n $NS
Recreate the pods of the BSS component. For example:
kubectl delete pod -l app=bss -n $NS
As a result, the BSS component will start using the new configuration for PDF conversion.
Important: When using a standalone PDF conversion service, make sure that all items of HTML files of your documents such as images, styles, and scripts are either included in those HTML files or are accessible from that service.