A colleague told me about transaction set variants and now I want to get some more experience with them myself. In a nutshell, the problem is that one transaction set can represent different kinds of documents. For example, he showed me an implementation guide that specified that the 204 Motor Carrier Load Tender could be used to create, cancel, modify, or confirm a load tender. That feels like four different documents to me, but they are all represented by the same transaction set. So, how do you deal with that in practice?

My goal isn’t to come up with a solution, but to understand the problem. I’ll take an implementation guide that describes some transaction set variants and then I’ll try to come up with a strategy to deal with them. I don’t want to build a full implementation; I want to get a feel of what it takes to handle this in practice.

I’m going to look at the implementation guide for the 850 Purchase Order from Amazon, because I happen to have a copy. This means that today, I’m a wholesaler! Amazon sends me a purchase order, now what.

Understanding the variants

I don’t sell directly to the consumer; I leave that to Amazon, so they need my product in their warehouse. That’s why they send me an 850 Purchase Order. How do I know that I have to deal with transaction set variants? The implementation guide from Amazon doesn’t contain any preamble. It goes straight into the default information.

That generic description of the transaction set doesn’t do me any good. Fortunately, I know to keep an eye out for transaction set variants, thanks to my colleague. The first segment of the transaction set (I’m not counting the envelopes) seems to contain what I’m looking for.

There seem to be 4 variants. Although, as you can see above, the guide mentions that there are 69 total codes. I assume that means that the standard defines 69 codes, but Amazon only uses 4 of them. Surely, Amazon doesn’t mean to say that they use 65 other codes as well, but they’re not going to tell you any more about them. Let me check that assumption with a look at the standard transaction set. Yes, that one has 69 codes. Good.

So, what variants do we have? New Order I understand: that’s a new order. I feel so smart right now! Rush Order is an order that needs to be rushed, but I’m not sure how this is supposed to be treated differently than a new order. Maybe it isn’t different in terms of EDI messaging and it’s just a notification to the business: do whatever you need to do to rush this. Perhaps alarm bells should go of to let everyone know to drop whatever it is they’re doing and take care of this order. I have no idea what a consigned order is, so I should ask a domain expert, but I’m going to ask Google instead.

If I understand correctly, with a normal order, Amazon buys a product from me, puts it in their warehouse, and can then do whatever they want with it, although presumably they’ll try to sell it. With a consigned order, Amazon puts the product in their warehouse, but it still belongs to me until Amazon sells it. At that point, Amazon handles the transaction with the customer and they forward me the money, minus a transaction fee they keep for their work. If the product doesn’t sell, that’s my loss and Amazon can ship it back to me to free up some shelfspace.

Let’s see if I can get this confirmed or corrected by someone more knowledgeable than the Internet. Zack confirmed it.

That leaves New Product Introduction. Does that mean that the first time Amazon orders that product from you, it will have a separate code? Why would that be the case? Again, I’m lacking domain knowledge. For now, I’ll assume you can handle it like New Order.

Handling the variants

Now that I have an idea of the variants, I need to decide how to deal with them. That’s not a technical issue; it depends on the business needs. Since this exercise takes place in a fictitious context, there’s no one I can ask questions about the business. No matter, I might not be able to get answers, but I still should be able to figure out the questions.

The first one is whether we use consignment or not. It seems to me that we either do all our orders with consignment or none of them. That implies that we receive either NE-orders (New Order) or CN-orders (Consigned Order). That’s an understanding we need to come to with Amazon before we start processing their EDI messages. Other than that, I don’t expect a difference in the way the orders need to be routed. In both cases, the warehouse needs to fulfill the order and Finance needs to process it. How Finance processes each order will be different, but that’s beyond my concern.

A rush order may be a simple boolean flag in the system, or it may have to kick off its own, separate flow, depending on how the business operates. Does the business need me to do something special in this case? If there’s a separate flow, can we kick that off based on the simple boolean flag? That seems reasonable to me and it means that we can map the message regardless of the impact a rush order has on the business. I might need to route it somewhere else if there’s a special department handling rush orders, though.

The considerations for a new product introduction are similar to those for rush orders. If there’s a special flow, can we kick it off based on a boolean flag? Because that would make mapping simple. If we need to inform specific people of a new product introduction, we can do that based on the flag as well.

A minimal mapping

Even without the answers, I can make some reasonable assumptions about how the system should work and create a mapping based on that. I’m not going to map the entire 850, because that’s not what I’m trying to figure out here. I’m interested in handling the different variants and for that, I only need to map the BEG-segment. I can get away with that, because all three variants—NE, NP, and RO—are basically the same, except for a flag or two. Yes, I’m assuming non-consigned orders, but even that doesn’t make a big difference. For handling consigned orders, just swap out NE for CN and keep the flags. Okay, let’s open Mappings and start mapping.

I’ll come up with my own custom target JSON based on the implementation guide. Yes, this is cheating, because typically you have a defined JSON shape you need to map to, but the principle is the same.

I decided to go with two flags: one for rush order, one for product introduction. Another option is to create a field type that can be normal, rush, or introduction. Doesn’t matter too much; I just like the flags.

The source JSON is just a BEG-segment. That’s small enough that I can type the EDI by hand. However, in order to do the mapping, I need to convert it to JSON, because that’s what Mappings uses. I’ll use Inspector to translate my handcrafted segment to JEDI, which is Stedi’s JSON representation of EDI.

Inspector doesn’t like that single segment very much. I guess I should tell it which transaction set it’s dealing with.

Hey, I just noticed that the Amazon implementation guide provides sample data for each individual segment, so I didn’t have to type it by hand. That’s marvelous.

I add a transaction set identifier code. That’s still not enough to make Inspector happy, but it’s enough to keep it satisfied and it does its best to produce some JEDI. It looks fine for my purposes, so kudos to Inspector.

The purchase order is trivial to map, because it’s a one-to-one copy of a specific field.

The date isn’t much harder. It just requires a minimal bit of conversion, because I like dashes in my date.

Will the flags be more challenging?

That’s not quite right. The code in the sample JEDI isn’t NE, but new_order_NE. JEDI makes the values more readable, but now I have to figure out what the JEDIfied versions are of RO and NP. Fortunately, Inspector can help me here.

Now that I know that, the mapping expressions for the flags will be simple.

That’s it?

The whole exercise was less of a hassle than I expected to be honest. Granted, I made things easy on myself by assuming only a single transaction set in the EDI message and by mapping only a single segment, but why would I want to make things hard for myself?

That’s not the real reason it was easier than expected, though. The real reason is that the variants of the Amazon 850 purchase order are all pretty much the same. I was able to handle them with nothing more than two flags. Most transaction sets that have variants will be more difficult to handle. If you’re disappointed by the lack of suffering I had to go through this time, then you can take comfort in the fact that the next transaction set with variants is bound to cause me more of a headache.