Developer Bytes | Custom Objects with Zack Wolfson | Part 1: Creating a Custom Object

Hello, everybody. Welcome to an episode of Developer Bytes. I am joined by Zach Wolfson, senior developer advocate@HubSpot. Hey, Zach, how are you doing?

Hey, Dennis. I'm doing great. How are you?

I cannot complain. Thank you very much. And he's here to help me understand custom objects. So the way we're going to lay this out is we're going to do a series of videos, three in total, and I will add links to the bottom of each one of these to the other two videos so you can see the entire playlist. The first video we're going to cover just what a custom object is. How do you set one up? You know the schema. The second video is going to be, well, you got it set up, but you want to make some updates to it. So how do you do that? Maybe some associations. And the last video we're going to cover is, I don't want this custom object anymore, so let's get rid of it. We're going to do the delete. So, Zach, could you just kind of walk me through real quickly what is a custom object?

Yeah, absolutely. So before we talk about what a custom object is, let's take a step back and talk about what objects are and what they aren't in particular. So there's two ways to represent data within HubSpot. Depending on the nature of what you're talking about, it's either going to be an object or an event. All right, so an object is. Well, I think a contact being kind of the first example that we ever saw of an object. Here it hubs, where you have a first name, a last name, and a number of properties that describe that first. Now, the values in those properties can change over time. So maybe you're tracking somebody's job title. Right. I've been at HubSpot 7 and a half years. My job title has changed several times. And you want CRM to be able to represent that. On the other end of that, we have events. Now, events are things that happen at a point in time and they have properties that describe them, but the values of those properties can never change because you can't go back in time and redo something. Classic example of this is an email. Open or click. I can click a link in an email and, you know, the browser. I used the email client that I had the time that I did it. Those things will never change about the event. Right. And then those things are all tied together with associations. So that's basically what makes up the HubSpot CRM objects, events and associations. Now we've got a lot of default objects and most common things you'll use in the CRM. Contacts, companies, deals, tickets, products, line items, all that good stuff. But that doesn't always meet everything that a company is going to want to use HubSpot for. So we introduced the idea of a custom object. So you can now define your own what we call a schema, the metadata about that object. So just like contacts have some default properties for first name, last name, email address, job title, you'll want to have the same thing for whatever your object is that makes sense for your business. Right. So you can shape HubSpot CRM to make sense for your users and your business. You got a lot of knock on effects for reporting, even some rendering custom content. All kinds of cool things you can do like once you have your data properly represented in the HubSpot CRM.

So to stop you right there, this is important. This is one of those things where you really need to make some decisions on what you want prior to even getting to the setting up of the schema. Right. You want to sit down with your team and know what's necessary for this object, correct?

Exactly. Because there's a lot of downstream implications and I mentioned kind of reporting any content on them, but there's others as well. So you know, how are you going to want to segment your contacts? Does it matter if they're related to whatever this custom object you have is? Or you also every time you get in a new object, you get a new workflow type. So think about, you know, as this is going through an automated fashion, what information you need, you know, are there going to be multiple of this object? You know, how does it relate to the other some default objects or even custom objects you may create? So think about it. In the old days you might think about like a database architecture, you know, let me model out my data and kind of see what makes sense. And that'll depend on how you want to use it. The same thing applies here, but you don't need to be a, you know, MySQL expert or anything. You just have to think about the marketing, sales and servicing that you want to do in relation to this custom object. Perfect. Cool.

And let's just, let's get down to it then. Let's get to the meat of this. Do you mind sharing your screen and just kind of walking through, just actually creating this schema?

Yeah, so I'm going to walk through an example that we have on our docs. So what we're seeing here is A postman, which is utility to make API calls really easily. And this will be the JSON that represents a new schema that we're talking about. In this case, it'll be schema to represent cars. So we'll pretend that we're at a car dealership and you know, this is a bunch of things that we need to go over. Now I'm not going to go through every single field in here, but just point out a couple of important things. So one, we want to give our schema a name, something we can refer to it, some labels so that the CRM UI knows how to frame refer to these things. When we only have one of them or we have multiple of them, we want to give it something to display. So in this case we're going to use the model of the car and that'll display in, you know, when you're looking at a record that's associated with it in the sidebar and the kind of highlighted link to click on it. Then we're going to define some properties that you have to use to create kind of cars in the database. So what year it was made the to make the vehicle identification number and of course the model, we're going to use it as a primary slave property. It must also be required. And we'll have the property definitions for these like what type of data and things like that in this properties array. But the one I really want to draw your attention to, which is a really interesting concept here is the vin. And the vin, it's a view of identification number and we have this has unique value to true and what this means is that as you put instances of cars or individual cars into the CRM, it will enforce to make sure that no two vehicles have the same vid. Right? And this is true in the real world. So we want our database or our CRM to represent that. And the nice thing about this is when we're dealing with customers cars via the API, I don't have to then write my scripts to keep track of what the HubSpot auto defined identifier is. I already know the VIN, so I don't have to go look that up and then, you know, get the HubSpot ID for it. I can just do all these operations by the vin, which I already have outside of it. So it's a nice feature here to use a meaningful identifier to help save some lookups and searching later on in the process. Cool seven properties here. Then we're going to associate this to the contacts object because people can buy cars. So we want to associate that with the cars. Let's go ahead.

Could you do it to multiple objects right there? Could I just go to associate to if I would do contacts and companies, that's.

That's possible. Exactly. So this is an array. So you just add a comma separated value, whatever the standard objects that you want to associate it to to. And we'll show how to create a new one in just a second. It's a new association. So if we go ahead and create this. Hope it works. There we go. Okay, So I get a 201 created back along with the full schema that we've got here. So we've got a lot of different stuff about it. But what I want to kind of point you to, to kind of save in here for later is the object type id. We're going to use this to refer to it anytime we want to modify anything about this schema. This will be the kind of the canonical way to refer to this id. Now in case you're curious, this two dash in front of it means it is a portal specific. So that means it was created in just my portal. You will see some other object types. So native object types have a zero in front of them. So so contacts is actually zero one and then integrator object types will have a one dash in front of them. Now you won't see a lot of these out in the wild. That's still very much a part of a pilot program that we're running. So you want to check that out. That's a link to from the custom objects document. We have an application to apply to be a part of that program to let you use insert custom objects into customers schemas using. Oh, perfect.

And I'll make sure we have a link to that in this video.

Perfect. All right, so let's take a look at kind of what this looked like. So here's my kind of contact screen here. Got the two default contacts and okay, I've got the native objects that are here that I kind of mentioned earlier. So now I created this. Let's do a refresh and we see cars here. Yes, nice work. Thank you. Well done. All right, so we can go ahead and just create a car. So we'll say a used car. We got it into our inventory a little bit ago. 2018, a Volkswagen Tiguan. Make up a VIN. That's not the correct one, but blue. It's got, you know, say 18,000 miles, let's say $20,000. And it's an awesome car. They all learn how to type. And we're going to also associate this with Brian. Now, I think he also has a much nicer car than this. But for now, let's pretend that Brian drives the same vehicle that I do. So here we go. We've got it. We can click on it. And this looks just like any other custom object. Or any other object.

Okay, folks, that wraps up part one of our series on custom objects. Our next video will be on patching the schema. If you have any questions, feel free to reach out in the community.