---
title: "Getting Started with the VDP Tool"
canonical: https://customerscanvas.com/docs/cc6/vdp-tool.htm
archived: true
applies_to:
  - product: "Customer's Canvas On-Premises"
  - product: "Design Editor"
    versions: ["6.15.0", "6.x (may differ)"]
---

**You’re viewing outdated documentation.** [View the latest Customer’s Canvas On-Premises documentation](https://customerscanvas.com/docs/on-premises/).

# Getting Started with the VDP Tool

**Applies to:** Customer's Canvas On-Premises; Design Editor 6.15.0, 6.x (may differ) · **Archived documentation**
 
The VDP Tool is a command-line utility and uses the [Web API for Personalized Rendering](https://customerscanvas.com/docs/cc6/web-api-for-rendering.htm.md) under the hood. You can download this utility from [your account↗](https://customerscanvas.com/account/licenses). If not, please contact our [support team↗](https://customerscanvas.com/account/cases/add).
 
## 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 and [registered a license key](https://customerscanvas.com/docs/cc6/registering-production-license-keys.htm.md) (a trial or a permanent one).
 
This utility requires [Microsoft Visual C++ 2017 Redistributable Package (x64)↗](https://aka.ms/vs/15/release/vc_redist.x64.exe).
 
## 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.
 
### Configuration
 
When you open the `AppSettings.config` file in a text editor, you can see the following parameters.
 
```
<appSettings>
  <add key="OutputPath" value="./"/>
  <add key="CombineFiles" value="false"/>
  <add key="FileNameTemplate" value="{state}_{index}.pdf"/>
  <add key="AssetStorageUrl" value="url_to_asset_storage" />
  <add key="AssetStorageApiKey" value="asset_storage_api_key" />
  <add key="AssetProcessorUrl" value="url_to_asset_processor" />
  <add key="AssetProcessorApiKey" value="asset_processor_api_key" />
  <add key="TokenUrl" value="url_to_token_service" />
  <add key="TokenClientId" value="token_service_client_id" />
  <add key="TokenClientSecret" value="token_service_client_secret" />
</appSettings>
```
 
Here, you need to modify parameters of the Asset Storage and Asset Processor:
 
- **AssetStorageUrl** - the domain name or local address of your storage. For example, `"https://assetstorage.example.com"`.
- **AssetStorageApiKey** - the API Key of your storage, a unique string.
- **AssetProcessorUrl** - the domain name or local address of your Asset Processor. For example, `"https://assetprocessor.example.com"`.
- **AssetProcessorApiKey** - the API Key of your Asset Processor, a unique string.

When you access your local services, you can use **AssetStorageApiKey** and **AssetProcessorApiKey**. To use assets from remote BackOffice, you first need to create an external app and obtain its **clientId** and **clientSecret**.
 
- **TokenUrl** - the endpoint for generating tokens in BackOffice. For example, `"http://backoffice.example.com/connect/token"`.
- **TokenClientId** and **TokenClientSecret** - the pair of string values that you can obtain in your tenant control panel.

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 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 `Aurigma.DesignAtoms.config` file.
4. Specify the absolute path to the font folder in the **FontDirectory** key, for example: 
```
    <add key="FontDirectory" value="C:\vdp\fonts" />
    ```

Other settings in `Aurigma.DesignAtoms.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
  
Before 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 the following:
 
1. You have installed this tool at `C:\vdp`.
2. You want to download the state with ID **8fed5bc0-4e92-4c9e-b489-afa3a4322a2e** from a user named **john**.
3. This user belongs to the tenant with ID **2**.

Run this tool with following parameters:

```
C:\> cd C:\vdp
C:\vdp> vdp -s 8fed5bc0-4e92-4c9e-b489-afa3a4322a2e -u john -t 2 -m online
```
 
Note that you can omit the **-t** key when using authorization with tokens, since a token already contains a tenant ID.
 
As a result, this utility renders the personalized product.
 
![Rendered personalized product.](https://customerscanvas.com/docs/cc6/images/VDPToolHiRes.png)
 
### 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
 
- [Variable Data Printing](https://customerscanvas.com/docs/cc6/variable-data-printing.htm.md)
- [Web API](https://customerscanvas.com/docs/cc6/webapi.htm.md)