3. Open edX events payload conventions#
Status#
Accepted
Context#
Given their public promise status, event hooks have maintainability as the main design goal. The contracts we are creating here should be stable enough to support the growth of the extensions community. That said, things should be allowed to evolve in a backwards compatible manner. When things inevitable break, they should break in CI. Which should not require the code of the Open edX platform to test integrations.
Decisions#
1. Events will receive header information in line with the OEP-41 format. However all the fields but data, which are also referred as the envelope information, will be wrapped in a dictionary. The data specific to the event will be passed as unpacked named arguments so that function signature mismatch errors can be caught in CI.
2. The envelope information will be calculated on the fly by the OpenEdxPublicSignal class to keep this information out of the way when writing the event calling location as well.
3. The data sent to an event will always use the form of attr objects following the OEP-49 data pattern . This data objects will be defined in the events library and will be scoped to the Architecture Subdomain they are in. Data objects should use only serializable python primitives and standard types with the exception of OpaqueKeys.
Consequences#
1. Extension developers will be able to test their event listeners without the need to import any Open edX platform code.
2. Consequence of the versioning ADR together with this one, extension developers will be able to test their code with different versions of the library and thus guarantee that their code will not break when upgrading open releases.
The events library will have a dependency on the OpaqueKeys library.
4. Events defined by this library will not be drop-in replacement of current Open edX platform signals. This means some refactoring will be needed when converting the platform code over to openedx_events.