Ring it Up has the ability import and export CSV (Comma Separated Values) files to and from your personal computer. The following steps should be followed when attempting to import Catalog Items, Contacts, Expense Items, or Categories from CSV based files. Sales, Purchase Orders, and Quote Transactions are NOT importable as Ring it Up was designed to be the single point of input for all transactions. This is due in large part to the complexity of the inter-relational nature of the tables used to store the transaction data. An expert could certainly accomplish the task, but the vast majority of users would have extreme difficulty so it was decided to leave this feature out of Ring it Up to best ensure the integrity of your transaction data.

Example CSV files

Requirements, Assumptions & General Rules of Thumb:

  • An application that has the ability to import and export data in a CSV format or a text editor. (e.g *Excel, *Numbers, Open Office, TextEdit, BBEdit, WordPad. *Recommended). Instructions for use of these applications are beyond the scope of this User Guide, please seek assistance from the vendor of that application.
  • Files exported by the programs listed above should be encoded in the UTF-8 encoding format. This ensures international character set compatibility. Files encoded in ASCII format should work for the standard US English character set, but international users might have difficulty with special accent characters, or monetary symbols such as the GBP symbol or the Euro Symbol when using the ASCII encoding.
  • It is assumed that you have created at least one Category, Catalog Item, Contact, and Expense Item with all applicable fields filled out. These records will act as an example of how your data should be formatted once you’ve completed
  • Each CSV file has a specific number of fields. Ring it Up will NOT attempt to import a file that does not match the number of fields it expects to see for the given CSV file, which why it is important to follow the formatting example noted in the previous assumption.
  • Pricing data should NOT contain any monetary symbols such as the Dollar, Euro, or British Pound signs. You can use those symbols in the name or description fields (any text based field).
  • No percentage based columns should contain any percent “%” symbols. For example, if your tax rate is 8.25%, then data in that column should read 0.0825. You can use those symbols in the name or description fields (any text based field).
  • Dates should be formatted in the same way as they appear in the main Expenses View.

 

Background:

  • Due to the relational nature of the way the data is stored in Ring It Up’s database, it is important to know the order in which the CSV files should be imported to achieve the best result. Some  tables in the database depend on information from other tables, so these dependencies should be imported first. The following is the order in which CSV files should be imported. If the type of data you are about to import either doesn’t reference data from another file(s), or the data already exists in the database, you may skip that CSV file, but proceed to the next in order.
  • It should be noted that before importing any CSV data file, an “Export to Dropbox” or “Create Backup Zip File” operation should be performed to get the latest snapshot of how your data currently exists. There are fields that exists in these tables that you cannot assign (Ring it Up assigns a unique primary key for every record in the database) and depending on the type of operation you are performing, you may need the most current primary key to properly add data which depends on a record in another table.
  • Please note the spelling of the file names listed below including the fact that all letters are lowercase. All files that are to be imported must have the correct filename or Ring it Up will not recognize it as an importable file and will not upload it to your iPhone/iPod Touch during the sync operation.
  1. category.csv
  2. contacts.csv
  3. expense_items.csv – depends on category.csv
  4. catalog_items.csv – depends on category.csv and contacts.csv

 

Editing your CSV files:

  1. Following file syncing methods listed elsewhere in this guide to sync your iPhone/iPod Touch with your computer to get the most recent snapshot of your data in CSV format.
  2. Locate your most recently synced CSV files and open any importable CSV file using a program capable of reading/importing CSV based files such as MS Excel, or Apple Numbers, or even a basic text editor.
  3. Assuming that you have already entered at least one record using Ring it Up, you should notice that the file you have opened contains a “Header Row” which contains the titles of each column. Leave this header row in your CSV file as Ring it Up automatically skips the first row when performing an import operation. The number of columns will vary between each CSV file, but the number of columns must never vary in the same CSV file. Some columns/fields may be empty, but the column must exist nonetheless. (Important – the last column must contain some sort of data in it, otherwise Ring it Up will incorrectly count the number of columns this row has and will skip that row during importation. In the case of Read Only columns, just enter a number zero “0”)
  4. The very first column each file, known as the “Import Action” column, is the most important column because it tells Ring it Up what you wish to do with each row of data while it is being parsed. There are four possible actions which can be performed on any given row of data (Skip, Add, Delete, Update). Each of those actions will be described below.
  5. You may combine multiple “Import Actions” in one CSV file. For example… Suppose you are editing your catalog_items.csv file which already contains 50 items and you wish to add 4 new items, update the retail price of 3 existing items, and delete 6 items, it is possible to perform all of these actions at one time by setting the “Import Action” appropriately. E.g. To add 4 items, append four rows to the bottom of the file, and edit the data for each column until those columns accurately represent the items you wish to add, then ensure the import action is set to “Add”. Now locate the items you wish to delete and set the Import Action to “Delete”. Finally, locate the items who’s prices you wish to change and set the Import Action to “Update” then edit the retail price column to set the new price. All other rows which retain the “Skip” import action will be ignored during import of your file.

Skip:

  • “Skip” is the default action assigned to every row when your data is being exported to ensure that if you accidentally tap the import button, you won’t mistakenly perform an action you did not intend. When parsing your CSV file, if the “Skip” action is encountered, this row of data in your CSV file will be skipped and no database operations will performed. The “Skip” action tells Ring it Up to keep the data contained in the database that corresponds with this row AS IS, skip it, do nothing to it, etc.

Add:

  • To add additional records to your database, add a new row to your CSV file and set the “Import Action” in the first column to “Add”. Following the previous records example, add all of the data necessary to complete this record. The second field/column normally contains the Primary Key ( a unique integer number) and will be named something like Catalog Item ID, or Category ID which identifies this record. This field’s value is set by the Ring it Up automatically during the import so any data entered in this column will be ignored. If you are adding records/rows to a CSV file that other items may depend on (like the category.csv file), you should re-export your data after importing this file before editing those other CSV files so that the correct primary key will be known when attempting to reference it.

Delete:

  • To delete existing records from your database, change the “Import Action” from “Keep” to “Delete”. Ring it Up will read the value in the second field (the primary key) and delete the record associated with that primary key. If you are deleting records/rows from a CSV file that other items may depend on (like the category.csv file), you should re-export your data after importing this file before editing those other CSV files so that the correct primary keys will be known when attempting to reference them.

 

Update:

  • If you wish to change data in an existing record, Change the “Import Action” from “Keep” to “Update”. Ring It Up will read the value in the second field (the primary key) and update the data associated with that record in the database.

 

Finishing Up:

  • Once you have finished editing your CSV file, save or export your work back to the same filename you originally opened. See the naming guidelines listed above for the exact names. Ensure that your file is exported or saved using the UTF-8 encoding format to ensure that all special characters are preserved.
  • Follow the steps listed in other chapters of this guide for sending the CSV file back to your iPhone or iPod Touch, then proceed to the following steps.
  • Assuming that the file you have uploaded is formatted correctly, Ring it Up will perform each import action for every row in the file. Once complete, Ring it Up will display an alert view stating the results of the import action. Verify your data has been correctly handled, and if not, check the formatting of your files, ensure all data is listed in it’s appropriate column and that you have properly set the import action.