Commerce Coordinator Technical Glossary

Draft

This is a summary of some of the vocabulary we’ve been using to think about the Commerce Coordinator.

Types of connections in Commerce Coordinator, and which file they should be put in.

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_SIGNALS at commerce-coordinator/commerce_coordinator/settings/base.py at main · edx/commerce-coordinator
    - CC_SIGNALS determins 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_CONFIG at commerce-coordinator/commerce_coordinator/settings/base.py at main · edx/commerce-coordinator.
    - OPEN_EDX_FILTERS_CONFIG determines 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:

Example of a GET of Order History.

Future Work

Add an example of an entire Purchase Action Flow using vocabulary of the glossary upfront
Add specific examples for key glossary items (e.g., of an Action)
Go back and make ADRs and other documents consistent with this glossary.
Note: Essentially, our signal configuration is a list of subscribers to topics. In Commerce Coordinator, the subscribers are methods in Plugins, and the topics are Incoming Connections/Signals.
Still need: Traceability, storage/auditing, replayability
Note: Need to investigate having Commerce Coordinator be a message bus to message bus
Add Receiver for Signals & Pipeline Steps for Filters