The 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.
Key points
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.
Introduction to the OMX Web App Manifest document
Each Web App in the Fluent Platform will have a setting to hold the Web App Manifest document.The required convention for this setting name is: `fc.mystique.manifest.<appname>`The manifest document can get pretty big, so it's possible to split a single manifest into smaller fragment settings and manage each separately.See Reference Routes below for more information on splitting routes into separate JSON documents.
Note
`mystique` is a short-hand codename for the OMX UX Framework
For example, the Fluent Commerce UIs have the following settings:
`fc.mystique.manifest.oms`
`fc.mystique.manifest.store`
The setting is configured in the `ACCOUNT` context and contains a specific JSON structure.
OMX Web App URL Endpoint
Each Web App in the account will have a unique URL in the following format: `https://<account>.<environment>.apps.fluentcommerce.com/<appname>`.Notice how the `<appname>` in the setting matches the URL path.
Web App Manifest Guide
In this section:
App-Level Configuration
Route-Level Configuration
Page Routes
Section Routes
Reference Routes
Local Development Options
App-level Configuration
Name
Type
Required
Description
manifestVersion
`string`
Yes
The version of the Web App Manifest schema. At present, this should always be set to `2.0`.
name
`string`
Yes
Name of the app used in logs and when filtering user actions.
title
`string`
Yes
Name of the app used in visible locations (app header, browser title bar, etc). Since this is end-user visible, it should be translated via i18n.
homePath
`string`
Yes
The initial page to load on login, or whenever no other page is referenced in the URL.
icon
`string`
No
The icon associated with this web app. See Icons for details.
orchestrationAlias
`string`
No
Enables us to rename 'servicepoint' to 'store' without changing all the workflows.
context
`MystiqueManifestRole`
No
Defines the application context, access restrictions, and context-switching behavior. The configuration specifies the context level (`account`, `retailer`, or `location`), optional roles required to access the application, and whether users can switch between available contexts.
plugins
`MystiquePluginSetting` | `MystiquePluginURL`
No
Defines the Component SDK plugins to load while rendering this app.
routes
`MystiqueRoute[]`
Yes
The pages available in this app (see [Route-level Configuration][7]).
settings
`{defaults: ApiSetting[]}`
No
Default settings values that are used out of the box.
header
`MystiqueHeader`
No
Components can be added for both mobile and desktop views, appearing between the app name and context name. Accepts standard `MystiqueComponentInstance` properties.In addition to the standard array of properties, the `position` property determines the component's position and can have values of "left", "right", "center" or "centre". This is an optional property with a default value of `left`.
MystiquePluginSetting
Name
Type
Required
Description
type
`setting`
Yes
Type of plugin.
setting
`string`
Yes
Name of the setting.
MystiquePluginURL
Name
Type
Required
Description
type
`url`
Yes
Type of plugin
src
`string`
Yes
URL or path from which the plugin bundle is loaded.
ApiSetting
Name
Type
Required
Description
name
`string`
Yes
Name of default setting.
value
`any`
Yes
Value of default setting.
MystiqueHeader
For more details on how to configure headerProperties, check out the how-to guide.
Allows a builder to configure extra header components between the icon/app name and the location selector/user menu shown on desktop screen dimensions.`position` allows the builder to specify (`left, right, centre/center`), which determines where the component is placed on the header.
Allows a builder to configure extra header components between the icon/app name and the location selector/user menu shown on mobile screen dimensions. `position` allows the builder to specify (`left, right, centre/center`), which determines where the component is placed on the header.
MystiqueManifestRole
Name
Type
Required
Description
level
`account | retailer | location`
Yes
The `level` property defines the app's context. For example, this could be either at a “retailer” (Fluent OMS) or “location” (Fluent Store) level.If not provided, it will default to the value`{ "level": "retailer" }`
role
`string| string[]`
No
The `role` property can be optionally defined as either a single role or an array of roles. Users must have at least one of the specified roles within the configured context to access the application. Users without the required role will not see the application in navigation, application selectors, or context switchers and cannot access it directly.
switcher
`boolean`
No
The `switcher` property can be optionally defined, allowing users to switch contexts within the app. If this property is enabled and a user has multiple contexts at the same level, a dropdown will appear in the top-right of the app, allowing navigation between contexts. The dropdown will contain 10 contexts, and the list will be scrollable for additional contexts.
The "routes" section of the manifest defines the pages of your app and the content to present on them.Routes is an array of `MystiqueRoutes`, which are either "Page", "Section", or "Reference" (see below), along with other fields depending on that type.
MystiquePage
Name
Type
Req
Description
type
`page`
Yes
Defines this route as a page.
path
`string`
Yes
The URL for this page. This URL can optionally include parameters, which may then be used in the GraphQL query and/or page components. Parameters are denoted with a colon. For example, when visiting a page with a path of `/orders/:id`, such as `/orders/123`, the value `id = 123` would be available in the page query to retrieve the corresponding Order.
fullScreen
`boolean`
No
Determines if the left side navigation is shown on pages within the route. The default value is `false`.
nav
`MystiqueNavConfig`
No
Details for configuring the Nav bar properties are provided in the table below.
roles
`string[]`
No
If present, users must have at least one of the specified roles within the application context to access the page.Restricted pages are hidden from navigation and return a 404 response when accessed directly via URL.Note: At the application level, access is configured using the `context.role` property. At the page and section level, access is configured using the `roles` property.
component
`string`
Yes
Name of the component to be used to render this page. Typically, `fc.page`, but any registered component can be used, so long as it's designed to fill a screen.
data
`GQLQuery`
No
If present, the specified GraphQL query is executed before the page is rendered, and the resulting data is made available to the page and its descendants.
Query variables support template expressions and can reference:
• User context information (`activeUser`, `username`, `attributes`) • Retailer context (`activeRetailer.id`, `activeRetailer.ref`) for retailer-level applications • Location context (`activeLocation.id`, `activeLocation.ref`, `activeLocation.primaryAddress`, `activeLocation.longitude`, `activeLocation.latitude`) for location-level applications • URL parameters (for example, `{{params.id}}` on a route such as `/orders/:id`) • Other supported template helpers
Template expressions always resolve to strings. When a GraphQL variable requires a non-string value, set `parse: true` to apply `JSON.parse` before the query is executed.
props
`MystiquePageProps`
No
The component props should be passed to the page component. These will differ depending on the component, so refer to the individual component documentation for more details.
descendants
`MystiqueComponentInstance[]`
No
The components to display on the page. Refer to individual component documentation for more details.
MystiqueNavConfig
Name
Type
Required
Description
label
`string`
Yes
The label is the user-facing text that defines the page name and should use a translatable i18n key.
icon
`string`
Yes
The icon is displayed in the page's nav bar.
badge
`BadgeProperties`
No
Badges are configured to show a number of outstanding items for a particular page.Badge properties are defined in the table below. Note: Badges are limited to 999 outstanding items. After 999 results are returned, then 999+ will be shown to the user.
Badge Properties
Name
Type
Required
Description
queryName
`string`
Yes
Takes a named GraphQL Schema query. This is used to retrieve a count of outstanding items from the GraphQL query.
variables
`key/value map`
No
Takes properties that are available in the query to filter data.
thresholds
`ThresholdsProperties`
No
Define the badge and number colors using low and high thresholds to indicate the severity of outstanding items.Note: If the `thresholds` object is removed, the badge color is always purple. Threshold properties are defined in the table below.
Thresholds Properties
Name
Type
Required
Description
thresholdLow
`number`
Yes
If results are below this threshold, then the badge will be green.
thresholdHigh
`number`
Yes
If the results exceed this threshold, the badge will be red. When results are between `thresholdLow` and `thresholdHigh` the badge will be orange.
1{2"routes":[3{4"type":"page",5"path":"orders",6"component":"fc.page",7"fullScreen":true,8"nav":{9"label":"i18n:fc.om.orders.index.nav",10"icon":"library_books",11"badge":{12"queryName":"orders",13"variables":{14"status":[15"ACTIVE"16]17},18"thresholds":{19"thresholdHigh":5,20"thresholdLow":321}22}23},24"roles":[25"ORDER_ADMIN",26"CUSTOMER_SERVICE"27],28"props":{29"title":"i18n:fc.om.orders.index.title",30"actions":true31},32"data":{33"query":"query($orders_first: Int) { orders(first: $orders_first) { edges { node { id type status items { edges { node { currency } } } createdOn } } } }",34"variables":{35"orders_first":10036}37},38"descendants":[39{40"component":"fc.list",41"props":{42}43}44]45}46]47}
Section Routes
A section is a group of pages that are nested under a single header in the nav sidebar.
MystiqueSection
Name
Type
Required
Description
type
`section`
Yes
Defines this route as a section.
nav
`MystiqueNavConfig`
Yes
Details for configuring the Nav bar properties are provided in the table MystiqueNavConfig.
roles
`string[]`
No
If present, users must have at least one of the specified roles within the application context to access the section.Restricted sections and all child pages are hidden from navigation and return a 404 response when accessed directly via URL.Note: Access to child pages does not override access restrictions defined on the parent section. If a user cannot access a section, none of its pages are accessible even if the page itself specifies a matching role.
pages
`MystiquePage[]`
Yes
Pages within this section, as defined in the page section above: Page Routes.
Section-level access restrictions take precedence over page-level restrictions. If a user does not have access to a section, none of its child pages will be visible or accessible, regardless of any roles configured on the individual pages.
Reference Routes
A reference route is a mechanism for partitioning the manifest into logically smaller JSON documents.To achieve this, include a "reference" type in the routes section of the manifest (instead of the usual "section" or "page" types) like so:
Name
Type
Required
Description
type
`reference`
Yes
Defines this route as a reference.
settingName
`string`
Yes
Defines the name of the Setting to load the manifest fragment
The fragment is a cut-down version of a full manifest, in that it defines additional sections and pages that will appear in the app navigation in the position where the reference was included in the original manifest. A fragment may also define default settings that are preloaded into the application cache and made available to the Manifest during runtime.
MystiqueManifestFragment
Name
Type
Required
Description
manifestVersion
`string`
Yes
Version of the MystiqueManifest schema. At present, this should always be set to `2.0`.
routes
`MystiqueSection[] | MystiquePage[]`
Yes
The pages available in this app (see Route-level Configuration).
settings
`FragmentSetting[]`
No
Defines settings that are preloaded into the application cache and can be used by the manifest during runtime.
FragmentSetting
Name
Type
Required
Description
name
`string`
Yes
Name of setting
value
`any`
Yes
Default value of the setting. This value is used when no value exists in the Settings service.
alias
`string`
No
An optional alias is used when referencing the setting value in queries or templates. This is useful when a setting value needs to be exposed as a variable within a query configuration.
Components within the page follow a consistent structure
MystiqueComponentInstance
Name
Type
Required
Description
component
`string`
Yes
Name of the component in the ComponentRegistry. Refer to component docs for specific examples.
props
`key/value map`
No
The component props to be passed into the component.These will differ depending on the component, so refer to the individual component documentation for more details.
dataSource
`string`
No
Select the subset of the page query that this component will use to render.This mostly just helps to shorten configuration in the props area so that each data reference doesn't have to write out the full path every time.
descendants
`MystiqueComponentInstance[]`
No
Some components allow nesting of other components within them, e.g., the `fc.tabs.card`component uses its descendants to represent the content displayed in each tab.
When developing locally, we provide several overrides so you can easily control which manifests and fragments are loaded.This lets you test manifest changes quickly without uploading to your account, or store multiple versions of the same web app on an account and swap between them.To use these options, you must set the `key` and `value` in your browser's localStorage using its developer tools. See the documentation for your preferred browser:
A Manifest document defining an app. If set, OMX will load this regardless of the app name in the URL. Any fragment references in the manifest will be resolved from the API as normal.
mystique.dev.overrides.manifestSettingName
`string`
A setting name. If set, OMX will query the setting API for this key and use its value as the app manifest. Any fragment references in the manifest will be resolved from the API as normal.For example, you may have a development version of the Store app in the `example.manifest.store.dev`setting.
What's next?
The next knowledge you would like to know is the Page Component.
