Lightspeed Retail API

Speaker 0: And welcome back to the community hotline. I'm your host Brian Gillespie from Directus. Today, we are answering a question from Directus community member, Daryl Morley. Daryl, how are you, sir? Welcome to the community.

Happy to have you. I'm gonna answer your question today in detail. Alright. So the question from Daryl. I'm integrating Directus with Lightspeed retail API.

Not heard Lightspeed name in a long time. That's awesome though. Would like to use, for example, the category ID from Lightspeed as the primary key in my categories collection within Directus. Here's the flow I'm aiming for. One, a the first step.

A user creates a new category from the Directus admin UI. A before create hook fires that's not actually what it's called in directus, but I got you. It creates a category inside Lightspeed via their API. We receive the category ID back from Lightspeed, and it sets that ID as the primary key of the new Directus record. The issue I'm running into is if the ID field is not auto generated, Directus requires you to provide an ID.

Yeah. You gotta have that primary key for sure. But I can't know the ID until I call the Lightspeed API inside the hook. Prevents me from using the Lightspeed category ID as a directus primary key. I could potentially store light speed ID in a separate external category ID field, also an option, but then I run into difficulties linking my items to categories as, the directus only sports relationships using the primary key.

You could establish relationships on that that other field as well, but I totally understand where you're coming from with this. And Daryl's pleading because anyone successfully implemented a setup like this or found a clean workaround, keeps everything in sync. Alright. So we are going to dive into this, Daryl. We are gonna solve this problem together right now.

Alright. So I've got a blank Directus instance. We're gonna go in and let's create a new collection. I use plurals. We're gonna call it categories.

Now every collection has to have a primary key. Typically, I just leave this set to ID for simplicity's sake, And usually I go with a generated UUID. We automatically generate that. In this case, where we want that to come from a third party, we are going to use a manually entered string. Now optional fields, I usually add these a 100% of the time.

Not gonna do that here. I'm just gonna click finish setup, and what we're gonna do is just hit name. Let's add one more field for the name of this category, and this is our categories. Right? So now the challenge is if I go in and this is a new category, just as you said, if I try to save this using command s or just hitting the save button here, requires a value.

Well, that sucks. That's not what I wanna do. So how do we fix this? There's two ways I can solve this. I'm gonna show you flows first, and then we'll talk about hooks.

Underneath the hood, they use the same event system. But, one way to do this inside the studio without writing much code or creating a custom extension that you've got to bundle and deploy, you could just do this in a flow. And if the logic is simple enough, it's it's easy to maintain. So we're gonna call this create category is the name of this flow cool in external API. Now I'm not actually gonna use the light speed API here just to keep this high level, but, yeah.

You'll you'll figure that part of it out. Got faith in you. Got confidence. Alright. So we can trigger these flows a variety of different ways.

The one we're looking for is event hook, and then we're immediately asked the type of event hook. So there's two, obviously, that's on the screen. There's filter, which is, they said we say blocking here because it blocks that event from actually performing. This is the one that we want because we get a chance to it runs before the item gets saved in the database or before the item gets updated. We'll talk about that in a moment.

Actions happen after the event is settled, so after the category has been created. In this case, we want to intercept that category as it's being created and before it's saved into the database, and we're gonna alter the payload. So that's what we're doing here. The scope, we just want items create. Right?

Updated items should already have an ID, and we don't wanna complicate this. The response body is going to be our altered payload with this. So this is the payload that we're gonna save to the database. Now you can choose between all data or the data of the last operation. In this case, I'm just gonna keep this simple and choose data of the last operation to remove as many potential issues.

Alright. So now we've got our trigger. The next thing that we wanna do is call the external API. Now, I could go in and just choose webhook request URL. I'm gonna hit call external API here.

This is our step. In this case, it's gonna be a post. And I've just set up, like, a a mock endpoint, from some online free service that when we send this request, it should just send us an ID back. Cool. Alright.

And now the last step, and, you know, and probably, like, that stuff you're getting back from Lightspeed, you're gonna wanna transform that payload. There's two ways to do that. And let's just call this payload. Right? I could use the run script operation where I've got the full power of JavaScript.

Now you can't import anything from NPM or use any libraries here, but you you've got, you know, the standard JavaScript library available to you here, and you can run, you know, just basic little functions there. Actually, you don't have the standard JavaScript library. This runs in an isolate, but you got all the basic JavaScript stuff that you're gonna need to transform a payload. The other way to do this is via the transform payload operation, which basically just allows you to adjust what is gonna come out of this thing. And you'll see we're using mustache syntax here for a reason.

Every operation in a flow appends its data to a key that you can then access. So there's two that are special, which are accountability and dot trigger. That's why they have or I'm sorry. Dollar sign trigger. That's why they have that dollar sign in front of them.

But the rest of them, we could just do like this. So it'll be call external API. That's the key. And then we're just gonna get the ID. Right?

Cool. Hit save. This is our flow. Super complicated, super messy. No.

It's not. It's easy. And then we're gonna go in, and now we're gonna create a new category. So we hit new category, And, oh, undefined. That's not good.

What is happening here? Call external API. That's my key. Did we get some records back? Okay.

Yep. So that's the issue. Right? Now I incorrectly formatted this. The thing that we're looking for is dot data dot ID.

Alright. Always gotta do a bit of troubleshooting. I was hoping I was just gonna one shot that without any AI assistance, but, hey, it happens. And I also saw that we're missing the name. So in this case, you know, I'm just going to call the name.

So we'll do trigger dot payload dot name. I think that's gonna be correct. Now, again, this is probably where you might wanna use something like JavaScript. But we can see here in our trigger, we have a payload. We have a name for the payload.

Awesome. Alright. So now, fingers crossed, this should work or it's gonna error out because we can't have two categories with undefined. This is new category. Hit save, And voila, we've got an ID that has come from the ether.

Now the other approach to do this, you know, if you prefer to express your logic as code and you wanna, you know, check that into Git, what you can do is just build an extension that does the same thing. Right? How do I do that? Well, go to our extension docs. So just go to guides, go to extensions, go to quick start, copy this code.

I'm just gonna open up my terminal. We are going to put this here, APX direct us extension latest, and we're just gonna write a custom hook. And I'm going to even cheat and just use something that I've got in, another project. Alright. Choose a name for the extension.

External ID, maybe. Sounds good. Cool. We're gonna use TypeScript auto installer dependencies, and now I've got this external ID extension. It actually needs to be in my extensions folder here inside Directus.

So, let's just blow this whole thing up and do that. My Directus project CD extensions slash external ID. Why does that not work? CD extensions. What is my directory?

Oh, somehow I'm inside a Directus. I gotta do that. CD extensions, external ID. Okay. And if I open this up, it's just an index dot ts file whenever the item is created.

Let's pull up just something from my clipboard. Where are you? Okay. Cool. So this is a pattern that I've used quite a bit before.

We're just gonna call this categories. Right? And we're gonna erase nano ID. We don't really need that. Cool.

And we'll say, what, fetch? We could do a fetch call in here. Alright. Constant ID. You know what?

Let's just let's keep it simple. Nano ID. Cool. So what this does, right, we define this hook, and we'll go into we see this filter that's on items dot create, and then we're passing in the payload, our schema from the direct us. And, we've got our accountability object, which we're not using at all here.

But then we've got this constant that says, okay. These collections have to have a public ID. And in this case, I could just change it to ID. And all we're doing here is updating the payload and returning the payload. Payload has no ID.

Alright. I'm gonna hit NPM build. Directus CD extensions. External ID. Cool.

There we go. PMPM build. Build my extension. I just wanna show you one way that can get this done. And then I've got my directus instance.

We're gonna need to restart that bad boy. So we'll hit restart. It should pick up that new extension. And fingers crossed. If we go to extensions, we could see that extension.

And then I can deactivate. Let's not delete it entirely. So we'll just deactivate this flow, change the status to inactive. Cool. Got it.

And now if I do this again, say test category. Fingers crossed. I know this is not gonna work. Oh, it does work. There we go.

Test category. I was gonna say, I don't think I have Nano ID in installed, but maybe we're using that somewhere inside Directus itself. Cool. There it is. Couple different ways to achieve it.

Hope this answers your question. Daryl, my man, thanks for joining the community. Appreciate you. Keep the questions coming. Keep the feedback coming.

We love it. I'll see you next time on the community hotline.