How To Add New Badge

This describes the steps for adding a new Badge. Also see Badge Expectations (Attributes)

It helps to know how the badge fits into the Constellation of Badges.

Generally, there are role-based Badges and Progress Chip badges. The main distinction is a Role-based badge depends on performing certain tasks and a Progress Chip badge depends on repeating a certain task a number of times.

This starts out describing a Progress Chip badge (because I haven't done one yet and when I get it working, I won't remember how I did it, so I'm writing it down).

To orient, check out the BadgeOS Structure page. This takes the perspective of someone sitting at the WordPress BadgeOS menu.


There is also a Checklist


  1. Decide if we're adding a new Role-based badge, or a Themed Badge. The Tiny Door Progress Chip will be Themed.
  2. Decide if an existing Achievement Type will work, or if we need a new Achievement Type. Trying out adding a New Achievement Type of "Theme (Close-ended)"
  3. Sub-Achievements are what most often show up as Badges and Progress Chips. These are the "steps" that build up to a Badge.
  4. For a Themed Badge, You would create a new record under the BadgeOS -> Themata (Closed) or Themata (Open).
  5. Complete the Form for the new Badge. This shell is given, and then we'll add the steps.
    • Name (checking the perma-link is OK too)
    • Type up a description, with references to the site, or how it is connected, or whatever gives it remarkability.
    • Create a Badge Image and give it an appropriate color.
    • This badge is earned by Completing Steps (select from the pull-down).
    • Give it a congratulatory text.
    • "Hidden?" field is set to "Show to User"
    • Save this for now. We need to make sure we have a sub-achievement we can refer to for the Steps.
  6. For a Closed Theme, each "step" has a unique identity that we are able to map one-to-one with a location or other feature in the real world. (For Open Themes, the count just keeps increasing to obtain higher levels of badge, the progress isn't a percentage of the goal, but just a number of times the achievement has been performed. In both cases, we just need a single sub-achievement time. Let's create that now.
  7. Navigate to BadgeOS -> sub-achievements and create a new record. The fields to be completed are:
    • Name (checking the perma-link is OK too) Our example here is "Visit Tiny Door"
    • Description not required.
    • Badge image not required.
    • "Earned By" is set to "Admin-awarded Only" (actually, this is an automated call from the server.)
    • "Maximum Earnings": -1 (limit is imposed by the system awarding the badge)
  8. Save this and return to the Badge instance. We'll add steps based on the sub-achievement.
  9. For each of the "steps" in this Theme — for each Tiny Door, as an example — Add a "Required Step" providing these fields:
    • Specific Achievement of Type …
    • Sub-achievement
    • The specific sub-achievement just entered above (Visit Tiny Door, as an example)
    • 1 times
    • Then, the field that identifies this step to the rest of the world: "Label" should correspond with the step:
      • Be unique across all steps within this Badge.
      • Be readable by humans
      • Be easy to match up with what is in the Real World. "TD #1" is too terse. "Tiny Door #1 - Krog Tunnel" is great.

Technical Notes

  • The Label is what we use as humans to match the arrival at a location with the step that should be checked off.
  • It's also what the human would use to assign the Sub Achievement's unique Primary Key to the API call that the system that tracks the arrivals will call.
  • Bundling these steps under a Badge allows reporting progress toward that badge.
  • Sub-Achievements have a post_name that hyphenates the Title and look more like a Badge in that they are explicitly named as requirements for a given badge.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License