> ## Documentation Index
> Fetch the complete documentation index at: https://help.csvbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Virtual Columns
> Create new columns by applying custom data transformation logic.
**Virtual Columns** are one of CSVbox's most powerful data transformation tools. They run small snippets of JavaScript that **merge**, **split**, **re-format**, **correct**, and **enrich** incoming data during an import.
Use them to process your data, do calculations, or merge values together before the data reaches your end.
## How it works
For any sheet (template), add a virtual column in the CSVbox dashboard.
Attach a JavaScript snippet to the virtual column.
After users submit the CSV file, the JavaScript runs to populate data in the virtual columns.
Data from the uploaded CSV and the virtual columns is pushed to the data destination.
### Example
Merge data from the `first_name` and `last_name` columns into a new virtual column named `full_name`.
Here is the JavaScript attached to the `full_name` virtual column:
```javascript theme={null}
try
{
return csvbox.row["first_name"] + ' ' + csvbox.row["last_name"];
}
catch(err)
{
return 'error: ' + err.name + ' | ' + err.message;
}
```
Normalize the incoming `order_date` into UTC format.
```javascript theme={null}
try
{ const date = new Date(csvbox.row["order_date"]);
return date.toUTCString();
}
catch(err)
{
return 'error: ' + err.name + ' | ' + err.message;
}
```
Pass any static value to the virtual column.
```javascript theme={null}
try
{
return 'Amazon';
}
catch(err)
{
return 'error: ' + err.name + ' | ' + err.message;
}
```
## Adding virtual columns
Go to the edit sheet page → **Columns** tab, and click the **Add Virtual Column** button.
Add the virtual **Column Name**.
Enter the **Javascript** code.
Attach **Dependent** libraries.
Click **Save**.
## Data rows
Data rows are the core object that virtual columns are built around. For each incoming CSV data row, you can read its data and manipulate it with JavaScript to populate the virtual column.
After the user submits the CSV, the JavaScript runs for each data row in sequential order to populate the virtual columns.
Use the `csvbox.row` object to work with each row, and `csvbox.row["column_name"]` to read a specific column of the data row. You can use data from a single column, multiple columns, or no columns to populate virtual columns.
## Inserting data into virtual columns
The value returned by the JavaScript snippet is added to the virtual column.
```javascript theme={null}
// Extracting first name
try
{ var fullName = csvbox.row["full_name"].split(' ');
// returning value
return fullName[0];
}
catch(err)
{
//returning error
return 'error: ' + err.name + ' | ' + err.message;
}
```
If the JavaScript returns a `NULL` value, an empty string is added to the virtual column.
## Receiving virtual data
Virtual column data is available at all data destinations along with the data from the regular columns.
In the API response JSON object, the virtual data appears inside the `_virtual_data` object, as shown below. The `_virtual_data` object is visible only if virtual columns are added to the sheet. In the example below, check lines 12 and 31.
```json lines theme={null}
[
{
"import_id": 79418895,
"sheet_id": 55,
"sheet_name": "Products",
"row_number": 1,
"row_data": {
"Name": "TP-Link TL-WN822N Wireless Adapter",
"SKU": "AS-100221",
"Price": "33.00",
"Quantity": "3",
"_virtual_data":{
"SKU_prefix": "AS",
"Compare_Price": "43.00"
}
},
"custom_fields": {
"user_id": "1002"
}
},
{
"import_id": 79418895,
"sheet_id": 55,
"sheet_name": "Products",
"row_number": 2,
"row_data":{
"Name": "EPower EP-600PM Power Supply Cooling Fan",
"SKU": "SS-103824",
"Price": "95.35",
"Quantity": "8",
"_virtual_data":{
"SKU_prefix": "SS",
"Compare_Price": "105.35"
}
},
"custom_fields": {
"user_id": "1002"
}
},
]
```
Virtual columns are available in the column mapping modal. You can push virtual columns to any receiving data field of your choice.
In the AWS S3 file store, virtual columns are added as new columns in the uploaded file.
The virtual data is also available on the [client-side JSON object](/getting-started/3-receive-data#data-on-the-client-side).
## Dependencies
In the JavaScript snippet, you can use an external library hosted on a CDN. You can also call any external API endpoint to fetch real-time data. Add the library script tag and any custom scripts to the **Dependencies** section, then use them in the main JavaScript snippet.
For each import, the dependent scripts run only once, whereas the main JavaScript snippet runs once for each row.
Suppose you want to use the data from the incoming `USD_amount` column to create a new `GBP_amount` virtual column. The amount should be converted from USD to GBP using real-time exchange rates.
You can use the [Money.js](https://github.com/openexchangerates/money.js) library for currency conversions and [Open Exchange Rates](https://openexchangerates.org/) to fetch real-time conversion rates. Here is the sample dependency code:
```javascript Dependent Scripts theme={null}
//Load jQuery via CDN
//Load Money.js via CDN
//Fetch real-time conversion rates via ajax call and initialize fx object
```
Corresponding JavaScript snippet for the `GBP_amount` virtual column:
```javascript Javascript snippet theme={null}
try
{
//USD to GBP
return fx.convert(csvbox.row["USD_amount"], {from: "USD", to: "GBP"});
}
catch(err)
{
//returning error
return 'error: ' + err.name + ' | ' + err.message;
}
```
## Variables
In the virtual column JavaScript snippet, you have access to data variables in the `csvbox` object. The following data is available:
### `csvbox.row`
Contains the row data. Access each cell in the row by providing the column name. Examples:
```javascript theme={null}
csvbox.row["first_name"]
csvbox.row["order_id"]
csvbox.row["price"]
```
The column name must exist on the sheet, or an error is thrown.
### `csvbox.user`
Contains the [custom user attributes](/getting-started/2-install-code#referencing-the-user) defined while initializing the importer. Examples:
```javascript theme={null}
csvbox.user["user_id"]
csvbox.user["team_id"]
csvbox.user["isAuthenticated"]
```
### `csvbox.import`
Contains data specific to the current import. The following data is available:
```javascript theme={null}
csvbox.import["sheet_id"]
csvbox.import["sheet_name"]
csvbox.import["original_filename"]
csvbox.import["import_start_time"]
csvbox.import["destination_type"]
csvbox.import["total_rows"]
csvbox.import["row_number"] //current row number starting with 1
```
### `csvbox.virtual`
Contains data from the preceding virtual columns.
```javascript theme={null}
csvbox.virtual["final_name"]
csvbox.virtual["age"]
```
Only data from the virtual columns defined before the current virtual column is available for use.
### `csvbox.environment`
Contains the [environment variables](/advanced-installation/environment-variables) passed during importer initialization.
```javascript theme={null}
// Example Usage
if(csvbox.environment["user_id"] && csvbox.environment["user_id"] == "abc123") {
// code
}
```
Use `console.log(csvbox);` to print all the available variables in the debugging console.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.