WebUI JSON

Important

The information below applies to AIMMS versions starting from 4.67 onwards.

In older AIMMS versions up to 4.66, the WebUI pages and widgets were stored by the WebUI Server in the pages and widgets sub-folders of the WebUI folder, respectively.

AIMMS WebUI uses JSON (see https://www.json.org/json-en.html) as the format to store the specification of your WebUI. JSON is a commonly used, text-based format for representing structured data. The webui.json file holds the complete specification of your WebUI app — including all pages, their layout, and the widgets placed on them.

Note

Before AIMMS 4.67, the WebUI specification was spread across multiple files in separate pages, widgets, and application sub-folders. This made it harder to get a complete picture of your app, and diffs in version control were noisy and difficult to interpret.

webui.json was introduced to consolidate the entire WebUI specification into a single, human-readable file. This makes it straightforward to:

  • See the full structure of your app in one place.

  • Track changes in version control with clean, meaningful diffs.

  • Resolve merge conflicts more easily.

  • Move or share a WebUI app as a single self-contained file.

The webui.json file is automatically created and maintained by AIMMS WebUI. You should never need to edit it manually.

File Location

Where the webui.json file is created depends on where the WebUI components (pages and widgets) are defined:

Main project

The webui.json file for the main project is located at:

<YourProject>/MainProject/WebUI/webui.json

This file is created automatically the first time you open or start WebUI for your project. It contains all pages and widgets that belong to the main project.

Libraries (Pages in Library feature)

When the Pages In Library Support feature is used and WebUI pages are added to a library, a separate webui.json file is automatically created inside the library’s WebUI subfolder:

<LibraryFolder>/WebUI/webui.json

Note

  • The Pages in Library feature requires WebUI Library version 25.3 or later, and AIMMS version 25.4 or later.

  • Each library with WebUI pages has its own webui.json, scoped exclusively to the pages and widgets of that library. This keeps library content self-contained and portable across projects.

How the File Is Created and Updated

The webui.json file is created and updated automatically by AIMMS WebUI — you do not need to manage it yourself:

  • Main project (new projects) — For a project created with AIMMS 4.67 or later, webui.json is created automatically the first time WebUI is started. All pages and widgets you add are written directly to this file.

  • Main project (existing projects) — For a project that was previously built with AIMMS 4.66 or earlier (using the old pages, widgets, and application folder structure), webui.json is automatically generated the first time the project is opened with AIMMS 4.67 or later. Only pages and widgets that are actively referenced in the WebUI Page Manager are included in the generated file. The old folders are not deleted, so the project can still be opened with older AIMMS versions if needed.

  • Libraries — When you add a WebUI page to a library via the Application Manager, a webui.json file is automatically created in the library’s WebUI subfolder (if one does not already exist). Each subsequent page or widget addition is recorded in that file.

  • Ongoing changes — Whenever you make a change to a page or widget (in either the main project or a library), AIMMS WebUI automatically writes the updated specification to the appropriate webui.json file.

If you make changes using an older AIMMS version (4.66 or lower), you may delete the webui.json file. It will be re-generated automatically the next time the project is opened with AIMMS 4.67 or later. However, changes made with AIMMS 4.67 or later are never reflected back in the old format.

File Structure Overview

The webui.json file is a single JSON object whose top-level keys fall into four categories:

Application application

A single object that holds all application-level settings. It contains:

  • App-level options — settings such as ui.editable (controls whether the WebUI UI can be edited by the end user), menu.hidden, widget.visibility.greyout, defaults.upload.download.controls.show, and timezone display settings.

  • Workflow configuration — workflows.information and workflows.configuration reference AIMMS identifiers that define the workflow panels shown in the app.

  • Pages — a nested children tree that describes the full page hierarchy. Each entry has a name, a slug (used as the URL fragment and as the key in pages/* sections), a type (e.g. pagev2-grid, pagev2-grid-dialog, pagev2-grid-sidepanel), and a children array for sub-pages.

  • Browser bindings — references to AIMMS identifiers for browser language, name, and timezone (browser.language, browser.name, browser.timezone, ignoredst).

  • Theme — themes.current (references an AIMMS identifier) and theme.classic.

The page tree always has a root node, then a grouping node named after the component ("Main Project" for the main project, or the library name for library pages), followed by the actual pages.

Note

The slug of a page and the uri of a widget are their unique identity within the WebUI. These are used whenever you need to reference a page or widget elsewhere in the application — for example:

For pages and widgets belonging to a library, the slug is prefixed with the library’s namespace prefix (e.g. mylib::page1). See the note in the File Structure Overview section for details.

Pages pages/<slug>

One entry per page that has been configured (i.e. has at least one widget or setting). The key is pages/ followed by the page’s slug. Each entry may contain:

  • aimms.widget.type — the page type (pagev2-grid, pagev2-grid-dialog, pagev2-grid-sidepanel, etc.), indicating whether it is a regular page, a dialog page, or a side panel page.

  • layoutId — a reference to a built-in or custom layout.

  • widgets — an ordered list of widget URI references and their grid layout info (width and height).

  • bindings — the placement of each widget into a named grid area.

  • onload — an optional reference to an AIMMS procedure called when the page is opened.

  • pageleave — an optional reference to an AIMMS procedure called when the user navigates away from the page.

  • primarypageaction / secondarypageactions — references to AIMMS identifiers that configure the primary and secondary page action buttons.

  • sidepanels — a reference to an AIMMS identifier that configures the side panels shown on this page.

Custom layouts layouts/<id>

One entry per custom page layout defined in the application. Each entry has:

  • definition — the grid template (columns, rows, named areas) and the widget area configuration.

  • displayName — the human-readable name shown in the layout picker.

Built-in layouts (e.g. Layout2, Layout7) are not stored here; only custom layouts created by the app developer appear as layouts/* entries.

Widgets widgets/<name>

One entry per widget, keyed by the widget’s name/URI. Each entry describes the widget’s type, its data bindings (references to AIMMS identifiers), display options, and any other widget-specific settings.

Note

  • Custom layouts are scoped to where they are defined. A layouts/* entry is available only within the component (main project or library) in which it was created. Custom layouts defined in the main project cannot be used in library pages, and vice versa.

  • For a library’s webui.json, the structure is identical but the pages tree has a root node followed by a grouping node named after the library, and all pages/* and widgets/* entries are scoped to that library’s own content.

  • Library slugs are prefixed with the library prefix. The slugs of pages and widgets that belong to a library are prefixed with the library’s namespace prefix using the :: separator. For example, if the library prefix is mylib, a page named page1 will have the slug mylib::page1 and a widget named widgetA will have the slug mylib::widgetA. This ensures uniqueness across the application when the same name is used in multiple libraries or in the main project.

Version Control Recommendations

If you use version control for your AIMMS project:

  • Add the webui.json file(s) to version control — both MainProject/WebUI/webui.json and any <LibraryFolder>/WebUI/webui.json files.

  • Once you no longer need to support AIMMS 4.66 or lower, remove the old pages, widgets, and application folders from version control.

The JSON format makes the WebUI structure directly readable in a diff tool, simplifying merge conflict resolution and making it easy to search for where a specific widget is used.

Note

The entries in webui.json follow a deterministic ordering: pages/* fragments are written in ascending order of their name, followed by widgets/* fragments in ascending order of their name. This predictable ordering keeps diffs minimal and makes merge conflicts easier to resolve.

Warning

Since WebUI version 25.3.1, this ordering has been broken — entries may no longer appear in the expected ascending order. We are aware of this issue and are working to resolve it.

Important

Even though webui.json is a standard JSON file, we strongly advise against editing its contents manually, as doing so can easily break parts of or your entire WebUI.