Open edX has an adlnet working group to facilitate the creation and publishing of xAPI events specific to Open edX or that do not currently exist to meet our use cases.

Joining the adlnet working group

1. Read these to make sure you understand what the work is:

   1. This document!

   2. The adlnet Getting Started

   3. The adlnet FAQs

2. Create an account on adlnet

3. And ask to join from the working group page

4. Ping @Brian Mesick or @Edward Zarecor in the #wg-data of the Open edX Slack, or the Data WG on Discuss for approval

Working on Profiles

xAPI transformations are handled in the event-routing-backends plugin. Existing transformations are documented here: https://github.com/openedx/event-routing-backends/blob/master/docs/event-mapping/Supported_events.rst

1. Identify the Open edX event that will be transformed, and try to find all of the places where it may be emitted. Different sources may include different information (ex: events that are generated via learner action but also by bulk action management commands).

   1. Document the superset of properties that may be on the event and the whether they will are always present or optional.

2. Check the ADL xAPI Profile Server for existing Profiles that closely match our event properties.

   1. Before starting on a new profile, make sure that our needs can’t be met by an existing Profile or by mixing and matching existing Profile components.

   2. There are some existing Profiles which have almost everything what we need, in which case we should extend those by creating a new Profile using the relevant existing fields (Verbs, Actors, Objects, and Contexts) and adding in Open edX necessary fields.

   3. There are some Profiles which require more than we have access to in our tools (ex. video events from mobile?). In those cases we may create a new Profile using Verbs/Objects/Contexts from the previously existing Profile, but omitting things that we do not have.

      • In some situations it may make more sense to choose to send blank or default values for those fields if the creation of a new Profile if we have the values sometimes but wish to maintain a single Profile for the event (web vs mobile video).

3. If it is necessary create a new Profile, make sure there is a ticket for the work on the Data Working Group board: https://github.com/orgs/openedx/projects/5/views/1

   1. Update the ticket with:

      1. The findings about the Open edX event fields

      2. Which existing Profiles may function as a foundation for the new Profile

      3. A description of the Profile you wish to create (doesn’t need to be the full JSON description at this point)

      4. The IRI you suggest to use for this Profile, details for choosing an IRI are here in the “IRI Design Practices” section. We will use “external IRIs” for readability as the generated IRIs utilize guids to create uniqueness.

   2. Ping @Brian Mesick and @Edward Zarecor for design review, and checking for IRI consistency.

   3. Once approved, you can create a new profile from the adlnet Working Group page with the approved IRI. name and description.

      1. Note that the IRI cannot be changed after creation

      2. There is a section for translations, I believe those are translations of the “name” and “description” fields. It’s not very well documented exactly if/where that information is displayed outside of adlnet, or how to craft the translation file and should be considered optional at this point.

      3. The “More information” and “tags” sections are also optional at this time, but encouraged to be added when possible.

   4. Craft the JSON for the Profile in the adlnet editor and test it

      1. When you are happy with the Profile, create a PR against event-routing-backends with the updated transform code, making sure to update documentation in the repo as well.

         1. Test that the generated xAPI Profile meets the JSON-LD and xAPI Profile spec

      2. Create test events using the updated event-routing-backends code, and validate the statements:

         1. adlnet has a tool for statement validation

         2. adlnet also has a test LRS that can be used to test sending statements to

      3. Update the Open edX ticket with a link to the draft Profile and event-routing-backends PR when they have been tested and are ready for review

   5. Once the Profile has been approved, the Profile can be published by creating a PR against this repo: https://github.com/adlnet/xapi-authored-profiles

   6. When the Profile has merged and the event-routing-backends PR has been approved it can be merged and the ticket can be closed!

Open Questions

• What is the full set of events we wish to make xAPI transformers for?

  • Proposal: We try to restrict xAPI to “learner” and “learning” events (learner profile, enrollments, course navigation, video events, problem interactions, grading events, course completion, what else?).

    • This may include certificate related events, open for discussion

    • This would not include business events (non-course page views, purchases, A/B test information that does not impact learning, etc)

    • This would not include site / performance metrics (load / render times, backend or frontend errors, sign in / sign out, etc)

• Do we want to do anything outside the norm for IRIs or are we comfortable using the w3id.org best practice as documented? I assume the latter.

  • Proposal: We prefix the “profile name” with “openedx_” to namespace Profiles we create for Open edX specific reasons.

• Can we work out a better policy for Profile translations, or are we ok leaving them optional for now?

• Are there better authoring and test tools / processes we can use?

• When the ticket has been closed, is there a way we should alert the community to this, or is it just something we should put in the release notes for the next named release?