New Issuers: Give Yourself a Badge

If you want to issue Open Badges either as an individual or on behalf of an organization, it may seem like there is a lot of conceptual and tech information to absorb. The easiest way to get to grips with it all is by doing something practical, so in this tutorial we will work through a basic badge issuing process. You will create a badge, award it to yourself and import it into your own Mozilla Backpack! By the end of the tutorial you should be well placed to approach your badge issuing project, however lightweight or extensive it is.

In this tutorial we will carry out the following key badge issuing steps:

creating a badge
including the image and metadata
awarding a badge
creating a badge assertion
baking a badge
embedding the metadata into the image
uploading a badge to the Mozilla Backpack

If you don't already have a Mozilla Backpack account you can create one at any time: http://backpack.openbadges.org

Step 1: Create the Badge

Awarding an Open Badge does involve a few technical tasks, but the first task is simply figuring out what your badge is going to be awarded for. Badges vary enormously in subject matter and activity type, from educational to community skills and beyond. The badge we issue in this tutorial is going to represent being a rookie badge issuer!

Define the Badge Class

Your Open Badge will be defined as a badge class. The badge class describes what the badge represents and is structured in JSON. A number of fields can be included - see the assertion specification for a complete list. For the purposes of this tutorial you can use the following sample, which includes all of the required fields - paste it into a new file:

{
	"name": "Rookie Badge Issuer",
	"description": "Issues great new Open Badges to self.",
	"image": "http://yoursite.com/rookie-badge-issuer.png",
	"criteria": "http://yoursite.com/rookie-badge-criteria.html",
	"issuer": "http://yoursite.com/badge-issuer.json"
}

Replace the domain names/ URLs in the image, criteria and issuer fields to match your own site.
We will create the image file and issuer JSON file soon, but you should adjust the criteria value to match an existing (or new) page on your site - for a real badge this should be a Web page describing the criteria for earning the badge.
Save your badge class as a .json file, giving it rookie-badge-class.json as the file name.

Create the Badge Image

Now let's design an image for the badge. Your badge image should be a square PNG (or SVG) with minimum dimensions of 90px and a maximum file size of 256kb. When you're working on your badge design, it's recommended that you view the result at 50 x 50px, making sure the content remains legible at that size. The badge may end up being displayed in a variety of contexts - taking care over how it scales will help it to have a consistent appearance wherever people see it.

You can use the Chicago Summer of Learning Badge Studio to create a suitable image - design your badge, click Export and save the image to your computer, giving it the same name as the entry in your badge class image field (rookie-badge-issuer.png in the example above).

Designed Badge

Define the Issuer Metadata

As you saw in the badge class JSON, each badge is linked to information about the badge issuer. This is key for authenticating Open Badge awards. We will create a new JSON file for the issuer organization info. As with the badge class, the issuer JSON can include various fields - see the assertion specification for a complete list. Create a new file and copy the following sample issuer JSON, which includes the required fields:

{
	"name": "New Badge Issuer",
	"url": "http://yoursite.com"
}

Alter the name value to whatever you want your name to be as a badge issuer - this could be your name as an individual or the name of your organization/ department/ program. Replace the url value with your website address - this link to the issuer site is used to validate awarded badges for verification. Save the file with the name listed in your badge class issuer field (badge-issuer.json) in the example above.

Note: Some proposed changes to the assertion specification are currently under discussion. See these threads in particular:

Host the Badge

Upload your badge class JSON file, image file and issuer JSON file to your server, making sure the image and issuer JSON are stored at the locations you listed as URLs in the badge class image and issuer fields.

Step 2: Award the Badge

Now you can award yourself the badge! To issue a badge to an earner, you create a badge assertion, also in JSON. This time the metadata will indicate the details of the earner and the badge award itself, as well as linking to the badge class we created (which in turn links to the issuer JSON).

As with the JSON files we already created, a badge assertion can include various data items - see the assertion specification for details. You can use the following sample structure, which includes all of the required fields:

{
  "uid": "a1b2c3d4e5",
  "recipient": {
    "type": "email",
    "identity": "[email protected]",
    "hashed": false
  },
  "issuedOn":  1388534400,
  "badge": "http://yoursite.com/rookie-badge-class.json",
  "verify": {
    "type": "hosted",
    "url": "http://yoursite.com/rookie-badge-award.json"
  }
}

Notes:

The uid should be unique within the issuing organization.
The recipient object outlines the earner who is being awarded the badge - alter this to the email address you use for your Mozilla Backpack. You can hash the email address for additional security, but in this case we will keep things simple.
The issuedOn field is a timestamp.
The badge field should match the location you uploaded your badge class to so alter it now.
The verify object indicates the type of badge assertion, which can be hosted or signed - in this case it is hosted and the value of the url field should match the location you upload the assertion file to so alter it now and save the file with the same name (rookie-badge-award.json in the example).

In a real-world badge issuing application, you would likely be generating these data items programmatically.

Upload your assertion file to your server - to the location you listed in the verify.url field.

At this stage you have actually awarded the badge to yourself! Issuing a badge essentially involves hosting a badge assertion for the badge and earner, which you have done. Note that you could award the "Rookie Badge Issuer" to someone else by creating another assertion file with their email address and a new uid.

In order to share the badge, you would typically want to push it to a backpack. We will do this by pushing to the Mozilla Backpack.

Step 3: Bake the Badge

All you need to do to issue a badge is host the three JSON files and the badge image, which is sufficient for many systems (for example if you use the Issuer API to push to earners' Backpacks. However, you can also bake the assertion data into the badge image, which will make it more portable for the earner (in this case you). Let's do that so that we can import the badge into your Mozilla Backpack.

Note that if you use the Issuer API to push to the Mozilla Backpack you do not need to bake your badges - the API will bake them for you.

Verify the Assertion

Before we attempt to bake the badge, let's first validate the badge assertion in case there are any errors in it. Visit the validator and paste in the URL of your badge assertion (should be the same as your assertion verify.url field). Check your assertion for validity - if the validator returns any errors it will provide details, so you can take steps to fix them.

Valid Assertion

You can also use the node.js validator in your application code: https://github.com/mozilla/openbadges-validator/

Visit the Bakery

Once you are happy that your badge assertion is valid, you can go ahead and bake the data into the image file. You can do this in the browser at: http://bakery.openbadges.org/ - simply paste your assertion URL and click Bake, the service will write your baked badge into the page, where you can download it - save your baked badge image onto your computer.

Baked Badge

You can use the Mozilla Backpack baking service via the command line or your application code, see Badge Baking.

Step 4: Import the Badge to the Mozilla Backpack

The baked badge image you downloaded has the assertion data embedded into it. Open Badges software will be able to extract that data from the image file. Let's test it out by importing the new baked badge into your Mozilla Backpack. Log in at http://backpack.openbadges.org and click Upload. Browse to the file you downloaded from the bakery service and click Upload.

Import Badge

Your new badge should appear in your Backpack!

Imported Badge

Next Steps

In this tutorial we have created a new badge, issued it, baked it and imported it into the Mozilla Backpack. Although this is a simplistic example, whatever your aims are as an issuer, you should now have gained enough of an understanding to get started on your issuing implementation. You will typically be able to use one issuer organization JSON file for all of your badges, with a badge class file for each badge you plan on awarding (one badge class can potentially be awarded to multiple earners), and a badge assertion for each award you make to your earners.

See the Badge Lab Tutorial for a more detailed guide to creating a badge assertion.

See the following links for next steps:

Help

For support working with Open Badges, use any of the following channels:

Post general questions in our Community Google Group and post technical questions in our Dev Google Group.
Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel.
Email questions directly to [email protected] and a member of the team will follow-up.
Follow or tweet the Open Badges team @OpenBadges.
Get involved or submit issues via the GitHub repos - feedback is always appreciated!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Issuers: Give Yourself a Badge

Contents