4.8. Enabling Badging#

This topic describes how to enable and configure badging in your instance of Open edX.

Note

Before proceeding, make sure you have read Guidelines for Updating the Open edX Platform.

4.8.1. Overview#

Badges provide a way for learners to share their course achievements. For courses that have course completion badges enabled, learners receive a badge at the same time that they receive a course certificate, and have the option of sharing their badges to a badging site such as Mozilla Backpack. For more information, see Course Completion Badges.

In addition to badges that are awarded for completing single courses, you can also issue badges for various cross-course events. For example, you can create badges to be awarded when any of the following events occur.

  • A learner enrolls in a certain number of courses.

  • A learner receives a completion certificate for a certain number of courses.

  • A learner receives a completion certificate for every course in a specified list of courses.

For more information, see Course Event Badges.

By default, Open edX supports Open Badges (http://openbadges.org/), an open standard originally developed by the Mozilla Foundation. Open Badges provides a badge generator called Badgr Server, which is used by default in Open edX.

You can use a badge generator other than Badgr Server. For information, see Specify a Badge Generator Other Than Badgr Server.

For information about creating custom badges, see Create New Badges for Your Open edX Instance.

4.8.2. Prerequisites#

Setting up the badges feature on your instance of Open edX involves performing the set up and configuration tasks that are described in the topics below.

4.8.2.1. Make Sure Certificates Are Enabled#

Badge generation depends on certificate generation. Badges for course completion are automatically generated when a course certificate is generated for a learner. Make sure certificates are enabled on your Open edX instance. For information, see Enabling Course Certificates.

4.8.2.2. Specify a Badge Generator#

By default, Open edX uses Badgr Server as the badge generator. If you do not use Badgr Server, you can configure a different badge generator.

4.8.2.2.1. Install Badgr Server#

Badgr Server provides an API for issuing Open Badges. Follow the instructions at concentricsky/badgr-server to install and run Badgr Server.

Important

You must install Badgr Server at a publicly accessible IP address, to allow the Open edX LMS and services such as Mozilla Backpack to contact Badgr Server.

If you do not use Badgr Server, you can configure a different badge generator. See Specify a Badge Generator Other Than Badgr Server.

4.8.2.2.2. Specify a Badge Issuer for Your Organization#

Note

This step is required only if you use Badgr Server for your badge generator.

If you are using Badgr Server, log in to your installation of Badgr Server and add an issuer of Open Badges for your organization.

For more information about issuing Open Badges, see the Issuing Badges topic on the Mozilla wiki.

4.8.2.2.3. Specify a Badge Generator Other Than Badgr Server#

By default, Open edX uses Badgr Server as the badge generator. To use Badgr Server, see Install Badgr Server and Specify a Badge Issuer for Your Organization.

To specify a different badge generator, follow these steps.

Note

Because the services and software used for badge generation can differ significantly, the steps described in this topic are intended as guidelines and not as exact procedures.

  1. Add the BadgingBackend object as a subclass to lms/djangoapps/badges/backends/base.py.

    A BadgingBackend object must include the award function

    award(badge_class, user_id, evidence_url=None)

    where

    • badge_class is the definition of the badge class for which the BadgeAssertion is created,

    • user_id is an ID for the user that the BadgeAssertion is to be created for, and

    • evidence_url is an optional URL for the location where the badge evidence can be viewed.

    The award function is responsible for the server awarding a badge to a learner. It is also responsible for all checks leading up to the awarding of the badge, including making sure the badge specification does not already exist on the target before creating a new badge specification.

    The award function should either return a BadgeAssertion object or raise an exception if the award cannot be given. By default, a base badge generation object called BadgeBackend exists, and contains a dummy version of the award function.

    class BadgeBackend(object):
        """
        Defines the interface for badge generators.
        """
        __metaclass__ = ABCMeta
    
        @abstractmethod
        def award(self, badge_class, user, evidence_url=None):
        """
        Create a badge assertion for the user using this badge generator.
        """
    
  2. In the BadgeAssertion object that is generated by the award function, make sure the backend value is the name of the BadgingBackend subclass.

    class BadgeAssertion(models.Model):
        """
        Tracks badges on our side of the badge baking transaction
        """
        user = models.ForeignKey(User)
        badge_class = models.ForeignKey(BadgeClass)
        data = JSONField()
        backend = models.CharField(max_length=50)
        image_url = models.URLField()
        assertion_url = models.URLField(
    
  3. In the lms.yml and studio.yml files, set the value of BADGING_BACKEND as a dot-separated python path specification to the object that you use to create and assign badges.

  4. When you have finished modifying your configuration files for the badge generator, restart the Studio and Learning Management System processes so that the updated environment configurations are loaded.

4.8.3. Enable Badges in Studio and the Learning Management System#

To enable badges, you modify the lms.yml and studio.yml files, which are located one level above the edx-platform directory.

  1. In the lms.yml and studio.yml files, in the FEATURES section, set the value of ENABLE_OPENBADGES to True.

    # Enable OpenBadge support.
    'ENABLE_OPENBADGES': True,
    
  2. In lms.yml, set the values for the following parameters.

    • BADGR_USERNAME: The username connected to your Issuer App in Badgr.org or in your installation of Badgr Server. This will be used to create OAuth2 tokens.

    • BADGR_PASSWORD: The password connected to your Issuer App in Badgr.org or in your installation of Badgr Server. This will be used to create OAuth2 tokens.

    • BADGR_TOKENS_CACHE_KEY: The cache key for Badgr API tokens. Once created, the tokens will be stored in cache and can be retrieved using this key.

    • BADGR_BASE_URL: A string containing the base URL for Badgr Server. If you are running your own installation, the Badgr Server must be installed at a publicly accessible IP address. If you have registered an Issuer App with Badgr.org, this will be provided for you.

    • BADGR_ISSUER_SLUG: A string that is the slug for the Badgr issuer. The slug can be obtained from the URL of the Badgr Server page that displays the issuer. For example, in the URL http://exampleserver.com/issuer/test-issuer, the issuer slug is test-issuer.

    • BADGR_ENABLE_NOTIFICATIONS: Optional boolean setting for enabling email notifications. When set to “True”, learners will be notified by email when they earn a badge. Default is “False”.

      ############## Badgr OpenBadges generation ##############
      
      BADGR_USERNAME = "example@example.com"
      BADGR_PASSWORD = "password"
      BADGR_TOKENS_CACHE_KEY = "secret-test-cache-key"
      # Do not add the trailing slash here.
      BADGR_BASE_URL = "http://localhost:8005"
      BADGR_ISSUER_SLUG = "test-issuer"
      BADGR_ENABLE_NOTIFICATIONS = True
      
  3. Save the lms.yml and studio.yml files.

  4. Run database migrations.

  5. Restart the Studio and Learning Management System processes so that the updated environment configurations are loaded.

4.8.4. Enable Badges Within Each Course#

The ability to issue course completion badges is enabled by default for all courses, but can be turned off or on again using an advanced setting in Studio. For information, see Enable or Disable Badges for Your Course in Building and Running an Open edX Course.

Note

The course-level setting to enable badges does not affect badges that are issued for completing or enrolling in multiple courses.

4.8.5. Configure Badges for Your Open edX Instance#

You can configure several types of badges to issue to learners in your Open edX instance.

In addition, you can use the badging framework to create custom badges. For information, see Creating New Badges for Your Open edX Instance.

4.8.5.1. Course Completion Badges#

For courses that have badges enabled, learners receive a course completion badge at the same time as they receive a course certificate, and have the option of sharing their badges to a badging site such as Mozilla Backpack.

You can configure a different course completion badge for each course mode that you support (for example, “professional”, “advanced”, or “basic”). You can also specify a different badge image for each of the badges that you configure. For information, see Enable Badges Within Each Course and Create Course Completion Badges for Your Open edX Instance.

4.8.5.2. Course Event Badges#

Course event badges are awarded across courses, and can be awarded when any of the following events occur.

  • A learner enrolls in a certain number of courses.

  • A learner receives a completion certificate for a certain number of courses.

  • A learner receives a completion certificate for every course in a specified list of courses.

You can customize these course event badges with your parameters and badge images. For information, see Create Course Event Badges for Your Open edX Instance.

4.8.6. Create Course Completion Badges for Your Open edX Instance#

Important

Default images are supplied in Open edX for course completion badges. Be sure to replace these default badge images with your organization’s own badge images before any badges are issued. When the first badge is issued for a given course, badge images are uploaded to Badgr Server. All badges issued in future for this course will use this uploaded original badge image, even if you subsequently change badge images in the Django Administration badge image configuration.

  1. Access the Django Administration website for your instance of Open edX. To do this, go to https://<host name of your Open edX instance>/admin. For example, this might be https://YourOrganization.org/admin.

  2. Select Site Administration > Badges > Course complete image configurations, and then define a course complete image configuration for each course mode on your platform for which you want to issue badges upon course completion. Examples of course modes are “professional” or “advanced” or “basic”.

  3. For each course complete badge image configuration, set these parameters.

    • Mode: The course mode for which the badge image should be used.

    • Icon: The badge image to use for the specified course mode.

    Important

    Be sure to replace the default badge images with your organization’s own badge images before any badges are issued.

  4. Optionally, you can define a badge image that will be used as the default badge image for any course modes that do not have an explicitly specified badge image.

    To do so, in the course complete image configuration that references the image you want to use as a default, select the Default checkbox. After you save the configuration, this badge image is used for any course completion badge configurations that do not have a badge image explicitly specified.

    Note

    You can specify only one default badge image.

  5. Save each configuration parameter and exit the Django Administration website.

4.8.7. Create Course Event Badges for Your Open edX Instance#

Open edX provides several customizable course event badges that can be awarded when any of the following events occur.

  • A learner enrolls in a certain number of courses.

  • A learner receives a completion certificate for a certain number of courses.

  • A learner receives a completion certificate for every course in a specified list of courses.

Before course event badges can be awarded, you must customize them with your parameters and badge images. To customize any of the course event badges, follow these steps.

Note

You can also use the badging framework to create custom badges. For information, see Creating New Badges for Your Open edX Instance.

  1. Access the Django Administration website for your instance of Open edX. To do this, go to https://<host name of your Open edX instance>/admin. For example, this might be https://YourOrganization.org/admin

  2. Select Site Administration > Badges > Badge Classes.

  3. Add a badge class for each course event for which you want to issue badges. Examples of course events might be enrolling in five courses, or completing three required courses.

  4. For each badge class, set the following parameters.

    • Slug: A unique identifier that you choose to identify the badge class. This identifier can contain only numbers, lowercase letters, underscores, or hyphens. The slug, combined with the Issuing Component value, uniquely identifies a badge.

    • Issuing Component: Identifies the part of the platform that is issuing the badge. This identifier can contain only numbers, lowercase letters,underscores, or hyphens. For the three customizable course event badges that are included in the Open edX platform, the value for Issuing Component must be openedx__course (with two underscores). For course completion badges that are included in the Open edX platform, the issuing component value should be empty.

      For new badge types that you create, specify an Issuing Component value that identifies the software component responsible for issuing the badge. For example, if badges are issued by the course management component, you might define Issuing Component as platform__course; if badges are issued based on activity in course discussions, you might define Issuing Component as platform__discussions.

    • Display name: The human readable badge name that is used when badges are shown to learners, for example, in the Accomplishments view of learners’ profiles.

    • Course ID: This value should be blank for course event type badges, as they are not associated with a single course.

    • Description: A description of this badge.

    • Criteria: A description of the criteria for awarding this badge.

    • Mode: The course mode for the course associated with this badge, if applicable.

    • Image: The badge image to use for this badge. Badge images should be square .png files less than 250KB in size.

    An example of a badge class configuration might have the following values.

    • slug: enrolled_three

    • issuing_component: openedx__course

    • display_name: Enroll in Three Courses

    • description: Enrolled in three courses

    • criteria: A learner must enroll in three courses to receive this badge

    • image: triple_enrollment_badge_image.png

  5. When you have finished defining the badge class, select Save.

  6. Next, you create a new course event badge configuration that defines all of the course event badges that you want to issue. Select Site Administration > Badges > Course event badges configurations > Add course event badges configuration.

    Important

    You can create more than one course event badge configuration, but you can only mark one configuration as Enabled. Only the most recently activated course event badge configuration is used.

  7. Within the new course event badge configuration, set the following parameters.

    • Courses completed: Define badges to be awarded for completing a certain number of courses, or completion of specific courses. Define one badge per line. On each line, enter the number of courses that must be completed, followed by a comma and then the slug of the badge class to associate with this badge.

      For example, to configure two badges, one that is awarded when a learner completes 3 courses, and another that is awarded when a learner completes 8 courses, you add two lines to the Courses completed field.

      3,completed_three 8,completed_eight

      where completed_three and completed_eight are badge slugs that you previously defined in badge classes.

    • Courses enrolled: Define badges to be awarded for enrolling in a certain number of courses, or enrolling in specific courses. Define one badge per line. On each line, enter the number of courses that must be enrolled in, followed by a comma and then the slug of the badge class to associate with this badge.

      For example, to configure a badge that is awarded when a learner enrolls in 5 courses, you add this definition.

      5,enrolled_five

      where enrolled_five is a badge slug that you previously defined in a badge class.

    • Course groups: Define badges to be awarded for completing a list of specific courses. Define one badge per line. On each line, enter the slug of the badge class, a comma, then the list of course keys.

      For example, to configure a badge that is awarded when a learner completes the 3 prerequisite courses in a series, you add this definition.

      prereq_computerscience_badge_slug,course1_identifier,course2_identifier,course_3_identifier

      where prereq_computerscience_badge_slug is a badge slug that you previously defined in a badge class, and course1_identifier, course2_identifier, and course3_identifier are the Course IDs for the three courses that must be completed for this badge.

  8. When you have finished defining badges in the configuration, select Save.

  9. To activate this configuration, select Enabled at the top of the configuration page.

Important

You can create more than one course event badge configuration, but you can only mark one configuration as Enabled. Only the most recently activated course event badge configuration is used.

4.8.8. Creating New Badges for Your Open edX Instance#

In addition to using the default customizable badges that are provided with the Open edX platform, you can design new badges that are generated when a particular XBlock-related or course-related action occurs.

Before you create new badges, you should understand the following concepts.

  • Badge Class - The specification of the badge that is to be awarded. Parameters for badge classes are described in Step 4 of the Create Course Event Badges for Your Open edX Instance topic.

  • Slug - This field in the BadgeClass model uniquely identifies the badge class.

  • Issuing Component - This field in the BadgeClass model identifies the part of the software that is issuing the badge. For example, the name of the XBlock where the occurrence of some event triggers the awarding of a badge.

    For the customizable course event badges that are included with the Open edX platform, the value for issuing_component must be openedx__course (with two underscores). For course completion badges that are included in the Open edX platform, the issuing component value should be empty.

    For new badge types that you create, specify an Issuing Component value that identifies the software component responsible for issuing the badge. For example, if badges are issued by the course management component, you might define Issuing Component as platform__course; if badges are issued based on activity in course discussions, you might define Issuing Component as platform__discussions.

  • The combination of badge slug, issuing component, and optionally, course ID uniquely identifies an awarded badge.

  • Award method - The award function on the Badge Class instantiates the badge generator and calls the badge generator’s award function, which is responsible for awarding a badge to a learner, as well as for performing all checks leading up to the awarding of the badge. On the Badge Class, the award function either returns a BadgeAssertion object or raises an exception if the award cannot be given.

  • Badge Assertion - A specific generated instance of a badge that a learner has been awarded. Badge assertions contain data about the learner who earned the badge, and the date and time that the badge was awarded. Multiple badge assertions can be awarded for a specific BadgeClass, including to the same learner. You can get all assertions for a particular learner for a specific BadgeClass using the get_for_user method, using user as an argument.

For instructions for creating new badges, see Create New Badges for Your Open edX Instance.

4.8.8.1. Create New Badges for Your Open edX Instance#

To create new badges for use within your Open edX platform, follow these steps.

  1. Create a Badge Class specifying the details of the badge you want to award. You can do this using the get_badge_class method from the badges app, or create a badge class in Django Admin. For Django Admin instructions, see steps 1-5 in Create Course Event Badges for Your Open edX Instance.

    BadgeClass.get_badge_class creates the requested badge class if one does not already exist that has the same combination of slug and issuing_component. Badge classes are uniquely identified by a combination of their slug and issuing_component fields, and optionally also the course_id field if a badge is associated with an individual course.

    If a badge class already exists with the same combination of slug and issuing_component that is in the request, the existing badge is returned. No new badge class is created, and no changes are made to the values of the existing badge class.

  2. In the XBlock or component where badges are to be awarded based on some event occurring, add declarations to the badging and user services.

    The following example illustrates creating a badge class and awarding it from an XBlock.

    from xblock import XBlock
    from xblock.fragment import Fragment
    import pkg_resources
    
    @XBlock.wants('badging')
    @XBlock.wants('user')
    class AwardBlock(XBlock):
    """
    A Block that awards a badge when a learner visits it.
    """
    def award_badge(self, user_service, badge_service):
         user = user_service.get_current_user()
         badge_class = badge_service.get_badge_class(
             slug='general_award', issuing_component='my_org__award_block',
             description="A shiny badge, given to anyone who finds it!",
             criteria="Visit a page with an award block.",
             # This attribute not available in all runtimes,
             # but if we have both of these services, it's a safe bet we're in the LMS.
             course_id=self.runtime.course_id,
             # The path to this file should be somewhere relative to your XBlock's package.
             image_file_handle=pkg_resources.get_resource_stream(__name__, 'badge_images/award.png')
             # Badge image should be a square PNG file less than 250KB in size.
         )
         # Award the badge.
         if not badge_class.get_for_user(user):
             badge_class.award(user)
    
    def student_view(self, context=None):
        """
        Displayed to the learner when they visit.
        """
        # If the user and badge services are not present, we cannot award the badge.
        # If they are, we are ready to award one.
        user_service = self.runtime.service(self, 'user')
        badge_service = self.runtime.service(self, 'badging')
        if user_service and badge_service:
            self.award_badge(user_service, badge_service)
        return Fragment(u"<div><p>You just earned a badge!</p></div>")
    

4.8.8.2. Get Information about Badge Assertions#

Depending on the type of badge you have created and are awarding, you might want to limit the number of times that a learner can receive a badge. You can find whether a specific learner has already received a particular badge in either of the following ways.

  • Use badge_class.assertions_for_user with user as an argument, to return a list of all assertions that the specified user has received for the badge class.

  • Use the Badges API GET method to return a list of assertions for a particular username. For example, use GET /api/badges/v1/assertions/user/{username}/.

For more information and additional parameters, see Supported Badges API Endpoint.

4.8.8.3. Supported Badges API Endpoint#

The Badges API supports the endpoint GET /api/badges/v1/assertions/user/{username}/. You can use the following query parameters with this endpoint.

Note

All of these query parameters are optional.

Parameters

Description

slug

If used, filters by the badge class identified by this slug. Unless issuing component is also specified, assumes a null/empty issuing component.

issuing component

If used, also requires slug to be specified. Filters by the badge class.

courseid

If used, returns only badge assertions that were awarded as part of the specific course.

For example, to get a list of badge assertions issued for a badge with an issuing_component value of openedx__course and a slug value of enroll_in_three_courses, the query would be

{openedx domain}/api/badges/v1/assertions/user/?issuing_component=openedx__course&slug=enroll_in_three_courses

where <openedx_instance> is the site URL for your Open edX instance.

Possible query results are as follows.

  • 200 on success, with a list of badge assertions.

  • 403 if a user who does not have permission to masquerade as another user specifies a username other than their own.

  • 404 if the specified user, badge class, or course does not exist.