Using the Vault Loader Command Line Tool


The Vault Loader Command Line tool allows you to perform all bulk create, export, update, and delete actions from the terminal. 

The process has three basic steps:

  1. Open a command line console.
  2. Use the command line tool to authenticate with your vault.
  3. Use the command line tool to load data via an input file or to export data from your vault.

Loading Basics

When you load content and data into Vault:

  • You must specify an input file in CSV format. The file extension can be CSV or TXT.
  • Input files must include all required fields and can include any additional editable fields that you wish to update.
  • Optional: You can use a mapping file to match fields in an existing data file with an input file.

Extracting Basics

When retrieving information from Vault:

  • You must specify a filename for the output file using the -csv flag. All output files are plain text and CSV-formatted.
  • Optional: You can use a “” command with specific field values to filter the items included in your extract.
  • Optional: You can specify a location for the output file. Otherwise, the file will be created in your current directory.
  • Optional: You can specify a column layout. Otherwise, the file will include all fields and their values.

Currently, the command line tool can export object records, users, and groups.

Responses

After processing a command via the command line tool, Vault creates various response files in your current directory.

  • Success log: CSV file with fields and values for successfully loaded records.
  • Failure log: CSV file with error messages for each record that failed to load.
  • Output file: CSV file with exported data.

You can use the success, failure, and export files to edit and reload records as needed.

If you are performing an action using the -async flag, you can use the following commands to retrieve status information:

Action Description
-jobstatus Use this action to retrieve status information (job ID, progress, start time, end time, etc.) for all operations that you've run via the command line tool since generating the VL-Config file.
-jobstatus <JOB_ID> Use this action to retrieve status information (progress, start time, end time, etc.) for a specific operation.
-jobresults <JOB_ID> Use this action to create a success or failure log and a text file with the job details, including progress, start time, and end time.

Getting Started

The command line tool is distributed as a single JAR file (VaultDataLoader.jar) and does not require installation. Simply download the ZIP file, extract it and run it from a command line console. You’ll need Vault Loader permissions to do this.

Download the command line tool from the Loader tab in your vault. When Vault releases new versions, you’ll need to download the latest file. Extract (unzip) the downloaded file.

Verify that you have installed Java JDK V7 or higher. If not, download the latest version.

Recommended: Create a local directory for Vault Loader-related files. This can help you keep track of various files:

  • Command line tool(VaultDataLoader.jar)
  • Vault DNS and authentication information(vl-config.xml)
  • CSV input files
  • CSV success and failure logs
  • CSV or TXT export files

Command Line Arguments

A command line argument is a parameter passed to Vault Loader. When using Vault Loader, arguments include both commands that define what operation to perform, like -updateroles, and modifiers for that operation, like _-all _to specify that a delete operation would affect all object records or -csv filename.csv to indicate that Vault Loader should create records based on the information in the specified CSV file.

A full list of arguments is available via the command line tool using the argument -h or --help.

Authentication & VL-Config Files

Before running any other commands, use your Vault username and password to authenticate with your vault:

java -jar VaultDataLoader.jar -username steve@veepharm.com -password p@$$w0Rd -dns https://veepharm.veevavault.com

The first time that you run this command, the command line tool creates the file vl-config.xml which saves your DNS and username for future commands. If you work with multiple vaults or multiple user accounts, you must delete this file and re-run the authentication command each time you switch vaults or switch users.

To authenticate, you must have a security profile that grants the Vault Owner Actions: Vault Loader and API: All API permissions.

Users


Create Users

This action creates new users using details from the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-createusers -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar -createusers -csv user_onboarding.csv
-m vault_vph_fields.csv

Update Users 

This action updates details for existing users using the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-updateusers -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar -updateusers 
-csv user_update.csv
-m vault_vph_fields.csv

Upsert Users 

This action creates new users and updates details for existing users using the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-upsertusers -csv <CSV>
-m <MAPPING>
-idParam <FIELD>
java -jar VaultDataLoader.jar -upsertusers 
-csv user_update.csv
-m vault_vph_fields.csv

Export Users

This action exports user metadata.

Action Parameters Example
-exportusers -csv <CSV>
-columns <FIELD>
-where <WHERE>
-headers
-noneditable
java -jar VaultDataLoader.jar -exportusers 
-csv users_12-15-15.csv
-noneditable
-where "active__v='false'"
java -jar VaultDataLoader.jar -exportusers
-csv users_names.csv
-columns first_name__v,last_name__v

Groups


Create Groups

This action creates new groups using details from the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-creategroups -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar -creategroups
-csv group_import.csv
-m vault_vph_fields.csv

Update Groups

This action updates existing groups using details from the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-updategroups -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar -updategroups
-csv group_update.csv
-m vault_vph_fields.csv

Upsert Groups

This action updates existing groups using details from the CSV file you provide. Before starting, prepare the CSV input file.

Action Parameters Example
-upsertgroups -csv <CSV>
-m <MAPPING>
idParam <FIELD>
java -jar VaultDataLoader.jar -upsertgroups
-csv group_import.csv
-m vault_vph_fields.csv

Export Groups

This action exports group metadata.

Action Parameters Example
-exportgroups -csv <CSV>
-columns <FIELD>
-headers
-noneditable
java -jar VaultDataLoader.jar -exportgroups 
-csv groups_2015.csv
-noneditable

Object Records


Create Object Records

This action creates new object records for a specific object. Before starting, prepare the CSV input file.

Action Parameters Example
-create <OBJECT NAME> -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar
-create product__v
-csv new_prods.csv
-m vault_vph_fields.csv

Update Object Records

This action updates existing object records with data from the provided file. Before starting, prepare the CSV input file.

Action Parameters Example
-update <OBJECT NAME> -csv <CSV>
-m <MAPPING>
java -jar VaultDataLoader.jar
-update product__v
-csv update_prods.csv
-m vault_vph_fields.csv

Upsert Object Records

This action updates existing object records or creates new records from the provided file. Before starting, prepare the CSV input file.

Action Parameters Example
-upsert <OBJECT NAME> -csv <CSV>
-m <MAPPING>
-idParam</p>
java -jar VaultDataLoader.jar
-upsert product__v
-csv update_prods.csv
-m vault_vph_fields.csv
-idParam external_id__v

Export Object Records

This action exports record metadata for a specific object.

Action Parameters Example
-export <OBJECT NAME> -csv <CSV>
-where <WHERE>
-columns <FIELD>
-headers
-noneditable
java -jar VaultDataLoader.jar
-export product__v
-csv prod_exp.csv
-where "name__v like 'Ad%'"
-columns name__v
java -jar VaultDataLoader.jar
-export product__v
-headers

Delete Object Records

This action deletes existing object records identified in the CSV file. If deleting specific records, prepare the CSV input file. If deleting all records, you don’t need to provide an input file.

Action Parameters Example
-delete <OBJECT NAME> -csv <CSV>
-all
java -jar VaultDataLoader.jar
-delete product__v
-csv prods_to_delete.csv
java -jar VaultDataLoader.jar
-delete product__v
-all

Parameters

The following parameters must be used with other arguments to modify how Vault processes a command:

Parameter Description
-all Use this flag with a delete action to indicate that the action should affect all records of the specified object.
-async Use this flag with any action to complete the operation asynchronously. With this flag, you will be able to immediately start a new operation. The command line tool will not display status messages on asynchronous operations, but will immediately return a job ID that enables you to later check the status.
-where <WHERE> Use this flag with an export action to limit the export based on a VQL query, for example, "product__v='wonderDrug'". The WHERE clause VQL query must be under 2,000 characters.
-headers Use this flag with an export action to export only field names as column headers. This can help you to create a template for CSV input files.
-columns <COLUMNS> Use this flag on an export action by specifying field names to limit the export to only those fields. Note that you cannot have spaces between columns names when specifying columns with the '-columns' flags.
-noneditable Use this flag on an export action to extract both editable and read-only fields. Note that including non-editable fields means that you cannot use the export as a template for CSV input files.
-idParam <FIELD> Use this flag on an upsert action to specify that items are identified in the CSV input file via an external ID, rather than the ID field.
-includefields Use this flag with a load action to specify that Vault should include the input fields in the output success log.