Understanding Category Administration -and- Using the Administrator HUD

Category Administration -and- Using the Administrator HUD

Marvelous Mania offers Organizers an Administrator HUD.  It's the same HUD that everybody else gets, except for two differences:

  1. It can be copied but not transferred.  This is to ensure that only the designated Organizers get a HUD.
  2. It has an extra script to handle the administrator functions.

Even if an Organizer uses the REST APIs to add or remove tokens to or from their renters, the Administrator HUD is always available to manage the environment when there are system bugs on either side that cause things to not work as planned.

When Can You Administer?

Administration of categories can be done before or after they are published to the HUD.  When they are not on the HUD yet, you can query our administrator site to get tokens of a specific state.  To use the Query site, you will need:

  • Entry Code.  This is the 8-character entry code assigned when the category was created.
  • State.  The state of the entries you want to query.  You can only query state one state at a time.  Querying Created is possible, but the results are largely meaningless.
  • Avatar UUID.  The UUID of the authorized registrant.
  • Secret Code.  The 50 character Secret API code assigned to the category.
    • We use an independent Secret Code because the secret code is never published, and this is what guarantees your security.  The Entry Code can be published.

Understanding the Token State

In the diagram above, you can see the token has four states.

  • When tokens are first created they have a Created state.  This means that they exist, but they have not been used by anybody to register an item.  Unless somebody registers an item with this token, the state never changes from Created.
  • The goal of all tokens is to reach a state of Accepted.  Once a token is in this state, it can be published to the HUD.
    • Many Marvelous Mania categories are auto-accept.  This means that as soon as an item is registered, it is automatically accepted.  Organizers can set their categories to auto-accept as well.
  • If the category is not auto-accepted, registration updates the status to Registered.  This means an administrator, must manually accept the token or flag an issue with it.  Management of the state is the primary function of the Administrator HUD.
  • If the administrator flags a token as Issue, the person will get an Instant Message from their Item with the issue you provided.  They can also manually request a "Status", and see the reason you provided.  You have 50 characters to explain what is wrong with their item object.  When they fix the problem, the registration returns to Registered, and you have to verify it again.  The only way to get the status to Accepted is if the administrator manually accepts the item.
    • There is an exception to this rule.  If the Category auto-accepts, the Issue status is set to Accepted.

What do you query and why?

  • You use Registered to identify the items you need to review and accept.
  • You use Accepted to see what your category looks like prior to it being published.  It is possible to share the information with other colleagues so they too can see the category before it's published.
  • You use Issue, to identify items whose issues have not been addressed.  This is to follow up with Designers or Residents who possibly didn't know there was an issue.

Query For All States (CSV Export)

This feature allows you to perform an export of all items in a category regardless of state.  We use a CSV export format as compared to an XLSX format to avoid security issues.  CSV will always open in your local spreadsheet software, but XLSX usually requires a file to be unblocked before it can be opened.

The CSV Exports these fields.

To run the export you use this link: http://admin.mm4sl.info/inquiry/items.html

The result will be a CSV file with the same name as the category code.

 

Query For Pre-Published States (As Notecard)

To get items that you can administer before your event is published, you use this form: https://admin.mm4sl.info/admin/query.html .  The output of this web page is a text document that you save as a notecard in Second Life.  Then open the notecard in the HUD using the notecard's UUID.  This opens a custom category that you can then administer.

  • Marvelous Mania Category - Is the category code assigned to your category when it was created.  It's 6-8 characters in length.
  • Administrator UUID - Is the authorized registrant for the category.  (a.k.a. the administrator)
  • Category Secret Code - Is the secret code assigned to the category.  This is the 50-character code provided to you after the category was created.
  • State - Is one of the states you want to pull your information from.  One of Created, Registered, Issue or  Accepted
  • Page Size - Are the sizes of category listings you want to create.  The default is 100.  Setting the size greater than 100 is done at your own peril!  Size dictates how many items are shown in a page for a category.

When you click the "Identify Category Pages" button, you will get an HTML document that:

  1. Identifies the event you requested.
  2. Provides a summary of all tokens in the category, with their state and count.
    • If there are no tokens with other states, they are not shown.
  3. Page summary for each category.  If you left the page size at 100, and the category had 275 items, then you'd see three links:
    1. Page 1 is items 1 to 100.
    2. Page 2 is items 101 to 200.
    3. Page 3 is items 201 to 275.

 

When you click link, you will see an output with gibberish on it.  Select the entire contents of this page, then copy it ...

 

And paste it into a Notecard in Second Life.  You can use any name you want for the name. Then save it.  Now right click the notecard, and select it's UUID.  Selection for the UUID can be done in either the Linden Labs Viewer (as shown here) or the Firestorm Viewer:

Opening Your Custom Category

Now open the Marvelous Mania HUD, and on the category tab, click the GEAR icon, select Custom and paste the UUID into the textbox.  This feature works on the regular HUD, so that you can share the contents of your category with other team members before the category is published, to facilitate activities such as blogging and other marketing promotions.  Note: You still need the special HUD to administer the category.

 

You will now see all of the information that you queried from the form above, and it will act and react just like a published Category page on the HUD.  As soon as you return to the category listing or your favourites, the HUD forgets about your custom category, and to open it again, you'll have to repeat the process above, to open a custom category.

 

Requesting Administrative Access

Whether you are looking at a published page or a custom page, you now need to request "Admin" access to the category in order to administer it.  Click the GEAR icon, and select "Admin".  While this button exists on the regular HUD, it doesn't do anything when selected.  You need the special Marvelous Mania Administrator HUD for it to work.

 

In order to be granted access to the category, you have to be identified as an administrator for that category on our central database.  If you are not the administrator, your attempt to access the category will result in a "denied" message.  This prevents you from accidentally trying to administer categories that you do not have access to.

 

Administering the Category

Identifying an Item Object

If you are granted Admin access, you will get an "Identify" button.  You use this Button to ask a hunt item to identify itself to you.  This button does not work for other types of events, where a Registration HUD is used to register ads.

  • Note: Throughout this web page we use the phrase "item object" to refer to the object that gives or sells items.  The object can be a Marvelous Mania branded kiosk or sales item, or your own.  The only requirement for the object is that they must give out the "Marvelous Mania - Information" notecard when the item is given away or sold.  We will provide the "Marvelous Mania - Root" script that registers items for your end-clients or designers, so that you can place it into any object with our notecard.  We strongly recommend you make or buy your own item objects, in order to solidify your brand within our system.

In this example, I am on a different region.  When you enter the initial Admin menu, it compares the Region where the item object was registered, to your current region, and gives you a warning message telling you they are different.  The reason this Warning is important, is because "Identify" works by sending a coded message to the entire region, asking the item object to identify itself.  If you are on the wrong region, the item object will never receive the message and the "Identify" request times out.

Let's begin by clicking "Identify" (while on the wrong region):

It sends a message to the item object, but since this item object is not on the region where I am currently located, the request times out:

 

We could decide to delete the listing, since we could not find the item object on the region.  This removes the item from the HUD listing.  Note, due to technical reasons the HUD will not update until the following morning (or, until you refresh the category listing using the steps above).  Whenever you ask to delete something, it asks to confirm your action, because once it is done, it cannot be undone.

 

You'll notice that both of these dialog boxes contain extra functions.  This is because many events do not have "item objects" for you to identify, because they used the Registration HUD to create the ad.  The only information you have is what is in the ad itself.  In these cases you can work with the server to administer the item.  You get these options:

  • Server - Performs an inquiry on the server to determine the status of the item.  The message you see is identical to the message the token owner sees.
  • Accept - Accepts the item, regardless of it's state.  (See more on "Accept" below).
  • Issue - Forces the item into an ISSUE state, where you can provide a reason why it's an issue.  (See more on "Issue" below).

 

For this example, we really want to identify the item object, so we will teleport to the real destination that contains the item object, and click "Identify".

 

This time, the item object responds, and gives you some information about itself.

It identifies the following things:

  • Located at.  Where the item object is located.  It gives you an actual location as a SLURL.  This allows you to teleport to the item object, or if the parcel has a fixed landing point, you will get a red arrow identifying it's exact location.  This is exceptionally useful for HUNTs, so that you don't have to search for the object.  For other types of categories, you might have policies that specify where the object has to be positioned, and this feature will be useful in helping you verify object item locations.
  • Distance.  This is the number of meters from your current location to the location of the item object.  In this example, I'm 7 meters from the item object.
  • Token.  This is the token they received when they bought from one of your item objects, or you gave to them.
  • State. Is the internal state of the item, as described above.
  • Owner. Is the individual who registered the item.  It's shown with their URI so that you can open their profile, to send an instant message to them without having to look up their details.
  • Store. Is the name of the store, or location they registered.
  • Item. For Stores, Music Venues, Art venues, and Locations, this is the first of a two line comment about the store or location they registered.  For sales items, or hunt items, this is the name of the item they are selling or giving away to the Resident.
  • Comment. For Stores, Music Venues, Art venues, and Locations, this is the second line of a two line comment about the store or location.  For sales items, this is a one line comment about the item.  For Hunts, this is a comment about the item, or hint to help the Resident find the item.
  • Folder. Is the name of the folder.
    • Note: The way the folder works is, when a resident clicks the item object, we send them the contents of the item object (excluding the script). Since there is always a minimum of two items (the landmark and our Marvelous Mania Information card) we have to send them as an Inventory List which becomes a folder in the resident's inventory, so we need a name for that, and this is the FOLDER.
    • Note: Every folder in the system has a prefix consisting of a few letters, a dash, and a number.  This Prefix forces all of the similarly prefixed folders to be grouped together in inventory. It is a way of helping the Resident, at a glance, figure out if they have all the things they were looking for.  Without the prefix, the HUD would create an Inventory management problem for Residents because they would get dozens of folders that may or may not be related to the things they see on their HUD, and they have to examine each one to determine their purpose.
  • Price. Is the price the item object will charge for the contents.  If the Category has a Price, it's the category price.  If the category uses User Define pricing, then the price is what the owner set for the contents.

 

Once you are in administration mode, the GEAR icon no longer shows the standard Item menu, instead it takes you straight to the admin menu.  Ultimately this is to save you from clicking Admin over and over for every item you are validating or accepting.  The standard Item menu appears again when you click on the Category or Favourites tab, and then go back to the Item listing.  If you minimize the HUD, the system remembers that you were in Admin mode.

Post Identification Options

Once you have confirmed that you can communicate with the item object, you now have several options:

  • Accept.
    • Used to accept the item.
    • If the item is already accepted, this really doesn't do anything.
    • After you accept an item, your HUD forces the item to perform a status update.
      • This will trigger logic and allow the item object to become active when the category starts, it also sends a status update message to the owner (whether they are online or not).
      • Note, unless the item has a state of "Accepted", the item object will not give out or sell items, and it will not appear in the HUD when the category is published.
      • If the item is not on the region where you perform this operation, the item is not updated.

 

  • Issue.  Used to identify an issue with an item.
    • You can identify an issue with an item, regardless of it's status.  This includes items where the category is set to auto-accept.  It allows you to force an accepted item into an Issue state.
      • Note: If the category is auto-accept, fixed issues are also auto-accepted.
      • Note: If the category is not auto-accept, fixed issues have a state of Registered. You use this information to figure out what the designer has done, if anything.
        • If the state of an item is "Registered", then it means the designer did something and re-registered their ad.
        • If the state of an item is "Issue", then it means the designer did not re-register their ad.  This indicates the designer has not resolved the issue; either because they cannot, or because they were unaware that they had a problem to fix.  In this case, you can follow up with the designer, using the link to their profile that the "Identify" dialog gives you.
    • Selecting Issue gives you a text box, where you can put in a message.
      • If the message is larger than 50 characters, the admin HUD will display a message in local chat, give it's length and prevent the issue from being raised.  You can then adjust your message appropriately.  Note, new line characters and leading and trailing spaces are automatically trimmed.
    • After you submit the issue, your admin HUD forces the item to perform a status update.
      • This will trigger logic to send an instant message to the item owner identifying that there was a problem with their ad.
      • It also tells the item object that it cannot give out or sell items when the category starts.
      • Designers can still make changes to their ad after the start date, they will just experience a delay before the item appears on the HUD; assuming it is accepted.
      • If the item is not on the region where you perform this operation, the item is not updated.

 

  • Delete... (with confirmation).
    • You may want to perform this action if you cannot find the item, or if the quality of the item is so poor that you want to remove the item from your category and refund the designer's fee.  Your policy should be explicit on when and why you delete items, and what happens to the designer's fee, if anything, when this occurs.
    • When you delete, it removes the entry from the central database, but for technical reasons, the HUD cannot be updated to exclude the deleted item.  You'll just have to learn to work around this limitation.  You will discover the item is removed when you update your custom category using the steps above, or wait for the category to be republished to the HUD the following morning.
    • After you delete, your admin HUD forces the item to perform a status update.
      • This will trigger logic to send an instant message to the item owner identifying that the token could not be found.
      • It also prevents the item from giving out, or selling items when the category starts.
      • If the item is not on the region where you perform this operation, the item is not updated.

 

  • Identify. Asks the item object to re-identify itself.  This is often used when you need to identify who the owner is to contact them.

 

  • Folder.  Gives you a copy of the contents of the folder the item would give to residents.
    • The objective of Folder is to verify the items that are being given out, to make sure they meet your category's quality standards.
    • When you use this option, you get a folder of items without paying for the contents.
    • You must act responsibly when you get these free items.
    • If you do like something and want a copy, you should reward the designer with the price they are asking.
      • Please do not use the Administrator HUD to get free stuff from your designers, unless you are explicit in your policy about this feature.
      • Note: Quertie (Marvelous Mania CEO) also has this privilege for all categories, and abides by the same principal to pay the listed price, rather than getting items for free.

 

  • Status.  Forces the item to update itself with the status on the database.
    • This is not required if you Accept, Issue or Delete the token from your category, as this step is automatically performed.
    • Status will send an instant message to the owner, so even if they are offline, they should receive your status updates.
    • Note: While we recognize that some designers want notecards instead of IMs, we are unable to accommodate their needs because it's impossible to create and send notecards from scripts.