Fluent Commerce Logo
Docs
Sign In

Extend the Connector Contract

Essential knowledge

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: 
    `<fluentcommerce>.<connector/module><domain>.<action/event name>`
    For example: 
    `fc.connect.product.upsert`
     a. Commands (aka action): 
    `<fluentcommerce>.<domain>.<action/event name>`
     b. Event: 
    `<domain>:<entity>:<event name>`
     c. 
    `fluentcommerce`
     should be replaced with account id for client-specific implementations For example: 
    `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


Fluent Commerce

Fluent Commerce

Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Fluent Logo