Merge pull request #366 from edx/carol/doc/SD_Badging_Config

DOC: Certificates and Badging configuration doc for Open edX

en_us/install_operations/source/configuration/enable_badging.rst

@@ -0,0 +1,145 @@
+.. include:: ../links.rst
+
+.. _Enable Badging:
+
+##################
+Enabling Badging
+##################
+
+Badges provide a way for learners to share their course achievements. For
+courses that have badges enabled, learners receive a 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.
+
+Open EdX supports Open Badges, an open standard originally developed by the
+Mozilla Foundation. For more information about Open Badges, see
+http://openbadges.org/.
+
+Enabling the badges feature on your instance of Open edX involves the
+following set up and configuration tasks.
+
+.. Note::  
+  Before proceeding, review :ref:`Guidelines for Updating the edX Platform`.
+
+.. contents::
+   :local:
+
+*****************************************************************
+Make Sure that Certificates are Enabled
+*****************************************************************
+
+Badge generation depends on certificate generation. Badges are automatically
+generated when a certificate is generated for a learner. Make sure
+certificates are enabled on your Open edX instance. For details, see
+:ref:`Enable Certificates`.
+
+
+*****************************************************************
+Install Badgr Server
+*****************************************************************
+
+Badgr Server provides an API for issuing Open Badges. Follow the instructions
+at https://github.com/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.
+
+
+*****************************************************************
+Specify a Badge Issuer for Your Organization
+*****************************************************************
+
+Log in to your installation of Badgr Server and add an issuer of Open Badges
+for your organization.
+
+For information about issuing Open Badges, see https://wiki.mozilla.org/Badges
+/Onboarding-Issuer#Issuing_Badges
+
+
+*****************************************************************
+Enable Badges in Studio and the Learning Management System
+*****************************************************************
+
+#. In the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files, set the
+   value of ``ENABLE_OPENBADGES``  to ``True``.
+
+   .. code-block:: bash
+
+     # Enable OpenBadge support. See the BADGR_* settings later in this file.
+     'ENABLE_OPENBADGES': True,
+
+#. In ``/lms/envs/common.py``, set the values for the following parameters.
+
+ * ``BADGR_API_TOKEN`` - a string containing the API token for the Badgr
+   superuser account. Obtain the token from the /v1/user/auth-token page
+   while logged in to the API as the superuser.
+
+ * ``BADGR_BASE_URL`` - a string containing the base URL for Badgr Server.
+   The Badgr Server must be installed at a publicly accessible IP address.
+
+ * ``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``.
+
+
+   .. code-block:: bash
+
+     ############## Badgr OpenBadges generation ##############
+
+     BADGR_API_TOKEN = None
+     # Do not add the trailing slash here.
+     BADGR_BASE_URL = "http://localhost:8005"
+     BADGR_ISSUER_SLUG = "test-issuer"
+
+
+3. Save the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files.
+
+#. Run database migrations.
+
+#. Restart the Studio and Learning Management System processes so that the
+   updated environment configurations are loaded.
+
+
+***************************************************************
+Configure Badges and Badge Images for Your Open edX Instance
+***************************************************************
+
+#. 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``.
+
+#. Under **Site Administration** > **Certificates**, define a Badge Image
+   Configuration for each course mode on your platform for which you want to
+   issue badges. For example, "honor" and "verified".
+
+#. For each badge image configuration, set these parameters.
+
+ * Course Mode
+ * Icon -- the badge image to use for the specified course mode
+
+ .. important:: Default images are supplied for badges. You must replace the
+    default 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 the original badge image, even if you subsequently change
+    badge images in the Django Administration badge image configuration.
+
+4. Optionally, define a default image for any course modes that do not have an
+   explicitly specified badge image. Select **Default** in the badge image
+   configuration. 
+
+   .. note:: You can specify only one default badge image.
+
+#. Save each configuration parameter and exit the Django Administration website.
+
+
+*****************************************
+Enable Badges Within Each Course
+*****************************************
+
+Badge issuing is enabled by default for all courses, but can be turned off or
+on again using an advanced setting in Studio. For details, see `Enable Badges
+In Each Course`_ in *Building and Running an Open edX Course*.

en_us/install_operations/source/configuration/enable_certificates.rst

@@ -0,0 +1,178 @@
+.. include:: ../links.rst
+
+.. _Enable Certificates:
+
+#######################
+Enabling Certificates
+#######################
+
+Organizations and course teams can now generate certificates for learners who
+have completed courses. Learners can view, print, or share their certificates.
+
+For information about certificates, see the *Building and Running an Open edX
+Course* and *Open edX Learner's* guides.
+
+To enable this feature on your instance of Open edX, you must enable the
+feature flag in both Studio and the Learning Management System and perform the
+configuration tasks described in this topic.
+
+.. Note::  
+  Before proceeding, review :ref:`Guidelines for Updating the edX Platform`.
+
+.. contents::
+   :local:
+
+
+*****************************************************************
+Enable Certificates in Studio and the Learning Management System
+*****************************************************************
+
+#. In the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files, set the
+   value of ``CERTIFICATES_HTML_VIEW``  to ``True``.
+
+   .. code-block:: bash
+
+     # Certificates Web/HTML Views
+     'CERTIFICATES_HTML_VIEW': True,
+
+#. Save the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files.
+
+#. Run database migrations.
+
+
+**********************************************************
+Configure Certificates for Your Open edX Instance
+**********************************************************
+
+#. 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.com/admin``.
+
+#. Under **Site Administration** > **Certificates**, add an HTML View
+   Configuration, and select **Enabled**.
+
+#. Modify the configuration parameters. You must set the following
+   certificates-related parameters for your Open edX instance.
+
+ * ``platform_name``
+ * ``company_about_url``
+ * ``company_privacy_url``
+ * ``company_tos_url``
+ * ``company_verified_certificate_url``
+ * ``logo_src``
+ * ``logo_url``
+
+
+   For each course mode, such as "honor" or "verified", define
+   ``certificate_type``, ``certificate_title`` and
+   ``document_body_class_append``. The mode name should match your course mode
+   name exactly.
+
+   .. code-block:: bash
+
+    {
+        "default": {
+            "accomplishment_class_append": "accomplishment-certificate",
+            "platform_name": "YourPlatformName", 
+            "company_about_url":"http://www.YourOrganization.com/about-us",
+            "company_privacy_url": "http://www.YourOrganization.com/our-privacy-policy",
+            "company_tos_url": "http://www.YourOrganization.com/our-terms-service",
+            "company_verified_certificate_url": "http://www.YourOrganization.com/about_verified_certificates",
+            "logo_src": "/static/certificates/images/our_logo.svg",
+            "logo_url": "www.YourOrganization.com"
+        },
+        "honor": {
+            "certificate_type": "honor",
+            "certificate_title": "Honor Certificate",
+            "document_body_class_append": "is-honorcode"
+        },
+        "verified": {
+            "certificate_type": "verified",
+            "certificate_title": "Verified Certificate",
+            "document_body_class_append": "is-idverified"
+        },
+        "base": {
+            "certificate_type": "base",
+            "certificate_title": "Certificate of Achievement",
+            "document_body_class_append": "is-base"
+        },
+        "distinguished": {
+            "certificate_type": "distinguished",
+            "certificate_title": "Distinguished Certificate of Achievement",
+            "document_body_class_append": "is-distinguished"
+        }
+    }   
+
+4. Save the configuration parameters and exit the Django Administration website.
+
+#. Restart the Studio and Learning Management System processes so that the
+   updated environment configurations are loaded.
+
+
+******************************************************
+Customize Certificate Templates For Your Organization
+******************************************************
+
+Set up the templates for certificates that your organization will issue. Base
+templates are included, but you must ensure that they are customized for your
+organization. For example, you can change the images that appear on
+certificates for each course mode that your organization supports, as well as
+fonts and colors that are used on certificates.
+
+Assets for HTML certificates exist in the following locations.
+
+* **lms/templates/certificates** - this folder contains .html files for
+  certificates. The file ``valid.html`` is an example of a certificate file.
+  Files with names starting with an underscore, such as
+  ``_certificate_footer.html`` are partial files that can be referenced in the
+  main certificate .html files
+
+* **lms/static/certificates** - subfolders of this folder contain assets used in
+  creating certificates, such as images, fonts, and sass/css files. 
+
+  .. note:: The organization logo on a certificate is uploaded in Studio. For
+     details, see `Set Up Course HTML Certificates`_ in *Building and Running
+     an Open edX Course*.
+
+
+*****************************************
+Configure Certificates Within Each Course
+*****************************************
+
+Within Studio, course team members with Admin privileges can create and edit a
+certificate configuration that is used to generate certificates for their
+course, including adding signatories and images for organization logo and
+signature images for signatories. For details, see `Set Up Course HTML
+Certificates`_ in *Building and Running an Open edX Course*.
+
+
+*****************************************
+Generate Certificates For a Course
+*****************************************
+
+To generate certificates for a course, run the ``manage.py`` script with the
+following settings. When the script finishes running, grades are calculated
+for learners who are enrolled in the course, and certificates are generated
+for eligible learners.
+
+#. Obtain the course ID for the course for which you are generating
+   certificates. When you view course content in your browser, the course ID
+   appears as part of the URL. For example, in the URL
+   ``http://www.edx.org/course/course-v1:edX+demoX_Demo_2015``, the course ID
+   is ``course-v1:edX+demoX_Demo_2015``. For some courses, the course ID 
+   contains slashes. For example, ``edX/Demox/Demo_2014``. 
+
+#. Run ``manage.py`` with the following settings, replacing ``{CourseID}``
+   with the actual course ID. Do not include beginning or trailing slashes.
+
+   ``/manage.py lms --settings=aws ungenerated_certs -c {CourseID}``
+
+   For example, 
+
+   ``/manage.py lms --settings=aws ungenerated_certs -c course-v1:edX+demoX_Demo_2015``.
+
+3. View the certificate generation status for a course using ``gen_cert_report``. For example,
+
+   ``/manage.py lms --settings=aws gen_cert_report -c course-v1:edX+demoX_Demo_2015``.
+
+

en_us/install_operations/source/configuration/index.rst

@@ -16,3 +16,6 @@ options.
    enable_entrance_exams
    enable_licensing
    edx_search
+   enable_certificates
+   enable_badging
+

en_us/install_operations/source/links.rst

@@ -60,3 +60,8 @@
 .. _ParseNotificationDelegate.java: https://github.com/edx/edx-app-android/blob/master/VideoLocker/src/main/java/org/edx/mobile/module/notification/ParseNotificationDelegate.java
 
 .. _edX Managing the Full Stack: https://github.com/edx/configuration/wiki/edX-Managing-the-Full-Stack
+
+.. _Set Up Course HTML Certificates: http://edx.readthedocs.org/projects/open_edx_course_authors/build/html/building_course/creating_course_certificates.html#setting-up-course-certificates
+
+.. _Enable Badges In Each Course: http://edx.readthedocs.org/projects/open_edx_course_authors/build/html/building_course/creating_course_certificates.html#enable-or-disable-badges-for-your-course
+