Openbadges.me allows you to issue badges using a powerful set of Application program interfaces (APIs). These APIs support the direct issuing of a specific badge to a specific recipient or the automatic event-driven rules-based issuing of badges.
Calls to the API services can easily be integrated into organisational application software to trigger the awarding and issuing of openbadges.me badges.
Getting Started
Before you can start using the APIs you must set-up a developer key and have a security authentication token. These will ensure your data is protected and secure within Openbadges.me.
To set these up just go to the API keys section within System settings of Openbadges.me account.
All API service calls are called from https://events.openbadges.me
A developer guide to using the API is available on the following link:
https://events.openbadges.me/swagger/index.html?url=/swagger/v1/swagger.json
Rules-based badge issuing API
Badges can be issued from Openbadges.me in the following ways:
- From the Openbadges.me site, manually or via imported CSV file.
- Using our APIs to integrate badge issuing into application software.
- Automatically, using openbadges.me rules-based issuing logic.
Introduction
Openbadges.me uses the Events Service and its Events API to provide rules-based badge issuing functionality to its users.
The premise is very simple:
- An organisation records user activities and events into an Events database. They can define their own custom events and add them into the Events database from their own application software using the Events API service.
- An organisation defines rules to automatically issue badges.
- A rules processer applies these rules to the events recorded in the database.
- If the event data satisfies the rule, the rules processor generates an outcome, which for openbadges.me is to issue a badge to a recipient.
- Using the Events API, the organisation can read detail about the rules they have, the user events they have recorded and the badges they have issued
In summary: “The Events Service allows an organisation to record events into a database, define and apply custom rules to those events, that in turn generate outcomes and trigger actions, such as the issuing of badges.”
Setting up rules
Event rules are defined by organisations and applied against the events entries an organisation makes for its users. The rules generate outcomes based upon the completion and satisfaction of a rule. For openbadges.me, the outcome is the issuing of a badge, or badges, to recipients.
Event rules are created and managed within the Openbadges.me space.
Within the Systems setting area of openadges.me, there is an ‘Issuing rules’ space to create the badge issuing rules for your organisation. The outcome for a completed rule within openbadges.me is the issuing of a badge.
Rules can be very simple: If this happens or this condition is met, then issue this badge.
Simple rules can be combined into more complex business logic badge issuing rules. If this happens, and something else happens a set number of times, then issue this badge.
The rules act upon the data that is registered on the events database. Data is placed into the database using the events API service to add event entries. Organisations define these events and record when they happen. The rules the organisation defines interprets their event entries, and if they are met, an outcome is generated. For openbadges.me, the outcome is the issuing of a badge, or badges, to a recipient.
Rules can be set up to issue badges based upon events registered into the database. In the above example, the CPD badge will be issued to a recipient when they have events, with an activity code of ‘CPD20’, where the combined int1 total is greater than 20. Each time a user completes a piece of CPD, the organisation may record this on the events database. They would create an activity event with an activity code of ‘CPD20’ and set the int1 field to the number of hours the use has completed. The rules processor totals up all the events entries for the user, and when the total is greater than 20, it will issue the associated badge.
For more information about openbadges.me single and combination rules and how they can be used to issue badges based upon a single or collection of activities, see the Openbadges.me help and guidance for ‘Issuing rules’.
Creating events
Event entries can be used to simply record activities and events a person has completed, achieved or participated in. Simply put, they can be used to record any event or activity associated with an individual.
To distinguish the different events being records, each event entry has its ‘ActivityId’ set to a custom activity event code. The organisation defines their own event codes. For example, ‘Timesheet’, ‘Conference2018’, ‘CourseAttendence’ or ‘CPDHours’.
To support badge awards and issuing, an organisation can define issuing rules within their Openbadges.me space that are applied to the event entries they record. This rule intelligence will automatically issue badges to recipients once the conditions of the rules have been met.
Creating a single event
You create an event entry for a user by calling the ‘/api/ActivityEvents’ Events API service endpoint: https//events.openbadges.me/api/ActivityEvents
To create an event entry, you will need to pass the following fields to the API, some of which are mandatory and some optional:
ActivityId: The activity code
ActivityTime: The date and time of the event
UserId: Unique recipient id, this can be an email or reference number
Email: The email address of the recipient
FirstName: The first name of the recipient
LastName: The surname name of the recipient
Int1: Optional data field (numeric)
Int2: Optional data field (numeric)
Date1: Optional data field (date)
Text1: Optional data field (text)
Text2: Optional data field (text)
Mandatory fields are: ActivityId, ActivityTime, UserId, Email, FirstName and LastName.
Additional data about the event can be included in the API call and used as part of the rules processing against the activity event. The additional data fields include: two numeric fields, two text fields and one date field. These fields are optional. Your organisation may have rules that use these additional fields to determine an outcome or result. The Int1, Int2, Date1, Text1 and Text2 fields are informational fields used to assist and inform the rules processor when applying event rules.
For example, as an organisation you may want to record and reward (by awarding a badge) community and voluntary work your members undertake. Alice recently spent three hours helping a local park regeneration scheme. This detail could be captured within an activity event entry JSON data object in the following way:
The Int1, Date1 and Text1 fields are utilised to capture additional detail about the ‘CommunityWork’ activity Alice completed.
The organisation could have a badge issuing rule defined within openbadges.me that totals up the number of hours a person has recorded against the ‘CommunityWork’ activity event and awards any individual a ‘Community Achievement’ badge when they reach ten hours.
In the case of Alice, she could have another ‘CommunityWork’ activity event entry added later that week for 8 hours supervision at a community street event. Her total ‘CommunityWork’ hours now exceed 10, so she will be awarded the badge by the events rules processor.
Creating multiple events
Using the Events API, with one service call, an event entry can be created for multiple people, or a single person could have multiple differing event activity entries created for them, or a collection of different people could have entries created for them for multiple and diverse events.
To use this bulk event creation service, you call the API ‘/api/ActivityEvents/bulk’ service endpoint: https://events.openbadges.me/api/ActivityEvents/bulk
In the example JSON data block below, the organisation is creating event entries for Alice (community work), Mahmooda (timesheets) and Ami (Numeracy exam result):
Reporting API
Using the Events API reporting services, you can:
- Get details on all your organisations rules
- Get a list of completions for a single rule
- Get the recipients of all awarded badges
- Get the recipients of a single badge
Get all your rules
You can get a listing of all your organisations events rules by calling the Events API ‘/api/rule’ service endpoint:
https://events.openbadges.me/api/rule
For this Events API service, you do not pass any data into it. The developer key and token you use as part of the service call is enough to identify your organisation and all its defined rules.
Example returned JSON data object:
Get a list of completions for a single rule
You can get a listing of all the times a single rule has been competed (satisfied/met) by calling the Events API ‘/api/rule/{id}/completions’ service endpoint:
The service requires that you substitute the ‘{id}’ string with the id of the rule you want to enquire about. For example, the rule for ‘Con18’ has an id of 3423456. The service call for this rule should look like this:
https://events.openbadges.me/api/rule/3423456/completions
The Events API call will return a collection of JSON objects that show when the rule was completed and user the rule was completed for.
Example returned JSON data object:
Get recipients for all badges
If your organisation has been issuing badges using the Events API, you can get a listing of all the awarded badges, for a specified date range, by calling the Events API ‘/api/ActivityEvents/entries’ service endpoint:
https://events.openbadges.me/api/ActivityEvents/entries
To call this service you need to provide a ‘From’ and ‘To’ date to the service call.
Example returned JSON data object:
The ‘ActivityId’ field is the badge identifier. The “UserId” field contains who the badge was issued to. The ‘CreatedOn’ field holds the date the badge was issued.
Get recipients for a single badge
There is another service endpoint that lets you get a listing of all the badge recipients for a single badge. The Events API service endpoint is ‘api/{id}/entries’.
For example, to get a listing of all the recipients of the Numeracy Essentials Part 1 badge, the Events API service endpoint would look like this:
https://events.openbadges.me/api/OB-60ff00b6-aca0-4860-aa1e-3112251739bf/entries
Example returned JSON data object: