Extend the Connector Contract
Author:
Fluent Commerce
Changed on:
24 Oct 2023
Overview
Describes Fluent’s approach to name messages used by the module’s workflows. The message is a mode of communication between two different systems. The naming convention helps to keep all messages uniform and consistent across all Fluent modules allowing partners to understand and adopt the format and follow it during their customisation.
A message can be of 2 types:
- Command: A Command is a message directed at a receiver to get something done (aka action). The producer of command has an intent and may expect a response from the receiver. Example: create an order
- Event: Events communicate the performed action from one system to another system. It’s a fact that cannot be changed as that has already happened in the past. Example: Order update notification: When the order is created or modified, a notification is sent from Fluent to external systems.
Key points
- Fluent Domains
- Naming rules
Fluent Domains
These domains are based on - Domain Model
Naming rules
Fluent brings a list of predefined and reserved message names that are used across its standard workflows, but it is still possible for any partner or customer to define new ones, and use them in custom workflows. Each Fluent module should describe all available message names (commands and events) that are part of the module.
Public names
Public names are for public API or cross-domain use.
- The message name is formed of three parts: . For example:
`<fluentcommerce>.<connector/module><domain>.<action/event name>`a. Commands (aka action):`fc.connect.product.upsert`b. Event:`<fluentcommerce>.<domain>.<action/event name>`c.`<domain>:<entity>:<event name>`should be replaced with account id for client-specific implementations For example:`fluentcommerce``acme.connect.product.upsert` - Complex names or domains should be lower dot case rather than using camel case
- Event names should not be in the past For example: status-update
- Command names should have the verb/action first For example: upsert-location
- The overall message name should very clearly state the intent of the message
- A message has a single purpose
Internal names
Internal names are for all intermediary steps of a flow and local to the domain and workflow.
- The message name is formed of 3 parts, the domain name followed by a fixed tag and step name: .
`<domain>:internal:<step-name>` - Complex names or domains should be lower dot case rather than using camel case.
- Step names should have the verb/action first. For example: upsert-location
- The name should very clearly state the intent of the step.
- A step has a single purpose.
Domain | Command (actions) | Event (Internal) | Webhooks (external events) | Domain dependencies |
Order | fc.connect.order.create | fc.connect.order.webhook.status-update | ||
Product | fc.connect.product.upsert (UPSERT_PRODUCT) fc.connect.product.category.upsert (UPSERT_CATEGORY) | |||
Fulfilment | fc.connect.location.create fc.connect.location.upsert | |||
Payment | fc.connect.order.transaction.add (FINANCIAL_TRANSACTION) | fc.connect.payment.capture fc.connect.payment.authorise fc.connect.payment.refund | fc.connect.payment.capture fc.connect.payment.authorise fc.connect.payment.refund |
