Anyone who works with CSVs knows they are, let’s say… finicky. And if you've never worked them, you may be asking yourself "What's a CSV?".
Please don’t hesitate to reach out if you’d like some help downloading, formatting, or uploading a CSV.
General CSV Information
A CSV is a comma-separated values file. CSVs can be viewed in spreadsheet format, with columns and rows, or as lines of plain text, wherein each data element is separated by a comma (for example: title,artist,date).
To help you get started, the MOON Object System generates helpful, downloadable CSVs based on the fields in your Blueprints.
It's best to upload a CSV with object data for a single Blueprint type. For example, if you’d like to add a group of 20 oil paintings, you’d upload the new object information using the CSV template for your "Paintings" Blueprint.
Our CSV upload is limited to 500 objects at a time.
If you’re uploading more than 500 objects, you’ll need to upload multiple CSVs.
The CSV must be encoded in UTF-8 format.
PLEASE NOTE: To preserve special characters like diacritics in a CSV, we recommend viewing, updating, or exporting using Google Sheets, Apple Pages, Airtable, or a plain text editor. Microsoft Excel may not preserve special characters.
Downloading a Blueprint’s CSV Template
The first step to uploading a group of new objects is to download a handy CSV template for your Blueprint. There are two ways to do this.
From your selected Blueprint, expand the action menu at far right. Select Download CSV Template.
Or, from your Objects page:
- Filter objects by the selected Blueprint. In this example, we’ll choose Paintings.
- Icons for uploading and downloading will appear at right. Click the downward pointing arrow.
You’ll be asked if you need the Blueprint CSV Template. Click to download it.
Import New Objects Using a Blueprint’s CSV Template
The first line in the CSV template (the column headings) will correspond to the field ids in your selected Blueprint. DO NOT alter these headings.
The template will also display the Blueprint Name and the Blueprint ID in the first row.
Now it's time to add your object information values to the CSV template. Remember we mentioned CSVs are finicky?
These rules MUST be followed:
Add the name of your Blueprint and the Blueprint ID for every object you add.
Every object must have a title.
If a row has data, there cannot be any empty fields in that row. You must add a hyphen in an empty field to preserve order (see the two highlighted fields with hyphens).
You can view the CSV and add data in spreadsheet format (recommended) or with a plain text editor. Notice the hyphens below.
When you've entered all the information for your new objects, save your CSV, and go back to the Objects page. Filter your objects by the same Blueprint.
Click on the upload icon (the upward facing arrow) to import. Click Upload your CSV.
You’ll receive a message letting you know the objects were added successfully.
PLEASE NOTE: When you upload a CSV with new objects, make sure to upload it only once – otherwise duplicate objects will be created.
Add, Update, and Delete Objects Using a Blueprint’s Object Data CSV
To edit information for a group of objects (with the option of adding new ones), go to the Objects page and filter your objects by the desired Blueprint. Then click on the download option for that Blueprint.
You’ll be given an option to download the Object Data for the Blueprint as JSON or CSV. Choose Download CSV.
The CSV will include your existing object data for all objects using that Blueprint. In this example, five objects use the Paintings Blueprint.
The column headings will correspond to the field ids in your selected Blueprint. DO NOT alter these headings.
The CSV will display the unique Object IDs for each object (in the oid column). DO NOT alter the oids.
The CSV will also include an ostatus column (more on this later).
Where there are no information values, hyphens are automatically inserted.
Adding a New Object
If you add new objects, remember that you must enter a hyphen in any empty fields (for example, oid and ostatus). Here we're adding a row for an object titled A Vase of Flowers. Because it's a new object, it will not have an object id (oid). Remember, every object must have a title.
Updating Object Information or Deleting an Object
To update or delete an object, you'll enter information in the object's object status (ostatus) field.
To update information, enter the word update (lowercase) into the object's ostatus field, and add the updated information for that object.
To delete an object, enter the word delete (lowercase) in the object's ostatus field.
PLEASE NOTE: For all other objects, make sure there are hyphens in the ostatus fields.
When you've updated the information in your CSV, save and upload it. For rows with data, make sure you don’t have any empty fields.
PLEASE NOTE: When you upload a CSV with new objects, make sure to upload it only once – otherwise duplicate objects will be created.
You’ll receive a message letting you know the objects were added and/or deleted successfully.
Questions about CSVs? Don't hesitate to contact us.