Getting Started with Klaviyo as a Developer: Modeling Data and Workflows

This is the first article in our Getting Started as a Klaviyo Developer four-part series.

To build a successful software product, it is important to have at least a high-level plan. In this section, we’ll discuss strategies to identify and define use cases to achieve a business goal or plan. With properly defined and understood use cases, the next article will focus on mapping these use cases to technologies and strategies to accomplish them.

Overview:

• Create data-driven experiences by defining two things: data and workflows. Data is defined as objects and their properties; workflows are composed of actions that these data objects are involved with.
• Discuss some strategies to identify data and workflows by defining use cases and by identifying the differences between use cases and edge cases.
• Work through creating pseudocode for an example use case by defining data objects with their corresponding properties and actions as workflow steps.

Defining use cases

The first step to building data-driven experiences is defining your data and workflows. The data can be likened to nouns in the system, and the workflows to verbs. To get started, you should think in terms of use cases. Thinking this way will help you discover both the data and workflows for common paths. From use cases, you can build a cumulative model that encompasses as much of the system as possible.

How to identify the use cases?

If you are working in an industry or business you are not familiar with, it may be challenging to identify the most important use cases. Answering key questions about the customers and the business should help. Questions include:

• What do customers use this website/service for?
• Where are customers getting stuck or needing help?
• How does the company make money?
• If the company is a merchant, What products make this company the most money? What products gain the most new customers?

Example: If you were running a movie theater, a common use case may be: a visitor arrives and wants to purchase tickets for a movie starting shortly. This would help you identify data that needs defining such as the visitor/customer, the movie schedule, the ticketing and admission process, etc. You could then consider the use case of a visitor purchasing a ticket for a movie far in the future and how it may change the requirements to be able to solve for both cases.

Considering use cases vs edge cases

Use cases and edge cases (less common use cases) are closely related. It is generally good practice to consider edge cases, however, if you spend all of your time optimizing for edge cases, you will not be prioritizing correctly for your key use cases. So make sure when defining use cases and edge cases, you are able to thoughtfully distinguish between the two. Try to account for and provide a way to handle edge cases without prioritizing too much time working on things that will not happen often. Try to bundle edge cases and handle them together.

Using pseudocode to model data and workflows

When modeling data, we will use the following pseudocode shorthand:

Pseudocode data objects will be concatenated and upper-case in code blocks:

ShoppingCart

To identify an object’s attributes, such as when modeling data, we will use {}containing name:description key/value pairs. The values may be omitted when not necessary to convey the idea of the data model. For example, you don’t need an explicit “Last Name” in the below data object to understand the intention:

Customer {
    First Name: David
    Last Name:
}

To identify a list of objects, we will use []for the named list and {}for the properties of the list, to distinguish each list item we’ll use {} inside [], {[]} for example:

Products {[
    Chair {
        Name: Stool
    }
]}

Workflows will have a name and workflow actions will be surrounded by ( ) with an arrow pointing → at the next step(s). Data required will be surrounded by { }. For example:

AbandonedCart

AbandonedCart — Workflow diagram of an Abandoned Cart data and actions

The goal of the pseudocode is to clearly convey the information, when doing your own modeling, feel free to use this style or another style that works for you.

Modeling data and workflows using an example

For this example, we are going to model the data and workflows for a website. By working through an example use case, we will add attributes to the data and actions to the workflows that enable the use case. As you develop more use cases for the same data and workflows, the attributes and actions for each one will increase in complexity.

Let’s start by defining the use case:

Use Case: User arrives at your website to find a product is out of stock. The user wants to be able to sign up for a back in stock list for that product, and be alerted when the product is restocked.

In this use case, we have at least three clear data points in the model, the user, the product and website. There is also a peripheral data object: BackInStockList. Let’s create our first model: AnonymousVisitor.

Modeling the Data

User { }

What attributes do we have for User and what attributes do we need? We should have information from their browser session including their source, any UTM params they arrived with, and possibly a cookie and other information from prior sessions (this is useful for reporting later on). We need information for what product they are signing up for back-in-stock alerts on, and the contact information to send the alert.

User {
 Source:
 Cookie:
 UTM params:
 Product:
 Email:
 Phone number
}

Let’s consider the next model: Product.

Product { }

What attributes do we have for the product? Typically products have attributes including: name, description, size, color, inventory, and potentially many more. For this experience, consider which attributes are required.

Product {
 Name
 Description
 Size
 Color
 Inventory
}

For our final model, we have: Website (there are many more things we could also model, but that are not strictly required for this example experience). The website needs a form that captures the user’s intention to sign up for a back-in-stock alert for the product.

Website {
 Back in Stock form
}

Now that we have the User, Product, and Website, let’s model the workflow for the use case: BackInStockAlert.

Modeling Workflow

In order to make this experience work, we need to have the appropriate data for the user, the product, and the website’s form. Then, when a product is restocked, we need to alert the user.

Visualization for BackInStock alert workflow

Summary data and workflows

Data Objects:

User {
 Source:
 Cookie:
 UTM params:
 Product:
 Email:
 Phone number
}
Product {
 Name
 Description
 Size
 Color
 Inventory
}
Website {
 Form
}

Combined Workflow with Data Objects:

Built-out workflow visualization for BackInStock

By modeling the data and workflows for this use case, we can more clearly view the requirements for the system. When modeling another use case, you can consider whether new data objects and workflows are required, or if you should add to what exists.

Summary

We covered the initial data modeling required to build data-driven experiences. This included defining the properties of the data objects and actions for workflows. We documented these use cases using pseudocode. Now we are ready to get started with our implementation.

What’s Next?

In the next article, we will enhance the workflow above to include obtaining consent at checkout and an abandoned cart flow. We will also discuss technical details on how to integrate this workflow into various systems. Follow us on Twitter, @KlaviyoDevs, to learn when the next article comes out!

Ready to get started with Klaviyo? Check out out Getting Started with Klaviyo guide in our developer portal to get your own account and start testing things out.