There are many use cases that Kustomer’s CSV upload tool can help users accomplish when they are trying to upload large amounts of data into their organization’s instance of the Kustomer platform.
In this blog, we’re going to work through a real-world example and show you how to bulk upload data from a CSV file and take action 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.
For example, let’s say you want to send a bulk email to your customers with a blog about all the exciting ways they can use a product they’ve purchased and how to reach out if they have any specific questions.
However, if your external systems’ ability to send bulk emails are limited, and you haven’t quite set up your external ordering system with Kustomer, then we have a solution — you’re able to get a CSV file with the information of clients who have ordered the product. This is a great chance to put the CSV upload tool to work.
Step 1: Creating the Form Hook
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. As a reminder, a form hook is a unique URL that lets third-party applications send real-time information into Kustomer.
This can be done by:
- Heading into your Kustomer instance and navigating to Settings > Platform > Inbound Webhooks and then clicking on the “Form Hooks” tab on that settings page.
- Once 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, 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.
Step 2: Creating the API Key
Next, we are going to create our API key which will give the CSVupload tool permission to send data into that webhook. API keys are required to authorise Kustomer to send and receive data across integration touch points.
To do this we are going to:
- Go back to our Kustomer instance and head to Settings > Security > API keys.
- Once there click the button to “Add API Key”. The name can be anything you like, let’s use “Bulk Email” for this example.
- For roles, search for and use “org.hooks”.
Note: 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 at another time.
Continuing the process to create the API Key:
- 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 six 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 go back to our CSV upload site and paste the key into the “API Key” field.
Step 3: Setting up the Workflow
You’re almost ready to start sending files into your Kustomer instance. You 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, you are going to:
- Head to Settings > Platform > Workflows.
- On that page, select “Add Workflow” and then choose “Custom Workflow”.
- The workflow needs a name of your choosing (make sure the callable workflow option is unclicked) and then you will be brought to a blank workflow page with one “Choose Trigger” box in the middle.
- Click that box and a new pane will replace the one on the right side. There, below the trigger app from the dropdown select “Hooks” and below trigger event scroll down and the “Bulk Email” webhook you just created is part of that dropdown list — choose that one.
- Locate the middle top right and select “save” and then toggle the button next to that to turn the workflow on, it will go from grey to blue.
- After that, go to the bottom left of the screen where it says “View Logs” and expand that. In the top left of the modal click “< TOP 100 EVENTS” and the workflow page should now look like the screenshot below.
Step 4: Sending Data Through the Hook
Now you’re set to start sending data through the hook and building out the workflow with the data from the 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 the Kustomer instance.
Below is an example of a CSV file with a couple of customers, their names and their email addresses. Those are within columns titled “Name”, and “Email”.
To send a test:
- Head to the CSV upload tool where you have your hook and API key ready to go, then drag this file from your 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, you’re going to select “Upload” and then you should see a screen similar to the one below.
If you get an unsuccessful message there are a few things to check:
- Confirm that the last six 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. Complete the following steps to continue our test:
- Nothing will show up but once you click the refresh button “⟲” on the logs you will see three events that occurred. Those events correspond to the three rows with data from my CSV.
- You can click on the first event and then into the “Receive” step. There you will see data in the “input” and “output” sections of the logs — that is all of the data available within a single row of the CSV mapped to the column names from the first line.
- With the output data, you can now start making more steps within the workflow to take action with this data.
Step 5: Building the Rest of the Workflow
Now we will build the rest of the workflow. To continue doing so, follow these steps:
- Below the bulk email step, you are going to click the plus sign and select “Action”.
- On the right side below “Action App” click and select “Kustomer” below “Action Event” then click and find “Customer: Lookup by Email”.
- Required fields will appear and in the email field, then you should enter: “/#steps.1.attributes.data.upload.Email”. The syntax we use is very specific.
- To access the email from the CSV you uploaded, you need to start with “/#steps.” this will tell the workflow to look for a step within the workflow.
- Now after the period, 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.
- You should use “attributes” first, and then you’ll see a colon and a brace. What that means is that you can access the next level down through dot notation (property accessors).
- Then there will be three more levels that you 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”.
Step 6: Adding a Condition Step to the Workflow
Next, we need to add a “Condition Step” to our workflow in the event that the customer doesn’t exist. To do so:
- Click the plus below step 2 and choose “Condition Step”.
- On the right-hand side under “Continue Only If” click in the box and up pops “2 Customer: Lookup by Email” we will select that and scroll down to choose “Id”.
- Set it so that if the “Id” exists, it will continue on. Later in the blog we will explore what to do if the customer doesn’t exist.
Step 7: Sending the Email
Once you’ve determined the customer is in the system, the next step in the process will involve sending the email.
- First, you need to create a new conversation with that customer. You can click the plus sign below the condition to add a new action step.
- Then go to Action App > Kustomer and Action Event > Conversation: Create. The required fields will pop up and you should use the customer found in the previous step.
- Click on the “Customer (string)”, scroll down and select “Id”. Now that you have the conversation, you can add a message to that conversation.
- Click the plus sign below “Conversation: Create” and follow Action App > Postmark and Action Event > Message Send (Note: Gmail does not support bulk messaging).
- You will see a couple of required attributes that need added in this step. For “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”, add an email address that you 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 organisation.
- The “To: field” will be the string used to access an email, “/#steps.1.attributes.data.upload.Email.”
- Last, add a subject line and the body of your message.
If you would like to use an email template, you can select the template you would like to use at the bottom. You can also create one by following this guide from our help centre. Now you are able to send emails to customers that were found.
Step 8: Creating a Path If the Customer Does Not Exist
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.
To do this:
- Click the plus sign above the condition step and select “Condition Branch”.
- In this case, there are only two options, either the customer existed, or it didn’t. In the condition branch that was created in the “Continue Only If” box, enter “true” and then select exists, that way it will continue down this path if the other condition was false.
Down this branch, you’ll need to add more steps.
- Click the plus sign to add a new action step. It will be Action App > Kustomer and Action Event > Customer: Create.
- All fields are optional here, however, you 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 you’ll 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 you 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 sign underneath the step you want to append the one you just copied, and select paste.
- Once they are pasted, you need to make some adjustments to them to make sure they are referencing the correct workflow steps.
In the Conversation:
- Create a 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 since you 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.
Step 9: Testing the Workflow
Now let’s test it. To ensure everything is set up properly:
- Go back to the CSV Upload tool.
- Ensure you’ve got the CSV file with the associated emails you want to send to in columns titled “Name” and “Email”.
- Then you will ensure you have the proper API Key, and finally ensure you have the right “Hook Address”.
- Then you can upload and see what the logs say when you refresh them.
You’ve done it! You’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, but nothing larger than that. 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.
