Commerce Coordinator Technical Glossary
- Phillip Shiu (Deactivated)
Draft
This is a summary of some of the vocabulary we’ve been using to think about the Commerce Coordinator.
Glossary
Action
Definition: An operation that needs to run before, during, or after a purchase.
Has inputs and outputs.
Purchase Action Flow (or just Purchase Flow)
Definition: A sequence and record of Actions for a purchase.
One purchase can start many Purchase Flows.
The output of one Action in a Purchase Flow may be required for the input of the next Action in a Purchase Flow.
Internal Connections (defined later) are what connect one Action in the Purchase Flow sequence to the next Action in the Purchase Flow sequence.
Service
Definition: Independently deployed software that performs an Action in a Purchase Flow.
A Purchase Flow triggers one or more Services to perform Actions in a certain sequence.
A Service can offer and implement the same Action.
Services that are part of Open edX are an Open edX Service.
Services that are not part of Open edX are a Third Party Service.
The legacy Ecommerce service is special.
We pretend it’s a Third Party Service.
Why: In the future, we want the legacy Ecommerce service functions to be external.
Action Implementation
Definition: The implementation of an Action for a Service.
Example: Different Services can implement the same Action. (Credit Card Processor 1, Credit Card Processor 2…)
Action Implementations must do the same thing and accept/produce compatible input/outputs as other Action Implementations for the same Action.
Commerce Coordinator (or just the Coordinator)
Definition: A Django IDA that connects Services to perform Actions in a Purchase Flow.
The Coordinator connects:
Third Party Services and Open edX Services
Third Party Services and other Third Party Services
The Coordinator generally does not connect Open edX Services to other Open edX Services. There are other better ways to do that.
Exception: The legacy Ecommerce service. See notes under “Service”.
Plugin (sometimes called by its old term, a Component)
Definition: A Commerce Coordinator Python Django application, loaded either directly via the Commerce Coordinator or side-loaded by an openedx-plugin that either:
is an Action Plugin, and implements a single Action in one or more Services in a single Purchase Flow.
is a Service Plugin, and performs one or more Actions with a single Service in one or more Purchase Flows.
Connection
Definition: A way to send or receive information for an Action:
by a Plugin from another Plugin: an Internal Connection.
by a Plugin to/from a Service: an Outgoing External Connection.
by a Service to/from a Plugin: an Incoming External Connection
A Plugin typically has:
External Connections with one and only one Service.
Supported Internal Connections, which may be exercised via configuration to connect the Plugin with one or more other Plugins
Incoming External Connection
Definition: A way to send or receive information for an Action by a Service to/from a specific Plugin supporting that Service.
Implementations:
Incoming API Resource
An API resource provided by the Coordinator that is called by a Service.
Includes a response from the Coordinator.
Incoming Event
An event emitted by the Service and sent to the Coordinator’s event bus.
Is an Incoming Open edX Event if sent from another Open edX Service.
This distinction is important because Open edX Input Events use the Open edX Event Bus, which uses an Incoming Event Bus Signal to fire an Incoming Open edX Event.
Is an Incoming External Event if sent from an External Service.
Internal Connection
Definition: A way to start an Action in another Plugin.
Is part of a Purchase Flow.
Open question: Where should the definition of an Internal Connection be stored?
Open question: What will be the “minimum definition” for all Internal Connections in general?
Open question: What will be the “minimum definition” for all Internal Connections in a Purchase Flow?
Implementations:
Signal (& Receivers)
Used when we do not need a synchronous response from the other Plugin.
Configured in
CC_SIGNALSat https://github.com/edx/commerce-coordinator/blob/main/commerce_coordinator/settings/base.py#L266CC_SIGNALSdetermins which Receivers activate when a given Signal is emitted.
Filter (& Pipeline Steps)
Used when we need a synchronous response from another Plugin.
Configured in
OPEN_EDX_FILTERS_CONFIGat https://github.com/edx/commerce-coordinator/blob/main/commerce_coordinator/settings/base.py#L293.OPEN_EDX_FILTERS_CONFIGdetermines which Pipeline Steps activate when a given Filter is activated.
Outgoing External Connection
Definition: A way to send or receive information for an Action by a Plugin to/from a Service.
Implementations:
External API Resource
An API resource provided by the Service that is called by the Coordinator.
Includes a response from the Service.
Output Event
An event emitted by the Coordinator and sent to the Service’s event bus.
Events sent to other Open edX Services are Open edX Output Events.
This distinction is important because Open edX Output Events use the Open edX Event Bus, which uses Outgoing Event Bus Signals to fire Open edX Output Events.
Events sent to External Services are External Output Events.
Transition-to-Coordinator Waffle Flags
Definition: A Django waffle flag used to redirect traffic to or from legacy ecommerce through Commerce Coordinator.
Transition-to-Plugin Waffle Flags
Definition: A Django waffle flag used to toggle sending incoming requests from a Service to Plugin B instead of Plugin A.
Example
This is an example of a couple of the technical glossary’s terms:
