The Technical Side of Aloha POS Integration

In my last blog entry, I discussed some POS Integration related business issues.  Now I would like to discuss the implementation issues associated with POS Integration on various platforms.    Doing POS Integration is kind of like my ascent up La Plata peak (14,336) outside of Leadville, Colorado.   Before you even begin the true climb, you have an approach hike of several miles, uphill, through a forest; then you take a left and start climbing up a gully to reach the saddle below the summit.   Now, the climbing guide we used left me with the impression that the hike up the gully was fairly short and had just a few switchbacks.  Yet, THAT’S NOT WHAT IT FELT LIKE TO ME!   I distinctly remember that gully as being incredibly grueling, with what seemed like a THOUSAND SWITCHBACKS.  When we finally got to the top of the gully and reached the saddle, we still had 1600ft to climb in 1.25miles, according to the guidebook.  Ugh!   The wind was blasting and all the new snow on top of the boulder field made it quite treacherous.    Though eventually, we made it up to the top and was rewarded by the fantastic view.

So is POS Integration really like that?   Well, sometimes, YES, but it’s generally not that bad.   There have been a few times when I felt like my back was absolutely pinned to the wall – when the POS is crashing and you don’t know why and the POS dealer and POS manufacturer take the approach that since the POS didn’t randomly crash before you connected to it, it must be YOUR FAULT! You don’t want to be in that situation.  So let’ talk about what you can do with each POS Manufacturer’s SDKs.    Please understand that since I am under NDA (Non-Disclosure Agreement) with a number of these POS companies, I am can only share my opinion as I am unable to divulge the specifics of each POS SDK.

Let’s start with Aloha – I’ll discuss other POS platforms in a future blog entry.

We have worked with every software interface Aloha has created (except the credit card API which was never released to us).   I would describe the types of Aloha APIs as being: 1) Order Placement / Cashiering; 2) Event Monitoring; 3) Print Modification; 4) Data Dictionary.

Let’s first discuss the Order Placement.   Like all Aloha APIs, the Order Placement API uses Microsoft’s “Common Object Model” or COM (DCOM), so it is easy to link into any Microsoft Visual Studio project.  The interface is designed to mimic what a cashier does when placing an order.   There are a lot of function calls available via this interface, which is good.   The bad news is that all the calls are fairly low level.    If your goal is simply to add 1 item to a new check, say “Diet Coke,” you have to make a lot of calls to the API; a minimum of 7 calls to the API (only 2 of which are specific to the item), in the right order, probably need to be made.  Items have to be ordered EXACTLY RIGHT.  By this I mean Aloha WILL NOT accept an incomplete order for an item or one that is improperly structured.   For example, consider the following order: “rib-eye steak medium rare, dinner salad with French dressing, baked potato with bacon and sour cream.”   Complex Aloha items can be defined as a tree structure, where choices are configured as children of the parent item.  In this case, if dinner salad and baked potato are configured as children, then the order has to be placed via the Aloha API in that same hierarchy; the structure continues down to the next level as well, with the “French Dressing” being a child of the Dinner Salad and the “Bacon and Sour Cream” a child of the Baked Potato.   This makes placing orders for items in Aloha quite challenging because both the order of the calls and the structure of the data in those calls must be correct, otherwise, Aloha rejects the entire item.   As Aloha allows for an infinite level of children in the item structure (or even the definition of infinite loops in menu items which we have seen very frequently), you really have to have your act together when coding a robust ordering interface for Aloha.   If you don’t place the order correctly, Aloha reports an error back to you, effectively telling you a piece is missing; BUT ALOHA DOESN’T TELL YOU WHAT IS MISSING.

You can also pay for orders via this interface, including credit card and non-credit card payment types.   If you want to use Aloha to process credit cards, this interface works well.   This interface’s weakness is promotions.    For years the documents have said that although the promo parts of the interface are “defined,” they are not “implemented.”   I have come to discover that some are implemented for certain versions; but Aloha doesn’t share that information, you have to discover it yourself by writing the code and seeing if it works.  😦

The Aloha Event Monitoring interface allows you to create a DLL that links into the Aloha Front of House interface to “listen” to what is going on at each terminal.  This isn’t a “keystroke by keystroke” type of event monitor: Aloha has predefined a collection of “events of interest” which roughly correspond to the life of a check and employee events such as “login” and “logout.”   Effectively, when one of these events occur, say adding an item to a check, Aloha calls out to your DLL, telling you a few details of what just happened (“Added Item 123 to Check 456”), and gives your DLL full control of the terminal.  At this point you can take the appropriate action: query the Aloha data dictionary, write to a file, call another service, start a program, whatever you need to do.

This brings up a commonly asked question: “Can I make a call out to the internet from a terminal?”   The answer is NO.    For PCI compliance purposes, you’ll find that Aloha terminals are configured to have no Internet access.  Typically the Aloha Back of House Server is configured with 2 NICs: one for the LAN (to talk to the terminals), and one for the WAN (connecting the Server to the Internet), thus isolating the terminals from the Internet.    In theory, you can configure the terminals to access the Internet; I have done it, but that was way before PCI compliance was a consideration.   Try doing that now and you’ll be fighting the Aloha Dealer and Aloha itself, as they want to protect the Restaurateur and themselves from any security breach liability.    So if you want to access an Internet enabled service (who doesn’t?) from the Front of House, you will need to route your request through the Back of House server.   In practice, you’ll need to take the same approach with every POS you integrate.

Another point to ponder when designing for multiple POS integrations is code reusability across platforms.   If you have been following this blog, you have probably realized that the integration points across POS platforms vary widely, so what can programmer’s re-use?   For all intents and purposes, the only thing that will be reusable is typically the back-end logic of communicating with the target Internet web service.    If your integration requires you to interact with Wait Staff, Cashiers, or get real-time data AND communicate with a web service, you will most likely be building both a Front of House and a Back of House component.    On Aloha, it’s usually easier to extract data from the terminal; on Micros, it is often easier to get the data from the Back of House Server.  In each case, it depends on what data interests you and how you will use that data.   That’s why integrations across multiple POS platforms get so expensive!

Let’s talk about the Aloha Print Modification API.   How this works is that you create a DLL that links into Aloha Front of House; each time Aloha is going to print something, the DLL “sees” the document before it is printed and has the option to change it just before Aloha sends it to the printer.     When Aloha calls out to your DLL, the DLL receives 2 pieces of information: 1) What type of document is being printed, such as a “Guest Check” or a “Kitchen Chit;” 2) The actual print request.   The Print Request is in the form of an XML document consisting of Aloha-defined print requests.   The challenge here is that there is no explicit context about WHAT is being printed.   For example, if a “Guest Check” is being printed and your program wants to know what guest check number it is, then your program needs to traverse the XML document and find the check number.   There is nothing in the XML to say what the check number is; you just have to find it somehow.    Suffice to say, this type of programming can be very tricky because although every Aloha check looks the same, they are NOT!  The document contains everything that is going to be printed on the check, such as “Diet Pepsi” or “Visa,” not “Item 123” and Tender ID “6.”  Like the Event Monitoring Interface, once your DLL is called, you have full control of the terminal to do what you need to do: read the Aloha data dictionary for more information, call another app, read a file, etc.    So now that you have the print document in your hands, you can change it as desired to meet your requirements.   This is a process of inserting the appropriate XML fragments as defined by Aloha into the print document and then returning control back to Aloha to let it perform your defined print request.

Moving on to the Aloha Data Dictionary . . .   This is a rich interface into just about every piece of data in the Aloha system.   The Aloha Data Dictionary allows you access in real time (through the Front of House terminals) all the available data available in the aloha system such as Checks, Employees, etc.   This is the good news: you can learn almost everything about Aloha through this interface.   The bad news: getting to the data is quite tedious.   The data is highly structured and for the most part, you have to start at the top of a data tree and work your way down to the desired point to access the data you need.   You can only ask for a single piece of information at a time; there is no way to ask for all the attributes of a menu item, guest check, or logged on employee.   I am not kidding—it is really tedious to get the data!  Often I am asked if we can write something that gives the third-party “EVERYTHING;” I used to answer that question, “Yes, but please send me your first born child as payment!”  Now I just answer, “NO, don’t be lazy, tell me specifically what you want and we can figure out how to get for you.”  The other problem with accessing data in the data dictionary is that the process is CPU intensive; meaning, it’s slow.    If you really need to access a lot of data via the data dictionary, then you run the risk of slowing down or freezing the terminal while your program gets the data it needs.   So sometimes it’s better to cache static data from the Data Dictionary at startup to eliminate redundant lookups that just chew up time.

Finally, from an Aloha interface perspective, I need to discuss the Aloha database file system.   Instead of using a single large database file to store all of its configuration information, the developers of Aloha elected to put most of this information in Dbase format files (DBFs).   You can read these files with Excel and you can read these files programmatically.   You can write to these files, but that’s dangerous, because Aloha adds fields to these files from time to time with new versions—so you can end up having to write code that treats the DBFs differently, depending on the version.  I am often asked if we can decrypt the transaction log.  The answer is “NO;” I have never tried.   I think reverse engineering something like a POS is a big waste of time.  Aloha does generate DBFs at the end of each business day that records the day’s sale history.

The other point about Aloha you need to understand is that this interface is highly dependent on the Aloha configuration setup for the location.    Although all Aloha APIs work the same way for either Aloha Quick Service or Aloha Table Service, for them to work properly, the Aloha Configuration must be properly defined, licensed (the Aloha Connect license purchased from the dealer), and properly running.  This is by far the biggest headache with Aloha integrations: getting the configuration to stay up and running.  I can say with confidence that 99% of our time spent supporting our Aloha integrations is actually spent on trying to get and keep Aloha itself running, not the integration itself.

So what I have shared about Aloha Integration is really just peeling back the top layer of the onion.  If you are going to be successful in integrating with Aloha, you really need to develop a deep understanding of how Aloha works.   It’s a time consuming process, and Aloha really doesn’t provide a lot of support to you in the process.  Nor is there any community support.   The dealers are experts in configuring Aloha for in-store operations, but really have very little input on how to interact with Aloha from an integration perspective.  So you are pretty much on your own.

If you are going to climb the Aloha POS integration mountain, just keep trudging up those switchbacks and take on the boulder field one step at a time!

For my next blog post, I’ll discuss Micros Integration.