Using the Kustomer CSV Upload Tool

Using the Kustomer CSV Upload Tool

Written by: Michael Iacono, Technical Support Engineer @ Kustomer

There are many use cases that our CSV upload tool (web address: https://kustomer-csv-upload.kusty.io/) can help you achieve if you are trying to import a lot of data into your Kustomer organization. Today we’re going to work through a real-world example and show you how to bulk upload data from a CSV and act on it. No prior knowledge will be needed to get this up and running, the only thing you will need is access to Kustomer with permission to create webhooks, API keys, and workflows. 

You purchased leads from a marketing team to gather information about clients who might be interested in purchasing your product. Next, your salesperson was able to secure some orders. Now you’d like to send a bulk email with a new article you just wrote letting customers know about all the interesting ways they can use what they just bought, and to let them know this is the place to reach out if they have any specific questions. However, your external systems' bulk email options are limited, and you haven’t quite gotten around to setting up your external ordering system with Kustomer. You’re able to get a CSV with the information of clients who have ordered the product though. This is a great chance to put the CSV upload tool to work.

The first thing we need to do is make a new Form Hook that will be able to receive the data from our CSV Upload tool. This can be done by heading into your Kustomer instance navigating to Settings > Platform > Inbound Webhooks and then clicking on the Form Hooks tab on that settings page. Once you’re there you will want to click the “Add Inbound Webhook” button. Let’s name it “Bulk Email”, give it a description of “Bulk Email” and for the type, we will select “Form”. Once it is created you will want to click the three dots next to the new form hook that you have just made and then click on “Copy Hook Address”. Now once you have that address copied you can head to the CSV-upload tool web address and paste that into the “Hook Address” field. 

Next, we are going to create our API key which will give the CSV-upload tool permission to send data into that webhook. To do this we are going to go back to our Kustomer instance and head to Settings > Security > API keys. Once we’re there we can click the button to “Add API Key”. The name can be anything you like, let’s use “Bulk Email”. For roles, you want to search for and use “org.hooks”. We recommend that you add an expiration date to any API key that you make. You can always make a new one and delete old ones from that screen. Then you can replace any expired ones. Once you click “Create” the key will only be available until you close the modal that pops up. Then it will be invisible except for the last 6 characters so that you can confirm if you have the proper API key. Store that key somewhere safe on your local drive if you think you will want to reference it later. Once you have it you can now go back to our csv-upload site and paste the key into the “API Key” field. 

We’re almost ready to start sending files into our Kustomer instance! We now need to set up a workflow that will ingest the data from the form hook and will be able to act on what comes in. To do this in Kustomer we are going to head to Settings > Platform > Workflows. On that page, we are going to select “Add Workflow” and then choose “Custom Workflow”. Our workflow needs a name of our choosing (make sure the callable workflow option is unclicked) and then we will be brought to a blank workflow page with one “Choose Trigger” box in the middle. Let’s click that box and a new pane will replace the one on the right side. There, below trigger app from the dropdown select “Hooks” and below trigger event scroll down and the “Bulk Email” Webhook we just created is part of that dropdown list. We’ll choose that one. We’re going to head to the middle top right and select save. Then we will toggle the button next to that to turn our workflow on, it will go from grey to blue. After that, we are going to the bottom left where it says “View Logs” let's expand that. In the top left of the modal let’s click “< TOP 100 EVENTS” and the workflow page should now look like this.

Now we’re set to start sending data through the hook and building out our workflow with the data from our spreadsheet!

A couple of caveats about the data that comes through the hook. It must be a .csv file, and the first row of the file must have data in each column that contains no spaces. If the columns are titled “Customer Name” or “Client Email” we will want to change those to be something like “Customer_Name” or “CustomerName” with either an underscore between words or no blank space. The first row will become the attribute values for us to map all of the data within each column for each row within the CSV. Let’s send an example through and see what happens in our Kustomer instance. 

Here is an example of the structure of a CSV file with a couple of customers, their names, and their email addresses. Those are within columns titled “Name”, and “Email”.

I’m going to head to the CSV upload tool where I have my hook and API key ready to go, then I’m going to drag this file from my Finder/File Explorer and drop it right into the “Upload CSV” Field. The “Upload Id” will automatically populate with the name of the CSV file. You can name it whatever you like. This will be how you are able to identify the data that was created when you sent in a specific upload. With this test data, I’m going to select “Upload” and then I should see this.

If you get an unsuccessful message there are a few things to check. Confirm that the last 6 digits of your API key match the API key you created, and confirm that the hook address is copied properly. You can recopy the hook address from directly within the workflow as well. Support is also available to help work through this with you. 

Now that we have our success message we’re going to head back to the workflow and check the logs. Nothing will show up but once I click the refresh button “⟲” on the logs I will see 3 events that occurred. Those events correspond to the three rows with data from my CSV. I can click on the first event and then into the “Recieve” step. There I will see data in the “input” and “output” sections of my logs. That is all of the data available within a single row of my CSV mapped to the column names from the first line. With the output data, I can now start making more steps within my workflow to take action with this data. 

Now we will build the rest of the workflow. Below the Bulk Email step, I am going to click the plus sign and select “Action”. On the right side below Action App click and select Kustomer below Action Event click and find “Customer: Lookup by Email”. Required fields will appear and in email field, I will put: /#steps.1.attributes.data.upload.Email. The syntax we use is very specific. For us to access the email from the csv I uploaded I am going to need to start with “/#steps.” this will tell the workflow we are looking for a step within the workflow. Now after the period, I am going to add the ID of the step. The first step in a workflow always has an ID of “1”. So it’s going to be “/#steps.1” (if typing this yourself the workflow will switch to a Blue 1 to switch views click the “<>” right above the input field). The rest of the string output of the first step. We want to use “attributes” first and then we’ll see a colon and a brace and what that tells us is that we can access the next level down through dot notation (property accessors). Then we’ve got three more levels that we need to navigate through. In this case, they are “data”, “upload”, and “Email” (case sensitive). Now when putting it all together “/#steps.1.attributes.data.upload.Email” will let the workflow know that you want to use whatever comes after “Email” as the string to use. In this case, it is the first line of the file “jotest@gmail.com”. 

Next, we need to add a “Condition Step” to our workflow just in case the customer didn’t exist. Let’s click the plus below step 2 and choose “Condition Step”. On the right-hand side under “Continue Only If” we will click in the box and up pops “2 Customer: Lookup by Email” we will select that and scroll down to choose “Id”. We can set it so that if the id exists, we will continue on (we will worry about if the customer doesn’t exist soon). Now we know the customer is in our system, what do we want to do? We want to send that email. 

First, we need to create a new conversation with that customer. We can click the plus below our condition to add a new action step. Then we go to Action App > Kustomer and Action Event > Conversation: Create. Required field pop up and we will use the customer we just found. Click in the “Customer (string)” scroll down and select Id. Now that we have the conversation we can add a message to that conversation. We click the plus below “Conversation: Create” and it is Action App > Postmark and Action Event > Message Send (Gmail does not support bulk messaging. We see a couple of required attributes that we need to add in this step. Customer (string) click the field, select “2 Customer: Lookup by Email”, scroll down and select Id. Then in Conversation (string) select “3 Conversation: Create” and find Id. In the From field, we add an email address that we want to use, by default a support alias is already configured and it will be support@ORGNAME.mail.kustomerapp.com where ORGNAME is unique to your organization. , the To field will be the string we used to access an email, /#steps.1.attributes.data.upload.Email. Last we add a subject line and the body of our message. If you would like to use an email template you can select the template you would like to use at the bottom, and you can create one by following this guide from our help center! Wonderful we can send emails to customers that we found. 

Now, what if the workflow didn’t find the customer? If the Id does not exist we need to create an option for that path. We can click the plus sign above the condition step and select “Condition Branch”. In this case, we only have two options, either the customer existed, or it didn’t, so in the condition branch, we created in the “Continue Only If” box we want to put “true” and then select exists, that way we will continue down this path if the other condition was false.

Down this branch, we need to add more steps. Let’s click the plus to add a new action step. It will be Action App > Kustomer and Action Event > Customer: Create. All fields are optional here, however, we want to be able to find these customers in the future so let’s add their Name and Email to the associated fields. The name will be /#steps.1.attributes.data.upload.Name and the email will be /#steps.1.attributes.data.upload.Email. Those are both the associated output steps that have the data we want to use to update the customer information(if there are other fields in the CSV file you can use the same dot notation to fill in all the associated information!). 

Once we have created the customer we can copy the Conversation Create and Postmark message send steps and paste them below the customer we just created. You click on the step you want to copy, head to the top right of the panel, and click the copy icon. Then click the plus underneath the step you want to append the one you just copied, and select paste. Once they are pasted we need to make some adjustments to them to make sure they are referencing the correct workflow steps. 

In the Conversation: Create step below Customer: Create delete the old information in Customer (string), and choose Conversation: Create > Id. The Postmark Message Send step is also going to need to be updated to reflect the proper customer and conversation ids in the same way. Everything else can be left as is. We used the email from the first step, and our general support email address. The subject line and body for the email are also not going to change. 

Now let’s test it. We’ll go back to the CSV Upload tool. Make sure we’ve got the CSV file with the associated emails we want to send to in columns titled “Name” and “Email”. Then we will ensure we have the proper API Key, and last we will make sure we have the right Hook Address. Then we can upload and see what the logs say when we refresh them. 
 

We’ve done it! We’ve got a robust workflow that will send an email out to a spreadsheet of customers. This can be modified to update any data on the customer you would like. Let’s say you know the specific order numbers that these customers have and you want to add a list of them to each one. You can modify this workflow to find the customer that ordered that and add it to a new array attribute that you created on the customer. The options for this tool are varied and powerful. There are a few limitations to be aware of, it can handle 70,000 line CSV files and no more. Additionally, if you do not use the upload Id to keep track of changes you will have a tough time finding the specific things you did with this CSV upload. If there are any questions or you have a use case you would like assistance with feel free to email us at support@kustomer.com anytime!

Congratulations! You made it to the end. You can also copy this GIST and import it as a workflow to have a starting point for building out one in your instance.