Onboarding the non-technical OBI implementer

Start using the Open Badges Infrastructure (OBI) today. This step-by-step guide has been built to get you using badges as quickly and easily as you can while keeping the technology know-how to a minimum. This guide has been built for people to move through step-by-step in order. You may feel you can move quickly through a step, it is suggested you do not skip any steps.

Step 0: background readings

1. A laundry list of sites and specific pages to start your journey towards understanding badges
2. This blog post details what I've learned so far with open badges. It also serves as a good list of resources.
3. The p2pu challenge titled open badges 101 is a great way to jump into the community.

related screencasts

• Readings about the Open Badges Infrastructure - http://youtu.be/3-FkzP18_lQ
• FAQs and Technical resources available for Open Badges - http://youtu.be/fzARrbOoP-8
• First look at the JSON message structure for issuing open badges - http://youtu.be/jqjuqmyW06E
• A first look at the P2Pu Open Badges 101 challenges - http://youtu.be/LcIQw-NkOFE

Step 1: Go out and claim yourself a badge

Go get your first badge. This is important for the claiming of your first badge exposes you to an issuer and your backpack and initiates the setup of the accounts required to be a badge holder.

An easy first step

There are a lot of sites where you could claim or earn a badge, all of these give a different perspective of how badges can be used... it is good to understand badges from many views and this list is just a beginning.

• openbadges.org - easily grab your first badge
• khan academy - start easy and achieve proficiency
• foursquare - grab a coffee, earn a badge
• p2pu - find an area of interest and challenge yourself to earn a badge, or jump into open badges 101

Once you've earned and claimed a few badges, think deeply of the three main infrastructures of; issuer, earner and displayer. Think about the role of these three and where the backpack would fit within these three.

Note: not all badge issuing platforms work with the open badges. This is part of the open badges initiative, to create a standard approach and messaging protocol for the issuing and display of badges.

related screencasts

• Digital badges - claiming your first badge - http://youtu.be/cp0v8LKIeHo
• P2PU - a first look at the P2PU Open Badges 101 challenges - http://youtu.be/LcIQw-NkOFE

Step 2: Technical Prerequisites

You can't avoid it, you are going to have to start thinking about technology. If you venturing into the open badges realm at this early stage you need to get to know some of the underlying technology. Then of course you could wait until the technology and related services are more mature. To be successful with implementing open badges you are going to need a very basic understanding of JavaScript, an idea of the web technology stack and the basics of server infrastructure. You don't require a deep understanding, but a basic understanding of these three areas will help greatly in supporting your learning.

A beginner understanding of JavaScript

To issue a badge a basic understanding of JavaScript is required. A reference needs to be set to the Mozilla JavaScript that "pushes" the badges JSON file toward the earners backpack.

Basic structure of JavaScript

To get started with issuing a badge from a web page it is strongly recommended that you brush up on your JavaScript knowledge. There are good number of online tutorials and books you can access, a simple Google search on "JavaScript Beginner" can provide a good list of resources.

Inserting a JavaScript include

One of your focuses as you learn JavaScript is going to be how to make a reference to an existing JavaScript library. Your going to require enough learning to understand this line of code and how it sets a reference to the library you require.

<script src="http://beta.openbadges.org/issuer.js"></script>

Calling a JavaScript module

Combined with setting a reference to the correct JavaScript library you will also have to know how to make a call to a function within the library. Review these lines of code to provide a sample of what you will need to know. Don't worry, I will be diving a little deeper in how these JavaScript calls work. These should provide you enough to focus this first round of learning.

Joseph Badjernor
<a href="javascript:OpenBadges.issue(['http://badges.bit.bc.ca/mwa/mwa-pjrch01.json'], 
function(errors, successes){  });">, claim your badge.</a></p>

Or some other server side programming language or application

Making use of the javascript libraries from within a web page is the manual approach to issuing badges. If you are going to want to issue badges from within a learning management system (LMS), another software application or custom developed software you are going to have to develop an understanding of that particular environment.

related screencasts

• Open Badges Technical Prerequisites - JavaScript - http://youtu.be/jzJjimCZz6g

The technology stack

Each of the three roles of issuer, earner and displayer have different technology requirements. It is expected that most people reading this will fall within the issuer role, but others will do well by continuing to read this wiki page.

For the issuer:

A web server with;

1. a stable URL that will remain consistent until all the badges issued have expired and are no longer displayed
2. the ability to host a web site, web pages, javascript and related services
3. the ability to serve up JSON files (this can occur in two ways; 3.1. being the preferred approach)
   1. web programming language and a database and required software to generate the JSON message to issue a badge for each earner who has completed the criteria and provided the appropriate evidence.
   2. hand edited JSON files for each earner who has completed the criteria and provided the appropriate evidence.

For the earner:

1. A blog, website or online portfolio to display your evidence.
2. A blog with the correct widgets or ability to embed javascript to display badges. This blog isn't so much a place to display the badges but to write and reflect about your learnings.
3. Personal accounts with one or more social media sites that allow the display of badges
4. Ability to access and manage your badge backpack

For the displayer:

1. The ability to serve up widgets or javascript
2. Access the earners backpack via the Displayer API.
3. Web hosting, programming language and database to store desired earner badges information

related screencasts

• Open Badges Technical Prerequisites - Technology Stack - http://youtu.be/X3Dc-Vofroc

Server Infrastructure

Each role requires resources on the internet, these vary greatly due to the work that is required. The diagram below shows the three roles and their interactions. The issuer on the left requires the most server infrastructure. The earner backpack requires infrastructure resources which will increase if you are planning on hosting a backpack (this is currently not recommended due to the lack of backpack federation features). It is currently recommended that you use the openbadges backpack hosted at http://beta.openbadges.org. The displayer role requires the least amount of resources as displaying badges requires the least amount of softwar features. This can increase if the displayer provides additional badge display features.

for the issuer:

The issuer requires the most server infrastructure, for it needs to host the badge and earners information. The servers also need the computing resources to issue (push) the badges to the Issuer API and compute and store any local badge management and tracking information. The issuer may also require the ability to inter-operate with other organizational server infrastructure (like a learning management system, event registration, etc).

To get a sense of the resource requirements for the issuer a review of the issuer json and its two main stores of information required to issue a badge are; the earner (or recipient) and the badge.

1. earner (recipient) information
   1. evidence information
2. badge information
   1. png file(s)
   2. criteria information
   3. issuer information

for the earner:

The earner requires the least amount of server infrastructure to support their activities. The earner could successfully earn badges with no server infrastructure of their own. The earner will require web locations to be able to host their evidence; this hosting could be in blogs, wikis, personal web spaces or existing educational infrastructure. If the earner does have their own server infrastructure or web space this could be used to host their evidence.

for the displayer:

From a server infrastructure perspective the displayer will need to have the ability to host HTML, JavaScript or an application widget that can make calls to the displayer API. This can be as simple as a hosted web page or a blog that can have the HTML of JavaScript embedded. If the displayer is providing the more robust features of a widget they will require the features for hosting the widget, making the displayer API calls, and any other programming or database infrastructure to support their widgets features.

related screencasts

• Open Badges Technical Prerequisites - Server Infrastructure - http://youtu.be/j-fOUEmHGnM

Step 3: Creating your issuer site

This step is going to be the first that requires some actual coding and system admin type tasks. During this step-by-step guide we are mostly covering what you need to know to issue a badge manually. More automated approaches that include integrating with existing LMS (Moodle) or application frameworks (Drupal, Wordpress, Django, Etc.) will come in a subsequent step-by-step guide.

Basic Requirements

The resources here are going to keep things as simple as possible. As with many things technical they can quickly become much larger topics as technologies are built upon each other and discussing lower levels can easily become a part of the discussion. For the time being we are going to stay at the higher levels and loop around to dive deeper as the Open Badges project gets to its 1.0 release sometime in early 2013.

1. Stability in the URL

Having a stable URL is going to be important for being an issuer. The meta-data within the badge (or json file) needs to refer back to an internet domain name. This is so the badge can be validated and the data within the origin, criteria, and evidence can be viewed and referenced through time.

2. Basic web site with the ability to support the json content type

For manual issue of a badge your web server is going to have to support the application/json content-type. Ihis is done by some administrative tasks with your servers configuration. A Google search of your server name (Apache, IIS, etc.) and the keyword content-type should provide the information regarding your server recognizing this content-type.

   # Save your manual badge issuing as .json files and add this to your httpd.conf
   AddType   application/json   json

Note: setting the content-type can also be done in code. This is currently beyond the scope of this step-by-step guide. To review this 'in code' approach feel free to read the github page discussing assetions; https://github.com/mozilla/openbadges/wiki/Assertions

• create a screencast for editing the httpd.conf file in apache... also show the server restart...

3. Ability to hash the earners email with the salt

There is currently two approaches to manually issuing a badge to the OBI backpack. These have been referenced in a number of blog posts mentioned above and in step 0 of this step-by-step guide.

• One method is to make an http request with the correctly formatted json file as a part of the URL (provide example).

http://beta.openbadges.org/baker?assertion=http://yourhosting.com/u/folder/BillyBlogTestBadge2.json

• the second method is to submit the json file using a javascript call (remember you will need to include the correct javascript library).

<a href="javascript:OpenBadges.issue(['http://badges.bit.bc.ca/mwa/mwa-pjrch01.json'], function(errors, successes)
 {  });">claim your badge.</a>

One of the issues with the plain text nature of json files and massages is that private information can be exposed. One of the features of the OBI is its ability to recognize hashed text to confirm the earner without having to expose their email address in the json file. The following php code snippet hashes the earners email with a salt value using sha256 encryption and echo's (displays) the hashed value to the screen. This is a one way hash, so you can't "unhash" it. To confirm this value you would need the email address of the earner and the salt value and then hash it yourself with sha256. Once the value is hashed you should have no reason to "unhash" the value, the OBI will be able to do this as it is accepting the badge into the earners backpack.

<?php
    echo hash("sha256", "peter@example.com"."mwach01");
?>

Step 4: Issuing a badge

The process of issuing a badge

Assumptions

1. the issuing institution has created a stable web infrastructre to issue badges. In particular, stability in thier domain name and URLs.
2. badges have been designed in correct graphics format [.png, (.svg soon!)]
3. badge, course and criteria URL locations has been indentified, and respective resources are available from these locations
4. processes for assessing badge awarding has been identified / created.
5. earners have successfully completed tasks / demonstrated knowledge as defined by the badge criteria

The process

1. after meeting (or exceeding) the badge criteria, earners either;
   1. request the badge, which triggers thier assessment (automated or otherwise)
   2. earn the badge through automation or other assessment techniques (peer, traditional, etc.) initiated by the issuer
2. notification of successful badge earning is provided to earner via email or other online notification method
3. the earner claims their badge and "moves" badge into their backpack
4. they organize their badges in preparation for display (this organization includes; setting a public-private attribute and moving the badge into a group, if appropriate)

Files, Folders and Domain names

All badges are created by combining a graphics file with metadata. This merge and create is called badge "baking". The graphics file is the image of the badge and the metadata is the information regarding the badge; it's location, the issuing institution, the badges criteria for earning, and the earners identification.
The badge baking occurs when the earner claims thier badge. The issuer creates an instance of the metadata, which is the json describing the badge. The json can come in two forms; an actual text file stored at some internet location or a digital message created by software and "sent" to the open badges infrastructure. There are a number of required attributes for the json file to successfully submit a badge. Three of these attributes refer to file locations. They are;

1. the badge image file location
2. the criteria description location
3. the origin URL of these above resources

It is important to note that the file location of these resources need to be accessible over the internet.

the JSON file or message

The JSON file(s) or message(s) are key to the Open Badges Infrastructure (OBI). It contains the information required for a badge to be issued and displayed.

As a file

Most of the tutorials have focused upon issuing a badge using a text (or json) file. The idea being that the required information is stored in a file stored to disk and referenced when issuing the badge. This means that many files would have to be stored to disk and would, through time, cause significant maintenance overhead.

As a Message

The json could also come as a message exchanged between systems. The idea of an Application Programming Interface (or API) available on the internet allowing two or more websites can exchange information has been available for a number of years. The json message between your local server and the OBI server follows this API approach. Therefore, some effort is require at the partner side of things to integrate with the OBI.
If you are going to issue a badge as a message it would be better to use some of the existing modules or widgets available for issuing a badge. There is a growing list of modules available on the open badges github; https://github.com/mozilla/openbadges/wiki/Open-Badges-related-widgets Building your own system would be considerable work and it would be best to leverage some of this existing work.

JavaScript

All the JavaScript code required to manually issue a badge is described in the previous step. Individual JavaScript links will have to be created for every badge that will be released to a badge earner. The badge earner will 'click' on the line of JavaScript code to claim their badge and move it into their backpack.

Step 5: Earning a badge

the Backpack

Step 6: Managing your badges

https://groups.google.com/d/topic/openbadges/NC_5_2pgiKA/discussion

Step 7: Being a badge displayer

Step 8: Displaying your badges