How to import listings and users from CSV data into your Webflow powered Tangram app

‍
Summary:‍

This tutorial explains how to import CSV data into a Tangerine map using the import tool or the API, with the import tool being the recommended option for most users due to its simplicity. Key steps include:

1. Using the Import Tool:
   • Log in as an admin, navigate to Settings > Integrations > Import tab.
   • Create a new import, upload your CSV file, and map spreadsheet columns to database fields.
   • Ensure email is included for creating/updating users, as it's required.
   • Run the import and refresh to check the processing status.
2. Example Imports:
   • Create new users by mapping emails and other details (e.g., display name).
   • Update users by modifying attributes like display name based on mapped fields.
   • Create new listings with required fields like user ID or listing ID for association.
3. Additional Features:
   • Use email aliasing (e.g., user+alias@example.com) for flexibility.
   • Map images via URL links in the CSV.
4. Using the API:
   • Offers more flexibility but requires custom code and lacks an undo option.
5. Undo Feature:
   • Available for imports creating new records but not for updates tied to specific IDs.

The tutorial concludes with advice to experiment safely using the undo option and invites users to reach out with questions.

Video Transcript:‍

" Today, I'm going to show you how to import CSV data into your Tangerine map. I'm going to go over a few methods. First, I'm going to start off using the import tool. And then I'm going to briefly talk about using the API. Most people will want to use the import tool to do this because it's a lot easier, but depending on your needs, the API might be a better suited for you, especially if you have developers in your team to get to the import tool.

The way that you want to do that is log into your Tangerine map as an admin, click the ranch icon, click settings integrations. And then find the import tab. That'll bring you to this import menu, which will show you a table of the imports you've run in the past and any that you want to run now. We're going to create a new one here.

We'll call it import number one. And we're going to start with roles. We'll do one role import and then we'll move on to listings next. First I'm going to attach the sample CSV I've put together. And I'm brought now to this table where I can create mappings. What a mapping is, is we're saying in our spreadsheet here, we have five columns, email, fruit, animal, user ID, and listing ID.

For each column we want to import on this import run, we want to map that to a field in our Tangram database. You can see those under the fields tab here. And I would recommend having it open in another tab so you can look at the fields while you're doing this. But for this particular import, we're doing new users first.

We want to do email for sure. To import new users, you always need an email. So we're gonna add that mapping. Now what this is saying is, for every row in this spreadsheet, find this email. If there's a user with this email, set the rest of the mappings to that value, and if there's not, then create a new user.

To better illustrate that, let me add one more column. We'll add fruit as the display name. Now what this is saying is, for every row in the spreadsheet, we're gonna find a user with the corresponding email, create it if it doesn't exist, and then set the display name to fruit. You want to go one by one through your columns in the spreadsheet and map them to fields in your Tangerine backend.

Once you've got the mapping set up correctly, you're going to want to hit run import here. And it says processing, as you can see. And you're going to want to just refresh until it's done. It takes a bit of time to run these imports, especially with more listings that are users. Could take a few minutes or longer.

Just keep checking back. And then, as you can see now, we have Three new users here, Apple, Banana, Orange, which correspond to, in the spreadsheet, we have Apple, Banana, Orange, which are the rows in the CSV. If I go into those users, we'll also see that the emails correspond to the corresponding row. This email corresponds to Apple in the spreadsheet, which it does.

What we're going to do now is, we'll go back to the imports table. And we'll do another import. This time what we'll do is instead of creating new users, we will update the users we just imported. So, we'll call this import number 2. We're gonna do role again, and we will do vendors again. We'll use the same CSV.

And this time, we'll update the display name to the animal column. We're gonna need email again, so that the system can find the corresponding user with the email. And we're going to set the spreadsheet column animal as the display name for the user. And if I run this import now, once it's done processing, we should be able to go back to the users table and see those fruit name users have now changed to animal name users.

And if I click manage on this elephant user, we would expect this to line up with the elephant user in the spreadsheet, which it does again. Apple, Elephant, and then that email. One thing you should know just about users in general is to create them you need an email. And if you don't have an email address set up for them, the way that we recommend you go about this is use plus sign aliasing for the addresses.

You can see that in action here. We have three different emails set up. All of them start with Aaron plus and then a string after that before the at sign. All of these emails are going to go to aaron at tangram. co But you can use, you can create a different account using the plus sign alias And if you don't know what that is, it might be worth googling or asking chat GPT It's not a tangram functionality, it's just something that comes with pretty much every email provider We'll go back to the imports table one more time And we will do another import now, but we'll do listings this time When you're importing listings, you have to select a listing type to import them under Each platform has different listing types set up, but For this particular one, we just have one.

For the sake of organization, you should map each CSV to one listing type. There are technically no required fields for listings. I could just import fruit and title here. And what this will do is create a listing for every row with the title fruit. So, it would create an apple, orange, and banana listing.

If I don't map a user ID, it will just create the listing under the admin account. You usually don't want that. You usually want a listing to show up under a user's account. When you want that to happen, you need to map a user ID as well. What that means is you need to have a user ID in your spreadsheet.

I have this one, Avery Thompson, which is one of the vendors on this platform. I mapped the user ID in the spreadsheet to the user ID column in the Tangerine database. If you want to update listings correspondingly to the previous user example, you would use a listing ID. You would have a column in your spreadsheet for the listing ID that you want to modify.

The way that you get these IDs for users and listings, you can either do it manually. There are a lot of ways to do this, but like the easiest one to do it manually is to go into the users table, click manage, and then copy this unique ID. You can also do it via API or via a data export, if that's easier for your particular use case.

But I have this fully set up now, so we're going to import, we're going to create new listings with the title fruit under the user ID column corresponding the spreadsheet, which is Avery Thompson. When I run this import,

it says Processing, we'll refresh, and now it's done. If we go to Avery Thompson, we should see those listings under her account.

As you can see here, we now have Apple, Banana, and Orange. The only data we set for them is the title. The rest of them are being inherited from the platform. The last thing I should cover is images. The way that you do that is in a column, you would have a link to the file you want to upload. I would add a column here called just photos and then you would use an integer.

So the way I would recommend doing this is just photos one and then having photos two. And for each of these you want to put a link to the photo for each one that you want to set the value for. If the URL is blank then it will not import the photo so you don't need to worry about it. For users you would be able to do it just by attaching directly to the avatar field.

That covers all of the import functionality. Next thing I do want to briefly touch on is using the API to Import listings and users. You can import in any way you want by using the create endpoint in your platforms API. Downside of doing it that way is you need custom code to do that. The upside of doing it that way is you're not restricted to using CSVs in particular, but if you don't have a developer, it's very hard to navigate the API.

Also, there's no undo. When you do an import via the CSV import tool, you can specifically undo it if it's creating new records. And in all the examples I've shown here that it has been creating new records. If I click undo, what it does is it just deletes all of the associated records. But if you're updating a listing or user by mapping to its ID directly, you won't be able to undo in that way.

The intended purpose of this is, let's say you're importing a thousand listings onto an account, and you want to see how they'll look. You can safely import. If you don't like the way they've turned out, you can undo, modify your CSV, and then try again. That's all the information we have around CSV imports.

Hopefully this has been helpful. If you have any questions about this, let us know in the comments below, but otherwise have a great rest of your day."

‍