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 .
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 document.
The required convention for this setting name is: `fc.mystique.manifest.<appname>`
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 `ACCOUNT` context and contains a specific JSON structure.
OMX Web App URL Endpoint
Each Web App defined within the will have a unique URL, with the following convention: `https://<accountid>.sandbox.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
Updating the Manifest
The lives in an setting, so updates can be done in the same way other settings are update - either by looking it up in Console/settings and editing or on the API directly via Postman/Insomnia/other API client.
The name of the setting to update for a given app is prefixed with the `mystique` domain, followed by the name of the app. For example, a servicepoint would be set at:
`fc.mystique.manifest.servicepoint`
Currently, all settings must be populated at the level; however, there are several within the (e.g., roles, conditional components, etc) to change the look and behavior of a single app across different retailers or locations.
Partitioning the Manifest
The document can get pretty big, so it's possible to split a single into smaller fragment settings and manage each separately.
See Reference Routes below for more information on splitting routes into separate JSON documents.
Individual values in a may also be stored as API settings and referenced with a string prefixed with `setting:` followed by the setting name - similar to how you would use an i18n label.
For example, a page's data query's variables could be stored in a setting:
A `setting:` label may safely reference a setting that contains an `i18n:` label, but must not reference another `setting:` label - they cannot be nested.
App-level Configuration
Name
Type
Req
Description
Sample
`manifestVersion`
`string`
✅
The version of the Web App schema. At present, this should always be set to `2.0`.
`"manifestVersion": "2.0"`
`name`
`string`
✅
Name of the app used in logs and when filtering user actions.
`"name": "servicepoint"`
`icon`
`string`
❌
The icon is associated with this web app. See Icons for details.
`"icon": "FaLaptop"`
`title`
`string`
✅
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.
Enables us to rename 'servicepoint' to 'store' without changing all the workflows.
`'orchestrationAlias': 'servicepoint'`
`context`
`MystiqueManifestRole`
❌
The `level` property defines the context of this app. For example this could be either at a “retailer” (Fluent OMS) or “” (Fluent Store) level. If not provided it will default to the value
`{ "level": "retailer" }`
The `role` property can be optionally defined as either singular or an array of strings, which gives the ability to restrict access to users who have been granted a particular role. Users without access won't see those apps across the store in any selectors or dropdowns. For example in the Fluent Store , you could define the `STORE_ASSOCIATE` role as well as adding the relevant context to a particular user to give them access to the app.
The `switcher` property can be optionally defined, which allows for users to switch contexts from within the app. If this property is enabled and a user has multiple contexts at the same level, then a dropdown will appear on the top right of the app, allowing for navigation between contexts. The dropdown will contain 10 contexts, and the list is scrollable in case of additional contexts.
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, and the default value is 'left'.
`"header": {`
` "desktop": [`
` {`
` "position": "left",`
` "component": "fc.mystique.collapsible.text",`
` "props": {`
` "text": "text",`
` "charCutoff": 100`
` }`
` }`
` ],`
` "mobile": [`
` {`
` "position": "center",`
` "component": "fc.mystique.collapsible.text",`
` "props": {`
` "text": "text",`
` "charCutoff": 100`
` }`
` }`
` ]`
`}`
`headerProperties`
For more details on how to configure the headerProperties checkout the how-to guide.
Allows a builder to configure extra header components between the icon/app name and the 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.
`[`
` {`
` "position": "center",`
` "component": "fc.mystique.collapsible.text",`
` "props":`
` {`
` "text": "text",`
` "charCutoff": 100`
` }`
` }`
`]`
Route-level Configuration
The "routes" section of the is where you define the pages of your app and what content to present on them.
Routes is an array of `MystiqueRoutes`, which are one of "Page", "Section", or "Reference" (see below), and other fields depending on that type.
Page Routes
Name
Type
Req
Description
Sample
`type`
`page`
✅
Defines this route as a page.
`"type": "page"`
`path`
`string`
✅
The URL for this page.
This URL can optionally include parameters, which may then be used in the query and/or page components.
Parameters are denoted with a colon, for example, when visiting a page with a path of `/orders/:id` as `/orders/123`, the value `id = 123` would be available to be used in the page query to retrieve the corresponding .
`"path": "/orders/:id"`
`fullScreen`
`boolean`
❌
Determines if the left side navigation is shown on pages within the route
The default value is `false`
`"fullScreen": true`
`nav`
`MystiqueNavConfig`
❌
Optional configuration for this page in the navigation page.
If there is no nav defined for a given page, it won't appear in the sidebar but will still be accessible via URL. This is common for pages that require parameters, such as the individual page `/order/123`.
`label` is user-facing and should use a translatable i18n key.
If present, users must have at least one of the roles defined in the context of the app (retailer or ) to be able to access the page.
Specifically, on failed role check, the page will disappear from nav and show 404 if directly navigated via the URL.
`"roles": ["ORDER_ADMIN", "CUSTOMER_SERVICE"]`
`component`
`string`
✅
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.
`"component": "fc.page"`
`data`
`GQLQuery`
❌
If present, the defined query will be executed before rendering the page, and the resulting data will be made available to the page and it's descendants.
Query variables are template strings, and can:
access the user's login context information, to filter queries to only those items relevant to the current users retailer or location. Available fields are:
activeUser
username
attributes
activeRetailer (for retailer-level apps)
id
ref
activeLocation (for location-level apps)
id
ref
primaryAddress
longitude
latitude
access URL parameters (e.g. on page "/order/:id" you can reference "{{params.id}}")
use other template helpers (e.g. data manipulation to generate timeframes for dashboards etc)
Note: template strings will always produce a string value, and there are some cases where requires a non-string variable.
For such cases, you can tell to parse the value using `JSON.parse` by providing an object following the second code example.
The fragment is a cut-down version of a full , 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 . The fragment may also define additional default settings to be used by the .
The fragment should simply define the `manifestVersion`, a `routes` array, and an optional `settings` array.
Name
Type
Req
Description
Sample
`manifestVersion`
`string`
✅
Version of the schema. At present, this should always be set to `2.0`.
`"manifestVersion": "2.0"`
`routes`
`MystiqueRoute[]`
✅
The pages available in this app (see [Route-level Configuration][7]).
`settings`
`ApiSetting[]`
❌
Default settings values which are used out of the box. It is recommended to place default settings which are referenced by multiple pages, under the top-level 's default settings key.
Note that if multiple fragments define the same default setting key, the last fragment will determine the value - later setting definitions overwrite previous ones.
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.
`"dataSource": "orderById.customer"`
`descendants`
`MystiqueComponentInstance[]`
❌
Some components allow nesting of other components within them, e.g., the `fc.tabs` component uses its descendants to represent the content displayed in each tab.
If present, users must have at least one of the roles defined in the app's context (retailer or ) to see this component.
If not, the component will simply not appear on the page.
`"roles": ["ORDER_ADMIN", "CUSTOMER_SERVICE"]`
Local Development Options
When developing locally, we provide a number of overrides so you can easily control the manifests and fragments being loaded.
This can let you test changes quickly without uploading to your or store multiple versions of the same web app on an 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 document defining an app. If set, OMX will load this regardless of the app name in the URL. Any fragment references in the 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 . Any fragment references in the will be resolved from the API as normal. For example, you may have a development version of the Store app in a setting called `example.manifest.store.dev`
What's next?
The next knowledge you would like to know is the Page Component.