Care and Feeding of the SL Marketplace Magic Box

The most critical component any SL Marketplace Merchant will use is the venerable “Magic Box”. Originally created by the author(s) of the SL Exchange virtual shopping site, the Magic Box has been the focus of many ill-tempered words. While not totally its fault, there are several quirks about the Magic Box that, once learned and used, can smooth the delivery of items purchased by your Customers.

Please note that since mid-July, 2015 the Second Life Marketplace has switched to Viewer Managed Marketplace (VMM). This means the venerable Magic Box has been officially retired and should NOT be used for anything new. If you are still using one or more of these, please update.

Magic Box Basics

The Magic Box is actually not that magical. Like many other “smart” devices used in Second Life, it is a scripted device. The scripts are written in the standard LSL Scripting language that runs every other active device. What makes the Magic Box special is the fact that it is designed to talk and work with the SL Marketplace. It’s a lot like a vending machine, except instead of depositing coins into the front and selecting your choice of snack food or soft drink, the Magic Box gets all its instructions from the SL Marketplace. It’s kind of like a vending machine and a TV Remote Control all glued together.

Another major difference between a Magic Box and a vending machine is that you do not need to put multiple copies of your products inside; you only need to put one copy of each product inside. As long as the products are copyable then that one copy can be used over and over again to deliver a new separate copy for each purchase. (The exception to this is when you have a non-copyable item to sell, however we will be ignoring this situation as most Merchants do not sell non-copyable items.)

Magic Box Limits

As with most things in life, Magic Boxes have limits that should be observed as well. One of the most important limits is the maximum number of items you can put inside each Magic Box. There are a lot of opinions on this number, but generally speaking it is best to keep the number of items in any one Magic Box below 100. (I personally like to keep less than 50 in each Magic Box, but that’s not a hard and fast limit either.) Some folks will tell you that they have close to 500 items in their one Magic Box, but practically speaking that’s just way too many. If you are doing a lot of business during the day, splitting your products up among several Magic Boxes means that the “load” (how hard the Magic Boxes have to work to keep up with deliveries) is shared among them all.

The other limit is with the number of Magic Boxes that you may have rezzed out. The only limit here is the number of Prims you have available. Since you can put the same product in multiple Magic Boxes, it is also best to have duplicate “Backup” Magic Boxes located on another Sim. That way if the Sim containing your primary Magic Boxes is offline or is unavailable for some reason, the Marketplace can always use the backup copies and thus not miss or fail a delivery. If you have some products that are pretty “hot” (meaning lots of deliveries every day … usually Freebies and similar) then it never hurts to have two or more backup Magic Boxes for those. As with computers in general, having backups is a good idea and, in the case of Magic Boxes, the extra backups are pretty easy to set up. Once set up, the only thing you watch carefully is to make sure you update all of them anytime you update a product. Thus if you release an update to your Whiz-Bang 2000 (for example, updating it to the new Whiz-Bang 3000) then you must make sure you update every Magic Box that contains the old version item.

Purchase and Delivery – Step By Step

Lets take a quick tour through the purchase and delivery process. When a Customer purchases one of your items from the SL Marketplace, the web site talks with one of your Magic Boxes, telling it what product to deliver and to whom. What the Marketplace says and what the Magic Box says is really just like a typical conversation, so we’ll “eavesdrop” on that conversation: (SLM is the SL Marketplace and MB is the Magic Box)

SLM: An Avatar named “Joe Customer” just purchased a “Whiz-Bang 2000” so please send them a copy.

MB: Okay, sent it.

SLM: Well done. Thank you.

If you are using ANS (Automatic Notification of Sale) and your Magic Box supports ANS then the Marketplace and Magic Box have one more short little “chat”:

SLM: Please send out the ANS Result.

MB: Sent it, all done.

(Note that the Marketplace doesn’t bother saying “Thanks” after the ANS Result is acknowledged, it just assumes all is okay.)

Peek Behind the Curtain

Obviously there is a bit more involved than just the above short conversation (although not that much), but there are some details that we need to understand. For example, if you have more than one Magic Box and the Whiz-Bang 2000 is in only one of them, how does the Marketplace know which Magic Box to talk to? In fact, are you even allowed to do that, put different products in different Magic Boxes?

Yes, in fact you are allowed to do that. It’s not only allowed, it is even recommended especially if you have lots of products for sale or you just wish to keep your products organized into different Magic Boxes. (For example, one Magic Box for shoes, one for dresses, one for hair, etc.) I always rename my Magic Boxes so I know what products are contained in each one. Even more important, you can put the same product into multiple Magic Boxes.

As for how Marketplace knows which products are in which boxes, you have to tell it to “ask” the Magic Boxes. This function is called “Synchronizing” or just “Syncing” for short. On the Marketplace Merchant page for managing your listings is a button marked “Sync Marketplace with Magic Boxes”. The button is located near the top of the page as shown here:

From the Marketplace Merchant Home Page (sometimes called the Marketplace Merchant Dashboard), choose the Manage Listings function under the Inventory section as shown here:

After you click the “Sync Marketplace with Magic Boxes” button, it’s best to take a short break. Depending on how many products you have and how many Magic Boxes you have, the Marketplace can take quite some time to complete the process.

NOTE: When it comes to Magic Boxes and the Marketplace, Patience is more than a virtue … it’s a requirement. The extra five minutes you wait patiently can save you hours of frustration and problems later. Do NOT rush the Sync process. Give it some time then give it some more time. I typically wait about 1-2 minutes per Magic Box just to be sure.

After you’ve patiently waited and you’re ready to see how it worked, hit the “Refresh” button in your web browser or choose the Inventory > Manage Listings function again to see the results. You will not see a list of which products are in which Magic Boxes, but you should see that all of your products are listed as “Available”. If any of your products do not show up or are marked as “Unavailable” then you may have rushed the process a bit or you may need to take some extra steps to fix the problem. I cannot stress enough how important it is to wait a sufficient time before refreshing the Manage Listings page. If you see products marked as “Unavailable” but you know they are in at least one Magic Box, it may be time do a little troubleshooting to fix the problem. (We’ll get into troubleshooting a bit later on.)

That’s all well and good but how does the Marketplace know which Magic Boxes you have? The answer to that question is a bit more complicated. Since the Magic Box was originally created for the old XStreet SL (and before that it was called “SL Exchange”) web site, you actually have to use the old XStreet SL site in order to “teach” the Marketplace about all of your Magic Boxes.

The Magic Box Status Function

From the Merchant Home page, choose the “Magic Box status” function under the Inventory section as shown here:

This function will open a new tab or window in your web browser then it will stop and remind you that XStreet SL is no longer open for purchases. Click the “Cancel” button on the warning to dismiss it and go on to the “My Inventory” page. The warning message is shown here:

In the very bottom left-hand corner of the My Inventory page is a list of all the “Registered Servers” (AKA Magic Boxes) that are known to the Marketplace. An example is shown here:

If there are any Magic Boxes listed that you know have been removed, use the “Force Remove” function to remove them:

Any Magic Boxes that you know are rezzed and working but do not show in the list should be manually reset using the Owner Menu – Reset function. Simply touch the Magic Box and choose “Reset” from the menu as shown here:

The “Sledgehammer” Solution

Sometimes when you are experiencing a large number of delivery failures, it’s best to use what I call the “Sledgehammer” method. Note that you should use this sparingly, most likely only when you do a massive rearrangement of products in Magic Boxes or just after updating your Magic Boxes to ensure you have the latest version. Because this process removes every single Magic Box from the Marketplace’s memory, it should only be used during a time when you know that you will have as few deliveries as possible.

It works like this:

  1. Use the “Magic Box status” page to “Force Remove” every single listed Magic Box (completely empty the Registered Servers list). Verify that you’ve removed them all by using the Refresh function of your web browser to get a new list.
  2. Start at your first Magic Box and use the Owner Menu – Reset function to force the Magic Box to manually register with the Marketplace. Wait up to a minute after each Magic Box has reset then refresh the web page and verify that the Magic Box appears in the list. Do not move to the next Magic Box until the one you just reset appears in the list properly. If it shows up then skip to step #5.
  3. In case the Magic Box doesn’t show up or won’t reset properly (for example the Owner Menu does not appear when you touch the Magic Box), right-click and “Edit” the Magic Box then use the Tools > Reset Scripts in Selection function in your Viewer to reset every script. Verify that the Magic Box shows up on the list of Registered Servers after the Magic Box has changed colors and has returned to its normal white color. If the Magic Box appears properly then skip to step #5.
  4. Right-click and “Take” the Magic Box into Inventory then immediately rez it back out. Wait for it to complete its color change and return to the normal white color. If the Magic Box still does not appear in the list then replace it with a new Magic Box and put your items into the new box. Discard the old box (as it is probably FUBAR and should not be used anyway).
  5. Once the Magic Box appears in the list properly, move to your next Magic Box and repeat starting at step #2 above. Continue this process until all of your Magic Boxes appear in the list of Registered Servers properly.
  6. Close the “My Inventory” web page and return to the Merchant Home page on the Marketplace. Use the “Sync Marketplace with Magic Boxes” function on the Inventory > Manage Listings page and wait a suitable period of time to ensure all Magic Boxes have been fully “synchronized”. Upon refreshing you should see that all of your products appear as Available.

Updating Your Magic Boxes

There are a couple schools of thought on how to update your Magic Boxes, however I only recommend replacing the Magic Box completely. While it should be okay to just replace the scripts, that can also lead to other problems. The safest and most reliable method is to just replace the entire Magic Box with a fresh copy purchased (for free) from the Marketplace.

The regular (without ANS) Magic Box is found here. However if you use ANS then you should obtain a new Magic Box with ANS here.

The process goes like this:

  1. Right-click and Edit the Magic Box you are replacing then copy the entire contents (your items only; do not include the Scripts) into a folder within your Inventory. You can create and use a temporary folder if you wish, however it never hurts to have extra copies of your Magic Box’s contents.
  2. Delete the old Magic Box.
  3. Rez the newly obtained Magic Box and wait for it to complete its color change and return to the normal white color. If you wish to change the name of the Magic Box, do so now before proceeding to the next step.
  4. Right-click and Edit the new Magic Box then copy the contents saved in step #1 into the Contents tab of the new Magic Box. Wait for it to complete its color change sequence and return to the normal white color.
  5. Use the Inventory > Magic Box status function from the Merchant Home Page to display the list of Registered Servers (Magic Boxes). Use the “Force Remove” function to remove the old (and now deleted) Magic Box then ensure the newly rezzed Magic Box appears in the list properly.
  6. Move to the next Magic Box and repeat the process starting at step #1 until you have updated and replaced every Magic Box. Double-check that the list of Registered Servers is correct.
  7. Once you are sure that every Magic Box appears properly in the list, close the My Inventory web page and return to the Merchant Home Page on the Marketplace. Then use the “Sync Marketplace with Magic Boxes” function on the Inventory > Manage Listings web page to synchronize the Marketplace with all of your new Magic Boxes.

After you have waited the proper time (and remember that patience pays off big-time here), refresh the Manage Listings page to verify that all of your products are “Available”.

Final Thoughts

The venerable Magic Box may be a bit long in the tooth, but it’s still a very viable and usable device for delivering your products to customers. Many of the ills that befall (and are blamed on) the Magic Box are actually symptoms and side-effects of other issues within Second Life. I welcome the advent of the new Direct Delivery method of delivering products, but unfortunately what I’ve read so far is a bit too contorted to make it readily adoptable by the Merchant Community. The extra step of having a secondary “shim” inventory that is managed and controlled by the Marketplace is a necessary evil of the method overall, however Linden Lab’s ability to undertake and succeed at releasing brand-new software functionality leads me to a level of concern that will only be put aside by putting their code where their mouths are. We saw how Viewer 2 worked out. Even though it was outsourced and thus does not land squarely on their shoulders, there have been many other adventures in codeland that I think justify my trepidation.

Time will tell. We no doubt will suffer some rather unexpected and spectacular failures up front … those are to be expected. However the way they respond, the speed at which they recognize, acknowledge and repair those failures will be the true test. If their response to failures in DD is the same as their response to bugs/oversights in the Marketplace and most recently the delayed/failing overnight delivery bug then I fear the final result will be the wholesale abandonment of the Marketplace and, by extension, Second Life in general. We are already seeing the effects of a general malaise in the customer base that is a direct product of LL’s own lack of care and concern, and I fear that the same attitude applied to their newest starlet (DD) will put the final nail in the coffin that … well … isn’t that where Vampires live anyway?

Cross your fingers folks. At the very least, bookmark this page and keep it handy … just in case Direct Delivery lands with a sickening thud instead of the much-needed light-footed¬†pirouette¬†that it can be.

Visit the DGP4SL Store on SL Marketplace


One Comment on Care and Feeding of the SL Marketplace Magic Box

    […] Link: Care and Feeding of the SL Marketplace Magic Box : DGP4SL Blog […]