Upload and Map a CSV File

This screen lets you upload a CSV file to BillingBot and tell it which column in the file corresponds to which invoice data (company, product, quantity, cost, etc.). It is used at two distinct points within Universal CSV: the first time you set up a file format (when creating a new integration), and every following month, when you upload the period's charges.

When to use this screen

• When you need to set up a new CSV file format (for example, a distributor that sends you their charges in a proprietary file format that BillingBot does not yet recognize).
• When you already have a CSV integration set up and it's time to upload the charges for the corresponding month.

What it shows

• Load File CSV window: a box for choosing the file (Browse or drag and drop) and the Send Data button.
• If the file has issues, an errors panel (red background) or warnings panel (yellow background) appears with the details of what BillingBot found in the file.
• Once the file passes review, a preview table is shown with the file's data broken out into columns.
• Field mapping panel (on the left side of the integration screen): here you specify, field by field, which column in the file corresponds to each piece of data BillingBot needs:
  • Source Company Id
  • Source Company Name
  • Source Product Id
  • Source Product Name
  • Quantity
  • Unit Cost
  • Unit Price (optional)
  • Total
• Each of these fields shows, while you map, a dropdown list with the column names detected in your file, so you can select the one that matches (you can type to filter it). Once saved, the field shows the chosen column. If a required field is left empty when you click Create Integration, it is marked in red.
• Above the mapping panel you'll also see Integration Name, Delimiter (the separator character, such as "," or ";"), and File Name (the name of the uploaded file).

Available actions

• Browse / drag file: select the CSV file from your computer.
• Send Data: processes the file and shows the preview in the table. If the file has formatting errors, this button remains disabled until you upload a corrected file.
• Create Integration: saves the field mapping as a new CSV integration. This only appears the first time, when you are setting up the file format.
• Save Charges ⚠️: records the charges for the selected period in BillingBot. This is the action that confirms the monthly upload; once saved, the charges become available to invoice.
• Load CSV (green button on the main Universal CSV screen): opens this window to upload the month's file for an existing integration.
• Delete (red button on the main screen) ⚠️: completely removes the selected CSV integration record. Asks for confirmation before deleting.

Step-by-step flow

First time: creating a new CSV integration

1. In the Universal CSV menu, click New Integration.
2. Enter a Integration Name (a name to identify this file format) and the Delimiter (the character that separates the columns in your file, usually "," or ";").
3. Click Load CSV. The "Load File CSV" window opens.
4. Use Browse (or drag the file) to choose your CSV file.
5. Check that no errors appear. If everything is fine, you'll see the table with the file's data.
6. Click Send Data.
7. The window closes and the mapping panel appears. For each field (Source Company Id, Source Company Name, Source Product Id, Source Product Name, Quantity, Unit Cost, Total, and optionally Unit Price), select the corresponding column from the dropdown list.
8. Click Create Integration to save the format. From now on, this integration is ready to be used every month.

Every month: uploading the period's charges

1. In the Universal CSV menu, locate the integration record in the list on the left.
2. Before uploading the file, set the Period field (top right) to match the month you're loading. This step is important: if the period is selected incorrectly, the charges will be recorded in the wrong month.
3. Click the green button for that integration (Load charges).
4. Choose the month's file with Browse and confirm with Send Data.
5. Review the data preview.
6. Click Save Charges to record the period's charges in BillingBot.
7. To review and invoice those charges, go to the Ready To Invoice menu, select the "Imports CSV" integration, the corresponding period, and, very important, the same CSV integration record under which you uploaded the data. From there, invoices are processed the same way as with any other integration.

Common errors and how to resolve them

• "The CSV integration does not have a delimiter configured...": the separator character has not been set before uploading the file. Go back to the integration and fill in the DelimiterField (for example "," or ";") before trying to upload again.
• "The file is empty or does not contain a valid header row.": the file has no data or the first row with column names could not be read. Verify that the file is not empty and that the first row has the headers.
• "The file header has no columns. Verify the delimiter is correct.": the configured separator likely does not match the one used in your file. Check whether the file uses "," or ";" and adjust the DelimiterField.
• "Duplicate column header found: ...": there are two columns with the same name in the file. Each column must have a unique name; fix it in your CSV editor and upload the file again.
• "Row ...: has ... columns but the header defines ...": a row in the file has more or fewer values than the header specifies. Check that row in your CSV editor (a comma may be missing or an extra separator may be present).
• "The file has a header but contains no data rows." / "The file has a header but all data rows are empty.": the file only has headers, with no information to load. Verify that the exported file actually includes the charges.
• "Error! Incomplete company id data" (and similar messages for company name, product id, product name, Quantity, Unit Cost, Total): the corresponding column has not been selected in the mapping panel yet. Check that all required fields have a column assigned (Unit Price is the only optional one).
• Blank rows: if the file contains blank rows, BillingBot detects and skips them automatically; you'll see the notice "... empty rows were found and will be automatically skipped during import.", and no correction is needed.
• "... Halo item(s) created because "Create products automatically" is on ...": the import made those items in HaloPSA because no Halo item has the same name as those products (the CSV import matches by name only; this includes products BillingBot already had but never mapped). There is no preview for the CSV import, so this notice is how you see what was written to Halo. If you did not want an item created, turn the option off in Settings Integration and map the product by hand in Map Products.
• "... charge(s) were imported with a unit price of 0 ...": the file has no selling price for those charges (typically a cost-only export) and their product has no Price Override, Margin Override or Use Halo Price, so HaloPSA would bill them at 0. The notice lists the products. Before sending, turn on Price Override or Use Halo Price for those products in Map Products, or edit the unit price of the charges in Ready To Invoice. Charges that are excluded, Track Cost Only or have no quantity are not listed.

Related screens

• Universal CSV
• Ready To Invoice
• Integrations