Frameworks
User Interface Framework (WebApps, Manifest Configuration, Fragments, Components, and their Elements.), Orchestration Framework (Workflow, Actions, Rules, Entities, Contracts, Settings, Triggers, Status, and Variables), Developer Tooling (Modules, Templates, Connectors, and SDKs.)
External Webhook Integration Architecture - commercetools Connector
Essential knowledgeExplains how the commercetools Connector ingests inbound webhooks and dispatches outbound payloads across the integration ecosystem. Partners will learn to configure and apply this shared framework utility, which manages message routing, handler resolution, and internal queue mechanics. For the business, this asynchronous architecture ensures real-time, secure data transmission and protects platform stability by preventing message loss during high-volume storefront traffic spikes.Note: This architectural component serves as a global framework utility rather than a single functional pipeline.- Core Function & Outcome: You will learn how the framework utility orchestrates bidirectional ingress and egress loops, serving as the master execution blueprint for all entity-specific data synchronization pipelines.
- Asynchronous Queue Infrastructure: The architecture processes incoming webhook payloads through an external
`ct-queue` and an internal Event Queue sequentially, decoupling network reception tasks from backend data processing to maintain platform throughput. - Declarative Route Filtering: Implementing partners can manage message names, configure explicit inclusion filters, and reassign target event pathways directly inside the
`application-connector.yml` configuration file. - Extensible Handler Architecture: The core message routing and processing layers are completely decoupled, allowing developers to cleanly register custom storefront event handlers by extending the base
`MessageHandler` class.
Webhooks Frequently Asked Questions
Essential knowledgeThis page contains frequently asked questions about Fluent Webhooks. Due to the nature of being a cloud-hosted application, there are some restrictions in place regarding IP Whitelisting and Authentication that frequently come up.- Static IP Whitelisting: Fluent Commerce's cloud setup doesn't allow for static IP whitelisting due to the potential for IP address changes caused by scaling or architectural adjustments, as well as AWS or GCP's own IP address alterations.
- Authentication Measures: Instead of relying on IP Access Control Lists, Fluent Commerce employs strong authentication measures for webhook requests, including cryptographic signing with a private key and verification using a public key to ensure the request's legitimacy and integrity.
- IP-Based Restrictions: Implementing IP-based restrictions, such as whitelisting or IP ranges, is not recommended due to the dynamic nature of IP addresses in the cloud setup, which can lead to high exposure levels and difficulty in implementation.
- Alternative Approaches for Access Control: Instead of IP-based restrictions, companies can utilize firewall/networking equipment or reverse proxies to restrict access based on incoming HTTP request details, or configure unique, specific static URLs for incoming traffic to filter and accept connections securely.
What are Fluent OMS Entities? (Entity)
Essential knowledgeA detailed explanation of Fluent OMS entities and how they can be used throughout the order journey.- Entities in Fluent OMS are data objects that store and process information throughout the order journey, such as orders, fulfilments, and financial transactions.
- Entities are managed via GraphQL, with mutations and queries used to create, update, and retrieve entity data.
- Entities should not be deleted but controlled using status fields, although some "remove" mutations can disconnect entities.
- Orchestrated Entities trigger a CREATE event upon successful creation, enabling workflow automation.
- Entities in Fluent OMS serve unique purposes to enable an end-end digital commerce journey and their statuses determine at what stage they sit.
- Entities have types and subtypes, types are rigidly defined, subtypes are more flexible.
Users, Roles, and Permissions
Essential knowledgeThe Fluent platform provides a comprehensive user role management system, allowing for the assignment of diverse permissions via roles to regulate platform access and functionalities. Custom roles can be created and fine-tuned, ensuring users only have access to appropriate functionality and data. The system provides flexibility to specify the scope for a role at different context levels, such as Accounts, Retailers, and Locations.- A role can be assigned to multiple users, and a user can be assigned multiple roles.
- Permissions are granular access controls and protect every GraphQL or REST API operations. GraphQL permissions follow specific naming conventions.
- Context plays a pivotal role in access levels, allowing users to have role-based access to data for specific Accounts, Retailers, or Locations.
UX Framework - Configuration Guide
Essential knowledgeThe OMX UX Framework delivers configuration-based solution implementation for UIs (Web Apps). Configuration is managed in a JSON document called the OMX Web App Manifest.- The OMX Web App Manifest document is essential for configuring Fluent Platform web apps and is stored in a setting following the convention "fc.mystique.manifest.<appname>". For instance, Fluent Commerce UIs have settings like "fc.mystique.manifest.oms" and "fc.mystique.manifest.store."
- The document, configured in the ACCOUNT context, is a specific JSON structure that includes sections like App-Level Configuration, Route-Level Configuration, and Local Development Options. Each web app defined within an account has a unique URL, and the Manifest guides app development, covering aspects like navigation, screen layouts, data sources, and user actions.
- Manifest updates can be done through Console/settings or directly via the API, with the ability to partition the document for manageability.
Fluent Analytics Studio
Essential knowledgeAnalytics Studio is a dedicated web application within Fluent that enables users to explore, analyse, and act on business data. Where embedded Fluent Analytics metrics are designed for monitoring in specific contexts, Analytics Studio is designed for investigation, giving users access to dashboards, individual records, and data exports to understand what drives changes in key metrics.- Analytics Studio is a dedicated web application for exploring and analyzing business data
- The application is available at
`https://<ACCOUNT_ID>.<ENVIRONMENT>.apps.fluentcommerce.com/analytics` - It extends dashboards by allowing access to the underlying records behind metrics
- Users can investigate issues, identify trends, and understand what is driving changes in key metrics
- The application supports exporting data, setting alerts, and scheduling reports
- Built-in dashboard actions allow users to refresh data, reset filters, change time zone settings, export dashboards, and schedule reports
Sources Interface
Essential knowledgeThe Sources interface provides inventory and batch-processing metrics visibility, enabling data ingestion and processing efficiency tracking. It includes:- Sources Dashboard – Monitors inventory updates, failure rates, and processing times.
- BPP Metrics Dashboard – Tracks batch-processing efficiency, showing processed, changed, and unchanged records with a date range filter of up to 31 days.
Both dashboards use structured data, support trend analysis within configurable time frames, and require METRICS_VIEW permission for access.- Sources Dashboard provides real-time tracking of failed updates, update frequency, total received updates, and estimated processing times.
- BPP Metrics Dashboard enhances visibility into batch data ingestion by tracking record modifications.
Stock Segmentation - Data Model and API Overview
Essential knowledgeStock Segmentation extends Fluent’s Inventory and Virtual Catalog data models to represent multiple logical segments for the same product and location using explicit, queryable factors.Stock Segmentation supports scenarios such as channel-specific reservations, manufacturing batch traceability, compliance restrictions (for example by country of origin), and supplier-level inventory management while preserving a single physical inventory model per product and location.This document explains the data model and GraphQL API capabilities introduced for Stock Segmentation.- Physical stock in the Inventory Catalog is represented through Inventory Quantities that can be segmented using dedicated fields such as
`condition`, `expiresOn`, `countryOfOrigin`, `channel`, `manufacturer`, `manufacturerBatchNumber`, `supplier`, and `segment1/2/3` - Inventory Quantities support parent-child hierarchies, allowing multi-level segmentation trees to be modeled explicitly via the parent relationship
- Inventory Quantities can be linked to operational entities using
`associationType` and `associationRef`, particularly for reservation linkage and traceability - Virtual availability can expose a single customer-facing segment using Virtual Segments
- Segmentation fields are exact-match searchable to ensure predictable query behavior (partial matching is not supported)
ICP, Qualification Criteria and Additional Use Cases
Essential knowledgeThe article provides a comprehensive guide to identifying the Ideal Customer Profile (ICP) for an Order Management System (OMS), highlighting key criteria and red flags to ensure successful implementation. It also explores Fluent OMS use cases, showcasing its capabilities in order capture, fulfillment, tracking, promising, shipping, and inventory management.- Ideal Customer Profile (ICP) based on specific industries, company maturity, and high order volumes
- Poor fit indicators, such as outdated legacy infrastructure or a lack of executive buy in
- Fast Qualification Framework to rapidly assess a prospect's Budget, Systems, Volume, and Channels.
Fluent Big Inventory Web App Overview
Essential knowledgeThe Fluent Big Inventory Web App is a powerful tool for managing products, inventory, feeds, and sources. Key features include:- Feeds: View inventory feed details.
- Sources: Track inventory update integrations.
- Products: Manage catalogs and product data.
- Unifies View of Inventory: Gain real-time inventory insights across locations and channels for optimal stock management.
- Inventory: Monitor allocation, Stock On-Hand (SOH), real-time updates, and buffers.
- Stores: Oversee individual and network locations.
- Insights: Track system events.
- Admin: Configure user access and settings.
- The Fluent Big Inventory Web App offers a comprehensive suite of functionality.
- With dedicated interfaces for Sources, Products, Inventory, Stores, Insights, and Admin, the web-based interface provides users with a holistic toolset, allowing them to observe and track integrated sources, manage product catalogues, exercise precise control over inventory, oversee individual and networked store locations, monitor system events comprehensively, and efficiently administer the entire inventory availability system for a seamless and valuable user experience.
Overview of Payments in Fluent
Essential knowledgeThe Fluent platform enables payment orchestration across the full lifecycle of an Order. Using the OMX Workflow Framework and core payment entities, businesses can implement custom logic for fulfilment, capture, refunds, and reconciliation. This document outlines the Payments Data Model and GraphQL API capabilities, excluding reference Rules, Workflows, or UX components. Financial operations within the Payments domain rely on precision-safe monetary representations to ensure accuracy and consistency across transactions.- This document covers the Payments data model and GraphQL API
- Payments are usually fulfilment-driven, but capture can occur at different stages depending on workflow configuration
- Core entities: FinancialTransaction (funds source), Payment (capture/refund), PaymentTransaction (status log)
- Monetary values support precision-safe amounts via preciseAmount (BigDecimal/NUMERIC); legacy Float fields remain optional for backward compatibility
UX Configuration - Common Concepts
Essential knowledgeSome common types and conventions are used across many component definitions. These items are not directly configurable in the manifest but will often be referenced in other component definitions that use them.- The Mystique manifest configures icons, cards, and template strings. Icons come from React Icons.
- Cards have common fields, and template strings allow dynamic values. Dynamic attributes (standard, image, component) offer flexibility based on conditions.
- A selection of helper functions are also available to control and transform these values as required, for example, number, logic, i18n, array, date, and string functions.
- Additional options like TextOptions and ImageOptions provide styling choices.
Introduction to the Events API
Essential knowledgeThe Events API is a core component of the Fluent Platform, enabling the creation and management of events that drive workflow logic and system activity tracking. It supports asynchronous operations for optimized performance and integrates with systems for inventory updates, product data transfer, fulfillment, and carrier tracking.- Events are fundamental to the Fluent Platform, representing actions or occurrences within the system.
- The Events API enables viewing and creating events, supporting workflow logic and system activity tracking.
`ORCHESTRATION` events trigger workflows, while `ORCHESTRATION_AUDIT` events log workflow execution details.- Common Event API operations include retrieving events by ID, filtering events, and creating new events asynchronously.
- Event Contracts are defined by Rulesets in workflows, combining event attributes to handle specific processes.
- Recommended practice: Use asynchronous integration for non-real-time actions to optimize performance.
- Common integrations include inventory updates, product master data transfer, fulfillment updates, and carrier tracking.
Responsive Sourcing Framework Overview
Essential knowledgeThe Responsive Sourcing Framework is a configurable, scalable alternative to custom Workflows and Rules for managing sourcing strategies. You’ll learn how to define and optimize sourcing logic using Sourcing Profiles, Strategies, Conditions, and Criteria. The Framework empowers both technical and business users with faster implementation, greater control, and transparency into how sourcing decisions are made and why.- Prerequisites: You should have knowledge of Order Management and Order lifecycle, Order Reference Module, and GraphQL API
- The Responsive Sourcing Framework is designed for both technical and business users - logic is transparent and comes with a configurable User Experience (UX)
- Enables faster implementation by reusing modular sourcing logic building blocks such as Sourcing Profiles, Strategies, Conditions, and Criteria
- Sourcing Profile GraphQL API is required to correctly set up your sourcing logic
- Supports custom Sourcing Conditions and Criteria through externally developed extensions for advanced or domain-specific logic
Sourcing Profiles Interface
Essential knowledgeThe Sourcing Profiles functionality in the Fluent OMS Admin interface enables retailers to configure, manage, and optimize sourcing rules. Profiles group strategies with defined priorities, catalogs, and networks, while strategies use flexible conditions (IF) and criteria (THEN) to refine fulfillment logic. New profiles are created via API, while profile versions can be generated either through the Admin UI or API. The UI provides capabilities to view, edit, reorder, activate, and track versions.- Part of Admin UI: Sourcing Profiles are managed in the Admin interface for Fluent OMS.
- Profile Versions: Editing a profile in the Admin UI triggers the creation of a new draft version via the
`updateProfile` mutation. - Centralized Management: View all active profiles with key details such as version, status, last updated, default catalog, networks, and max split.
- Sourcing Strategies: Create new strategies (including fallback) and edit existing ones. Strategies within profiles are assigned priorities, ensuring that the most critical business rules are applied first.
- Conditions & Criteria: Define or adjust fulfillment logic using configurable IF conditions and THEN criteria.
- Intuitive Editing Experience: Users can easily add or configure conditions, set maximum splits, and apply catalogs or networks through guided forms.
Product Description - Fluent Commerce OMS
Essential knowledgeFluent Order Management components are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure. These components operate within the framework to enable the order management experience on the platform.- The main components that comprise the platform architecture are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure.
- Each Module represents a particular business domain and its associated rules and workflows. Core, Inventory, Order and fulfilment are the four Fluent modules.
- These are the web and in-store interfaces used to access module functionality.
Product Description - Fluent Commerce OMS
Essential knowledgeFluent Order Management components are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure. These components operate within the framework to enable the order management experience on the platform.- The main components that comprise the platform architecture are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure.
- Each Module represents a particular business domain and its associated rules and workflows. Core, Inventory, Order and fulfilment are the four Fluent modules.
- These are the web and in-store interfaces used to access module functionality.
Orchestration Webhooks
Essential knowledgeFluent workflows use webhooks for real-time communication with external systems, triggered at specific workflow points. Webhooks provide timely updates for order status, shipping, payments, and inventory movements. The standard SendWebhook rule simplifies outbound communication by sending basic data, allowing external systems to retrieve additional information as needed.- Webhooks enable real-time communication between Fluent workflows and external systems, eliminating the need for frequent API polling.
- The
`sendWebhook` rule simplifies outbound communication by passing essential data that external systems can use to fetch additional details. - Typical use cases include order status updates, shipping notifications, payment captures, and stock transfers.
- Webhooks should not be used for Inventory domain operations due to scalability concerns, performance impacts, and stability risks, so use Inventory Feeds instead.
- In rare cases where inventory-related webhooks are required (e.g., conditional stock change notifications), contact our team to discuss alternatives before implementation.
Workflow Framework Overview
Essential knowledgeThe Workflow Engine (aka Rubix) is the engine that drives the Fluent platform. The Workflow Engine enables business process orchestration, workflow automation, and underpins the specific feature sets and functionality for each of the Fluent apps. Additionally, the Workflow Engine is built to be highly scalable, and provide high-performance workflow execution across any domain.- Cloud-native, high availability, scale-on-demand workflow execution.
- Pre-built, customizable workflows delivering capabilities across each of the Fluent App domains.
- Rich Rule Library containing reusable rules across each of the Fluent Apps.
- Software Development Kit (SDK) and Developer Tooling, enabling the implementation of custom rules and integrations.
- Business Tools to manage, configure, and implement workflow and process automation.
Overview of Pick and Pack
Essential knowledgeThe Pick and Pack feature suiteof the Store Fulfilment app allows stores to pick and pack online orders that are allocated to the store based on store inventory at the time of order creation. The Fluent Store’s interface is used to access the capabilities of the Pick and Pack feature suite.- Adaptability: The process is responsive, ensuring a seamless experience on screens of varying sizes. Customization options are available through UI configuration or creating new components.
- Process Stages: The wave process involves creating a wave, picking order items, packing them, and booking carriers.Prioritization logic is applied based on factors such as expiration dates, order types, or delivery types.
- Efficient Picking: Picking orders is initiated by creating a wave, followed by selecting orders and using a user-friendly PICK component.Confirmation of picked items involves a final review, confirmation, and automatic rejection of unpicked items.
- Completion Process: The wave-picking process leads to the completion of fulfilling online orders in-store, providing a streamlined approach to order fulfillment.
Unified View of Inventory Interface
Essential knowledgeThe Unified View of Inventory (UVOI) interface consolidates data from multiple locations and channels into a single, real-time interface. It provides centralized inventory search, advanced filtering, and customizable views. It enables you to monitor, analyze, and act on inventory data.- Centralized Inventory Management: The Unified View of Inventory (UVOI) consolidates data from multiple locations and channels into a single, real-time interface, simplifying inventory management and improving decision-making.
- Advanced Filtering Capabilities: UVOI offers flexible filters for refining search results, including catalog, stock status, on-hand quantities, and product or location-specific criteria.
- Comprehensive and Customizable Views: The Inventory Search page provides a detailed overview of inventory, with drill-down capabilities for stock levels, available-to-sell quantities, and update histories. Users can navigate to location-specific or product-specific views and customize filters and criteria to tailor the experience to their operational needs.
Inventory Interface
Essential knowledgeThe Inventory interface of the Fluent Web app provides comprehensive inventory management capabilities:- Inventory visibility
- Inventory allocation
- The total quantity of stock for a specific item (stock on hand(SOH)) and the status of that inventory
- Available to promise inventory levels
- Inventory buffers to reduce overselling of products
- The Fluent Web app's Inventory interface offers a comprehensive suite of capabilities, including inventory visibility, allocation, total stock quantity (stock on hand), inventory status, available-to-promise levels, and strategically implemented buffers to prevent product overselling.
- The interface is equipped with various configurations, such as Inventory Catalogues, Control Groups, Virtual Catalogues, Cross-Catalogue Views, and Location Inventory Views, providing users with versatile tools to tailor their inventory management approach according to specific business needs and scenarios.
Pack for Multi-Parcel Shipments
Essential knowledgeThe Pack feature of the Fluent Store empowers Store Associates to efficiently manage the packing process for multi-parcel shipments. It allows them to allocate items to specific parcels, add new parcels as needed, set parcel dimensions and weight, remove parcels, and reject items that don't meet requirements. This feature ensures that each parcel is properly organized and labeled, giving Store Associates complete control over the packing process.- Store Associates can choose which fulfillment to pack next, optimizing the packing process based on operational needs.
- Fulfillments are organized into two tabs—Awaiting Pack and Packed Fulfillments—providing a clear overview of the packing stages.
- A badge displays the number of fulfillments awaiting packing, helping Associates manage their tasks efficiently.
- Store Associates can allocate items to specific parcels, add or remove parcels, set dimensions and weight, and reject items.
- The integrated barcode scanner speeds up the packing process by quickly and accurately identifying parcels and items.
Order Management Interface
Essential knowledgeThe Order Management interface is the central workspace for managing the order lifecycle. It brings together orders, customers, billing accounts, returns, and escalated fulfilments in one view. Orders provide access to details and fulfilments. Customers show records including accounts and order history. Billing Accounts manage financial operations such as invoices, memos, and payments. Returns track customer or system-initiated cases with refund details. Escalated Fulfilments highlight exceptions requiring action.- The Order Management interface brings together orders, customers, billing accounts, returns, and escalated fulfilments in one place.
- It enables visibility and control over the entire order lifecycle, from creation through fulfilment, return, or escalation.
Product Description - Fluent Commerce OMS [Superseded - Document Version 1.0]
Essential knowledgeFluent Order Management components are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure. These components operate within the framework to enable the order management experience on the platform.- The main components that comprise the platform architecture are Web Apps, Modules, Order Management Experience (OMX), Orchestration Engine, and Cloud Infrastructure.
- Each Module represents a particular business domain and its associated rules and workflows. Core, Inventory, Order and fulfilment are the four Fluent modules.
- These are the web and in-store interfaces used to access module functionality.
MockApiClient
Essential knowledgeThe `MockApiClient` is a critical component of the `util-test` library. It provides a mock implementation of the `ApiClient`, which is the interface Rules use to communicate with the Fluent Commerce GraphQL API.By using the `MockApiClient`, you can test how your Rule behaves with different API responses without making any actual network calls. This isolates your tests, makes them faster, and allows you to simulate any scenario, including errors or empty data results.
- Test API Interactions: The
`MockApiClient` allows you to test how your rule responds to different API outcomes (e.g., success, failure, empty data) without making live network calls. - Isolate and Speed Up Tests: By mocking the API, your tests run faster and are isolated from network or environment issues.
- Executor Integration: You typically don't use
`MockApiClient` directly. You use the helper methods on `RuleExecutor` and `WorkflowExecutor` (like `.mockQuery()` and `.mockSetting()`) to configure it. - Full Coverage: It supports mocking pre-compiled queries/mutations, dynamic queries/mutations, and settings, giving you complete control over your test environment.
Master Buffer: Strategic Adjustment of Available-to-Sell (ATS) Quantity
Essential knowledgeUnderstand the Master Buffer: a tool for final Available-to-Sell (ATS) quantity adjustments. This guide covers its function, configuration, and strategic applications. Using it offers precise, SKU-level ATS control, helping optimize stock, support promotions, prevent over/underselling, and align inventory with business goals.- Key Points:
- Final SKU-level ± adjustment applied after all quantity buffers to the aggregated SOH.
- Directly modifies ATS; negative calculated ATS becomes zero.
- Intended for strategic, deliberate application.
- Concluding ATS modifier: Applies a direct SKU-level override after all quantity buffers, just before ATS is calculated.
- Strategic & Product-Specific: Use it for deliberate, product-level inventory goals (like promotions or managing supply risks), not for general, location-based stock on hand buffering.
- Direct Impact on Sales: A positive buffer value increases ATS; a negative value decreases it. A resultant negative ATS will always be floored to zero.
- Use Deliberately & Review: Due to its significant impact, apply the Master Buffer thoughtfully. Document the rationale and regularly review its necessity.
Extending the UX Framework with the Component SDK
Essential knowledgeThis lesson introduces the Component SDK, a powerful toolkit for extending the UX Framework Component Library. We'll explore the core concepts behind the SDK, covering its purpose, capabilities, and benefits. By the end of this lesson, you'll understand how the Component SDK empowers developers to create custom, OMX-ready components for Fluent Web Apps, streamlining development and ensuring consistent user experiences.- What is the Component SDK? A development kit for building custom components for the UX Framework Component Library using modern, developer-friendly tools like React and TypeScript.
- What can be extended? Developers can create a wide range of components, including content, layout/page, interaction, form field components, and template helpers, significantly expanding the functionality of the standard library.
- Why use the Component SDK? The SDK simplifies custom component creation by handling complex tasks like manifest configuration, authorization, data access, localization, and workflow interaction, allowing developers to focus on component logic and design. It also leverages the Fluent OMX Design System (based on Material-UI) for consistent and high-quality UX.
Setting up the Manifest Document
Essential knowledgeThis lesson introduces the Manifest document, a crucial component in defining the structure and layout of Fluent Web Apps. We'll cover how to set up your development environment with a pre-configured VS Code workspace, understand the key elements of a Manifest document, and learn how to create a new web app by defining an account-level setting. We'll also explore the different types of routes used in Manifests and walk through creating a simple page route. This setup and introduction will prepare you for more advanced Manifest configurations in later lessons.- VS Code Setup: Use the provided VS Code workspace for Manifest editing.
- Manifest Definition: The Manifest defines a Fluent Web App's structure, layout, navigation, and data.
- Account Setting: Manifests are stored as account-level settings.
- Web App Access: Web apps are accessed via URLs based on the Manifest's appName.
- Key Elements (Name, Title, Context, Routes): Manifests define these core elements.
- Route Types: Page, Section, and Reference routes define navigation within the app.
Manifest Creation and Customization
Essential knowledgeThis series of lessons guides you through building a feature to manage storage areas within the Fluent Store web app. We'll cover creating a new Manifest fragment, adding it to account settings, and referencing it in the main Manifest. We'll then add a List component to display storage areas, configure a data source for the list using a page query, and create a details page for individual storage areas. Finally, we'll explore working with dynamic values, including date formatting, array access, image rendering, and configuring i18n language translation.- Manifest Fragment Creation: Learn to create and configure a new Manifest fragment for managing storage areas.
- Account Settings Integration: Integrate the new fragment into account settings and reference it in the main Manifest.
- List Component Integration: Use the List Component to display storage area data.
- Data Source Configuration: Use the
`activeLocation` context to configure a page query as a data source for the List Component. - Details Page Creation: Create a details page for individual storage areas with a dedicated page query.
- Dynamic Value Handling: Learn to work with dynamic values using formatters (e.g.,
`dateStringFormatter`), array access, attribute retrieval by name, and image rendering. - i18n Configuration: Configure i18n language translation keys for the web app.
Understanding Manifest Structure
Essential knowledgeThis lesson details the structure of Manifest documents, covering both main web application manifests and fragment manifests. We'll explore the required fields and optional configurations for the main manifest, including context, routes (section, page, and reference), and plugin integration. We'll also examine the simpler structure of fragment manifests and how they contribute to managing complex UI configurations.- Manifest Types: There are two types of Manifests: main and fragment.
- Main Manifest Structure: Required fields include manifestVersion, name, title, context, and routes. Optional fields include homePath.
- Context Configuration: Defines whether the app operates at a LOCATION or RETAILER level and allows role-based access control.
- Routes (Section, Page, Reference): Routes define the navigation menu. Section routes group menu items, Page routes link to specific pages, and Reference routes include fragment manifests.
- Fragment Manifests: Fragment manifests contain only manifestVersion and routes, allowing for modular management of large Manifest configurations.
- Plugin Integration: The Manifest can include references to custom component plugins hosted externally.
Introduction to the Component Library
Essential knowledgeThis lesson introduces the OMX Component Library, a collection of pre-built, configurable UI components designed for use in Fluent Web Apps. Unlike standard UI components, these components are specifically built to interact natively with the Fluent Platform. We'll explore the various categories of components within the library, including Foundation, Content, Layout, Interaction, and Field Components, and understand their distinct roles in building user interfaces.- Fluent Platform Integration: OMX Components seamlessly integrate with the Fluent Platform.
- Component Categories: The library includes Foundation, Content, Layout, Interaction, and Field Components, each with distinct roles.
- Component Hierarchy: Content and Layout components are typically children of Foundation Components.
- Mobile Responsiveness: Components should be designed with mobile responsiveness in mind.
- Interaction Components: These enable user interaction with the application.
- Field Components: Automatically rendered form elements, essential for complex workflow input, are not configured via the manifest.
Unit Testing Custom Components
Essential knowledgeThis lesson covers the process of unit testing custom components using the tools provided within the Component SDK: Jest and React's test renderer. We'll walk through the steps of creating mock objects for dependencies (authentication, data, attributes), arranging the test environment, acting by rendering the component with the mocks, and asserting the output using snapshot testing. This process ensures the reliability and correctness of your custom components.- Testing Framework: The SDK includes Jest and React's test renderer for unit testing.
- Mock Objects: Mock objects are created for external dependencies like authentication (
`useAuth`), data from the page query, and dynamic attributes from the manifest. - Arrange, Act, Assert: The testing process follows the standard Arrange, Act, Assert pattern.
- Arrange: Mocks are set up and configured.
- Act: The component is rendered with the mock data.
- Assert: The rendered output is compared against a snapshot.
- Snapshot Testing: Jest's snapshot feature is used to compare the component's output to a previously saved snapshot, ensuring consistency.
- Testable Components: Unit tests help ensure the reliability and maintainability of custom components.
Enhance Your Custom Fields: Leveraging Existing Components from the Registry
Essential knowledgeThis lesson details how to enhance custom form fields by adding structure, styling, and interactive controls. We'll focus on improving the user experience and data capture capabilities of our custom field component. This involves using Material-UI for styling, organizing the field's layout, and integrating pre-built form controls from the component library, such as the `QuantitySelector`. We'll also cover best practices like using the `useEffect` hook for debugging.- Structure and Layout: Learn how to structure and organize the elements within your custom form field for optimal presentation.
- Styling with Material-UI: Use Material-UI's styling capabilities (e.g., makeStyles) to style your custom field and maintain design consistency.
- Form Control Integration: Integrate pre-built form controls, like the QuantitySelector, to efficiently capture specific data types (e.g., integers for quantity).
- Component Registry Retrieval: Learn how to retrieve and use existing components from the component registry (e.g., the QuantitySelector using its alias "number").
- State Management: Manage the state of form inputs using React's state mechanisms.
- Debugging with
`useEffect`: Use the `useEffect` hook to debug and verify the behavior and output of your custom field.
Accessing User and Location Context with the useAuth Hook
Essential knowledgeThis lesson explores the `useAuth` hook provided by the Component SDK, which grants access to crucial information about the currently logged-in user. We'll learn how to retrieve user details, including roles/permissions and the current location/retailer context. Specifically for location-context web apps like Fluent Store, we'll focus on using this hook to access the currently selected store's information, such as longitude and latitude coordinates, which will be essential for our map implementation.`useAuth` Hook Purpose: The useAuth hook provides a convenient way to access details about the authenticated user, including their roles, permissions, and current context.- Contextual Information: The hook provides access to the user's current location or retailer context, which is vital for location-based applications.
- Location Coordinates: For location-context apps, useAuth allows retrieval of the selected store's coordinates (longitude and latitude), enabling map integration and location-based functionality.
- Fluent Store Application: In the context of Fluent Store, this hook will be used to get the coordinates of the currently viewed store, providing the data needed to display the store's location on the map.
Building Custom Components with the Component SDK
Essential knowledgeThis lesson dives into the practical application of the Component SDK, focusing on how to build custom components for OMX Web Apps. We'll explore the different types of custom components you can create, the powerful hooks available for interacting with the Fluent platform, and the utility components that streamline development and ensure consistency. We'll also touch on the crucial concept of component registries.- Types of Custom Components: The Component SDK enables the creation of custom view components (for page content) and custom field components (for workflow user actions), allowing developers to tailor interfaces to specific needs.
- Hooks for OMX Integration: Fluent-specific React hooks (e.g.,
`useAuth`, `useI18n`, `useQuery`) provide easy access to platform functionalities like authentication, localization, and API interaction, simplifying complex tasks. - Utility Components for Consistency: The SDK offers utility components (e.g., Card, Loading, Drawers) that serve as building blocks for custom components, ensuring a consistent look and feel, theme responsiveness, and mobile compatibility.
- Component Registries: Custom components must be registered with the appropriate registry (Component, Field, or Template) before they can be used in OMX Web Apps, making them discoverable and usable within the framework.
Creating Custom Template Helpers
Essential knowledgeThis lesson explores the creation and registration of custom template helpers within the Component SDK. Template helpers are powerful utilities that can be used within Manifest documents for tasks like styling, formatting, and calculations. We'll demonstrate how to create a custom template helper, in this case, one that bolds entity references, showcasing how to leverage the `TemplateRegistry` and its utility methods for generating formatted HTML.- Template Helpers: Template helpers are reusable functions that can be called within Manifest documents to perform various operations.
- Use Cases: Template helpers can be used for styling, formatting, calculations, and other data transformations.
`TemplateRegistry`: The `TemplateRegistry` is used to register custom template helpers, making them available for use in Manifests.- HTML Formatting: The lesson demonstrates creating a template helper that bolds entity references using
`TemplateRegistry` utility methods for formatted HTML generation. - Customizability: Custom template helpers extend the functionality of Manifests, allowing for greater flexibility and control over data presentation.
Extending Forms with Custom Field Components
Essential knowledgeThis lesson introduces the concept of custom form fields within the UX Framework. While standard form fields are automatically generated based on data types, developers can create custom field components to handle more complex data structures or enhance the user experience for specific scenarios, such as workflow user actions, GraphQL mutations, and list filters. In our client scenario, we'll focus on building a custom form field to capture stock reservation details, which requires a JSON object containing `locationRef` and `quantity`.- Form Field Generation: The UX Framework automatically generates forms based on expected data types.
- Custom Field Components: Developers can create custom field components to handle complex data types or improve UX.
- Extending Scenarios: Custom field components can be used with workflow user actions, GraphQL mutations, and list filters.
- JSON Data Capture: This lesson's focus is on creating a custom field component to capture a JSON object for stock reservation details, containing locationRef and quantity fields.
- Client Scenario: The need for a custom form field arises from the client's requirement to capture stock reservations, which involves a specific JSON structure.
Orchestration Engine
Essential knowledgeThe Orchestration Engine powers the execution of workflows, business logic, and business processes. It enables real-time sync for orchestrated availability calls, high-volume batch processing for inventory loads and updates, event tracking which logs all activities, responds to events triggering execution, and triggers activity in external systems.- Orchestration Engine
- Powers the execution of workflows, business logic, and business processes.
- Enables real-time sync for orchestrated availability calls, high-volume batch processing for inventory loads and updates, event tracking which logs all activities
- Responds to events triggering execution, and triggers activity in external systems.
Getting Started Configuring Fluent Big Inventory Web App
Essential knowledgeThe Fluent Big Inventory Web App is pre-configured with standard functions that provide the interface for managing products, inventory, feeds, and sources and serve as a starting point for your projects.The default UX templates are hosted on the platform, so you don't have to create the manifest settings unless you need to customize the existing baseline configuration.- The Fluent Big Inventory Web App comes with pre-configured standard functions, offering a user-friendly interface for effective management of products, inventory, feeds, and sources.
- Default UX templates are readily available on the platform, eliminating the need to create manifest settings unless customization of the existing baseline configuration is required, streamlining the setup process for a seamless user experience.
UX Framework Overview
Essential knowledgeThe OMX UX Framework, or Mystique, delivers configuration-based solution implementation for UIs (Web Apps) that understand the Fluent Platform. It enables UIs to react to changes within workflows and provides best-in-class user experience and design. Web apps can be built using code-free configuration, utilising a rich library of ready-to-use UI Components. Customising UIs to meet specific business requirements using Component SDKs is also possible. Configuration is managed in a JSON document called the OMX Web App Manifest.
- Dynamic user management experience.
- Configurable left-navigation menu items.
- Dynamic views, labels, and fields based on configuration and GraphQL queries.
- Dynamic and contextual user actions based on workflow configuration.
- Ability to create and edit all entities, including non-workflow entities.
- Customise UIs to meet specific business needs and processes.
- Ability to configure contextual actions based on roles and process states.
- Enables centralised management of orders, products, inventory, fulfillments, and locations.
Users Configuration Overview
Essential knowledgeOMS Webapp's Users List page allows users to efficiently search and view existing users using a versatile filter component. The Users table provides essential user details, with a clickable Username link leading to a detailed User Details page displaying user information. The paging control at the bottom ensures easy entry management with customizable rows per page and intuitive navigation.`Type`: Understand the different types of users; ADMIN, RETAILER, API, and AGENT- User Status: Be aware of the user status options, ACTIVE and INACTIVE, which reflect the user's current accessibility.
- Filtering Users: Utilize the filter component to efficiently search for users based on various criteria like username, status, creation date, and type.
- Roles and Permissions: Assign roles to users to manage permissions within the system, ensuring each user has the appropriate level of access.
- Paging Control: Utilize the paging controls at the bottom of the Users table to navigate between pages and manage the number of entries displayed per page, with options for 10, 25, or 100 entries.
- Deprecation Notice: Be aware that certain user types such as AGENT, SUPPORT, and others have been deprecated and should not be used for new users.
Escaping / unescaping of values in UX Framework
Essential knowledgeCharacter escaping and unescaping are crucial for data integrity and security in UX frameworks. This document focuses on the Mustache.js templating engine, which escapes HTML by default to prevent XSS attacks. When special characters like ampersands need to be displayed, the framework offers unescaping methods to ensure correct and secure rendering.This overview highlights the significance of proper value escaping and the techniques for accurately rendering special characters within the UX framework.- Mustache.js Templating: The UX framework utilizes mustache.js for templating, which automatically escapes HTML characters. This is important for preventing XSS (Cross-Site Scripting) attacks and ensuring data is displayed as intended.
- Unescaping Variables: To display special characters properly, such as ampersands, you must unescape variables using triple mustaches, e.g.,
`{{{variable}}}`, or the `&` symbol in the variable tag, e.g., `{{&variable}}`. - Correct Display of Values: Escaping or unescaping variables correctly is crucial for the accurate representation of data within the UX. This ensures that special characters are rendered as intended, maintaining the integrity of the information displayed to users.
