OBF Connector

An API connector for Open Badge Factory.

This repo contains a specification and a reference implementation for OBF in lib/obf/.

Useage:

const OBFConnector = require('obf-connector');
const connector = new OBFConnector('your_org_id', 'path/to/cerificate', 'path/to/private.key');
connector.getEarnableBadges((err, response) => {
  if (err) throw err;
  console.dir(response);
});

See index.js for more examples.

Design Philosophy

This is an implementation an abstract connector specification. Rather than providing abstract classes from which to inherit, the specification will be outlined below (or maybe in the future at some other place) and the implementation will adhere to it as close as possible. This has the rationale that JavaScript, unlike strongly typed languages like Java, does not impose type checking at compiletime, thus removing the need for something like an interface definition.

The basic idea is that there are multiple Open Badges systems like Open Badge Factory, Credly and Badgr (background systems or target systems). Most of these systems provide similar functionalities through their APIs, like creating Badges, listing Badges of an issuer and applying for badges. A connecting system might want to use some of that functionality, while being loosely coupled to a specific target system.

The Connector gets a command describing a use case to be realized by the background system with the id of the current user and required parameters.The Connector handles the login into the Background system and requests, if necessary, from KO-Badgelor a screen area to let the Background system communicate with the user. The Connector informs KO-Badgelor when the Background system has completed the use case by returning an instance of class ConnectorResponse

Note that most systems still use the 1.1 specification, so that's what we'll use too.

Specification

Following this specification should make it possible for users of an implementation to easily switch to another implementation. For that, we define a common interface below, which is some classes with serveral defined functions or fields. Some functions may be left unimplemented but should throw a ReferenceError when called. This is meant to be a guideline that leaves most specifics to the implementation. It is designed to be broken, but as little as possible, as to minimize switching costs.

Development of the specification is guided by https://userpages.uni-koblenz.de/~dahn/Badgelor/.

Badge

A representation of a badge, possibly with information on how to earn it. Can be an Open Badges Badge: https://openbadgespec.org/history/1.1-specification.html#BadgeClass.

Must have and id field.

User

An user in the connecting system, independent of a role.

Must have and id field.

Filter

A plain JavaScript object. Each present property will be matched against a target collection. Example:

const filter = {
  "issuer": "jake",
  "lecture": "echeladder"
}

Should return elements of a collection whose issuer property equals jake and whose lecture property equals echeladder.

Connector

Provides functions to work with a Open Badges system.

Connector#addCreator(creator: User)

Creates the user creator in the target system.

Connector#applyForBadge(user: User, badge: Badge)

Creates an application from user for badge:

Connector#createBadge(user: User, badge: Badge)

Creates badge with user's account'.

Connector#getBadgesList(user: User, filter: Filter)

Reads the list of available badges that the user is allowed to see. For example, this may exclude unpublished badges. The badges may be earnable. Uses filter to filter the result. Whether the filtering is done in the connector or in the target system is left to the implementation.

Connector#getCreatorsList(filter: Filter)

Returns a filtered list of creator user accounts in the target system. Whether the filtering is done in the connector or in the target system is left to the implementation.

Connector#modifyBadge(user: User, badge: Badge)

Updates the data of badge (identified by its id) with the new data from badge. The action is executed as user, if possible.

Connector#modifyCreator(creator: User)

Updates the data of creator (identified by their id) with the new data from creator.

Connector#pushBadge(user: User, badge: Badge, target: URL)

Facilitates pushing badge, owned by user to the target backpack/passport server.

Connector#reviewApplications(user: User, badge: Badge)

Initiates the process of the user reviewing applications. For example it may open a connection to the background system with the user logged in and the list of applicants for the specific badge open