The VDP Client

The VDP Client is a command line utility that should be used along with the Customer's Canvas web-to-print editor to handle the Variable Data Printing scenario. We provide a Customer's Canvas Proxy (a JS application) that allows your users to create designs and upload their data as an XLS file. This utility allows you to implement the following workflow:

  • When your users save their design and data at a Customer's Canvas server, you receive identifiers of the design and the user who created the design (stateId and userId, respectively).
  • You save the stateId and userId in your database/orders/etc.
  • Your staff who fulfill orders have this vdp.exe utility installed. They simply run it and pass stateId and userId through the command line interface.
  • This utility downloads the design and data from the Customer's Canvas server and generates printable PDF files.

Prerequisites

It is assumed that you have already installed Customer's Canvas on your server or obtained access to an instance hosted by our servers.

Also, you need to run the Customer's Canvas Proxy, which saves a design and user's data on the Customer's Canvas server.

This utility requires Microsoft Visual C++ 2017 Redistributable Package (x64).

To get the Variable Data Printing demo application, please contact our support team.

How to set up vdp.exe

Installation

To install this utility, unzip the package to a folder on your computer where it is convenient to run it from a command line.

After that, you need to add a license key (a trial or a permanent one). Copy the Aurigma.GraphicsMill.lic file to the lib folder. If the license key is not enclosed in the package, contact our support team or your contact person at Aurigma to obtain it.

Configuration

When you open the AppSettings.config file in a text editor, you can see an XML file like this:

<appSettings>
  <add key="CustomersCanvasUrl" value="https://URL_TO_YOUR_CUSTOMERS_CANVAS_INSTANCE" />
  <add key="CustomersCanvasApiKey" value="YOUR_API_KEY_FOR_CUSTOMERS_CANVAS" />
  <add key="CombineFiles" value="false"/>
  <add key="OutputPath" value="./"/>
  <add key="FileNameTemplate" value="pdf/{state}/{index}_{data.Person Name}.pdf"/>
</appSettings>

Here, you need to modify the first two values:

  • CustomersCanvasUrl - the URL to your Customer's Canvas instance.
  • CustomersCanvasApiKey - the API key you specified in AppSettings.config of Customer's Canvas as described in the Web API topic.

Also, you may want to configure output files:

  • CombineFiles - if true, the utility will create a multipage PDF file (one page = one record); if false, it will create a separate PDF file for each row of data.
  • OutputPath - a root location of output PDF files.
  • FileNameTemplate - an output file name template.

In these settings, you can use the following placeholders:

  • {state} - the current state Id.
  • {index} - the number of the current row in a dataset (starting with 1), ignored if CombineFiles is true.
  • {date} - the current date (formatted as yyyy.mm.dd)
  • {data.PROPERTY_NAME} - the value of the PROPERTY_NAME column in the current row, ignored if CombineFiles is true.

For example:

<add key="OutputPath" value="./pdf/"/>
<add key="FileNameTemplate" value="{date}/{state}/{index}_{data.Company}.pdf"/>

This will create the following file structure:

.
   \pdf
      \2018.11.01
         \b3c6f043-8127-4163-9dcd-34301999acc8
            \1_Acme.pdf
            \2_Northwind.pdf
            ... 

In this way, you can organize your orders in a structure that is easy to navigate and understand.

Fonts

When you allow your customers to use fonts that are not installed on the machine where the vdp.exe tool is running, it is very important to specify the location of the fonts.

To set up fonts:

  1. Download the fonts from your Customer's Canvas instance.
  2. Save them in a subfolder, for example, the fonts folder in the folder containing vdp.exe.
  3. Open the VectorObjects.config file.
  4. Specify the absolute path to the font folder in the FontDirectory key:
    <add key="FontDirectory" value="C:\vdp\fonts" />
    

Other settings in VectorObjects.config should be the same as in the appropriate config of Customer's Canvas.

Environment variables

If you like, you can add the location of the vdp.exe file to the PATH environment variable of your system. It will allow you to run vdp.exe from any location (not just the folder where you install it).

You can perform this optional operation as follows:

  1. Right-click My PC in Windows Explorer.
  2. Choose Properties.
  3. Click Advanced system settings.
  4. Click the Environment Variables button.
  5. Double click Path either in User variables or System variables. In the former case, it will work only for a current user, in the latter case - globally, for all users on this machine.
  6. Click Edit and add the path to the folder where vdp.exe is located to the end of this list.
  7. Restart the command line session to have changes to go into effect.

How to use vdp.exe

Prior to using vdp.exe, you (or your users) need to create a design, upload some data and save a state file. As a result, you will have two pieces of data - stateId and userId.

After that, you can proceed in two ways:

  1. Pass the obtained stateId and userId to this utility. It will download and process them automatically (the online mode).
  2. Download the state file yourself, place it near vdp.exe and pass its name to the utility (the local mode).

Online mode

Let's assume you have installed this tool at C:\vdp. You want to download the state with id 8fed5bc0-4e92-4c9e-b489-afa3a4322a2e from a user named john.

Run this tool with following parameters:

C:\> cd C:\vdp
C:\vdp> vdp -s 8fed5bc0-4e92-4c9e-b489-afa3a4322a2e -u john -m online

As a result, this utility renders the personalized product.

Rendered personalized product.

Local mode

Let's assume you have installed this tool at C:\vdp, downloaded a state file as 8fed5bc0-4e92-4c9e-b489-afa3a4322a2e.st, and placed this file in the C:\downloads folder.

Run this tool with following parameters:

C:\> cd C:\vdp
C:\vdp> vdp -s ..\downloads\8fed5bc0-4e92-4c9e-b489-afa3a4322a2e.st -m local

Note, you can omit the -m local key, as the local mode is the default.

Suppress output

If you don't want this tool to output the results, you can turn off the verbose mode by adding the -v false key.

Help

Just run the tool without any arguments or pass the --help key. To get a version, pass the --version key.

See Also

Manual