Update WebUI to Newer AIMMS Version

AIMMS WebUI has evolved over the years based on new insights and customer demands. As a result, UIs developed using older versions of AIMMS need to be adapted to work with modern versions of AIMMS.

This article covers changes in functionality of AIMMS WebUI and how to convert your UI to adapt to use these changes in your applications.

Before you start

Save a copy of your project before you start upgrading. A good practice is using a source code management (version control) system.

Determining the version of AIMMS

To know which changes may affect your project, check which version of AIMMS it is based on.

Every AIMMS 4 project contains a .aimms file in the root folder. For example:

1<?xml version="1.0"?>
2<References AIMMS_Version="4.39.2.1069 (x64)">
3    <MainProject Path="MainProject" />
4    <Library System="true" Path="AimmsPro" />
5    <Library System="true" Path="AimmsWebUI" />
6</References>

On line 2, the AIMMS version is refreshed when a change is made to the model text or the WinUI page manager. When the AIMMS App Launcher is installed, double-click this file to open AIMMS 4.39 (or the latest AIMMS version if it is not installed).

Note

Changing the WebUI alone does not update the version for the project. To otherwise trigger this update, you can make a small change to the model text whenever you are upgrading your project UI to a newer version of AIMMS. For example, add (or remove) a space to MainTermination when using a newer version of AIMMS on a project.

Adapting for WebUI changes

Now we will discuss features removed from WebUI, and how to adapt those features when using later AIMMS versions.

The versions listed below are the earliest versions to require the specified adaptation.

Download examples are available in each section below.

AIMMS 4.17: Sets in selection widget

AIMMS 4.16 is the last version where selection widget could contain AIMMS sets as contents (and pressing select all in the selection widget):

../../_images/Aimms416FilteringUsingSetInSelectionWidget.png

With AIMMS 4.17, you will need to add a zero one parameter, for instance something like:

1Parameter p01_Selector {
2    IndexDomain: sn;
3    Range: binary;
4}

Initializing this parameter in MainInitialization is advised, for instance as:

1p01_Selector(sn) := 0 ;

And then specifying such a parameter in the contents (and pressing select all in the selection widget).

../../_images/Aimms417FilteringUsingSetInSelectionWidget.png

Downloads:

AIMMS 4.20: Starting browser

AIMMS 4.19 is the last version of AIMMS where the model developer had to manually start the browser using something like: localhost:12001/Aimms-WebUI/home.

With AIMMS 4.20 onwards, starting the WebUI browser would start the browser directly.

True, no change is made to the project, but it did change the interaction of the model developer.

AIMMS 4.40: WebUI folder position

AIMMS 4.39 is the last version of AIMMS where the WebUI folder was located as a sub-folder of the project folder. AIMMS 4.40, the WebUI is a sub-folder of the folder MainProject.

../../_images/MoveWebUIFolder.png

When you are using a source code management system, you will want to remove the WebUI folder from the repository before the upgrade and add the folder MainProject\WebUI afterwards

Downloads:

AIMMS 4.46: Element Text

See also presentation of element names

The names of elements in a table can be displayed with more elaborate names; for instance, when initials of people are used in a set, but you want to see in the tables their actual names.

AIMMS 4.45 is the last version of AIMMS that supports the javascript identifier ElementTextMap often found in files with names such as elementText.js or element-text-map.js in the folder .\MainProject\WebUI\resources\javascript\.

Such a file looks like:

1ElementTextMap = {
2     "i_sn" : "sp_elaborateNames",
3};

For every data line, on the left we see the name of an index, here i_sn, and on the right we see the name of a string parameter, here sp_elaborateNames. To convert such a line, we open the set that is the range of the index, here s_someElements, and specify the string parameter as annotation webui::ElementTextIdentifier. The declaration of the set becomes:

1Set s_someElements {
2    Index: i_sn;
3    webui::ElementTextIdentifier: sp_elaborateNames;
4}

Once this conversion is complete, I recommend to remove the corresponding .js from your project; some file transfer mechanisms don’t approve of .js files in folders or .zip files.

Downloads:

AIMMS 4.50: Annotations

Data-dependent styling uses annotations identifiers.

Up to and including AIMMS 4.49, the annotation identifier associated with identifier X, needed to be called X_annotations. From AIMMS 4.50 onwards, the annotation identifier associated with identifier X can be specified using the annotation attribute webui::AnnotationsIdentifier. This permits the reuse of a single annotations identifiers by multiple other identifiers and more freedom in naming identifiers.

In our example, we use in AIMMS 4.49:

1Parameter p_associatedValues {
2    IndexDomain: i_sn;
3}
4StringParameter p_associatedValues_annotations {
5    IndexDomain: i_sn;
6}

In AIMMS 4.50 we can use:

1Parameter p_associatedValues {
2    IndexDomain: i_sn;
3    webui::AnnotationsIdentifier: sp_associatedValuesAnnotations;
4}
5StringParameter sp_associatedValuesAnnotations {
6    IndexDomain: i_sn;
7}

Not only did we add an annotation to the declaration of p_associatedValues, but we also took the opportunity to change the name of the annotations identifier, such that it could adhere to our naming conventions.

Downloads:

AIMMS 4.61: Map V2

The map widget was replaced with a new map widget in AIMMS 4.61. The map v1 widget was available up to AIMMS 4.60.

In our example we use the following declarations:

 1Set s_Customers {
 2    Index: i_Customer, i_CustomerFrom, i_CustomerTo;
 3}
 4Set s_LatLon {
 5    Index: i_LatLon;
 6    Definition: data { Latitude, Longitude };
 7}
 8Parameter p_Coords {
 9    IndexDomain: (i_Customer,i_LatLon);
10}
11Parameter p01_TravelArc {
12    IndexDomain: (i_CustomerFrom, i_CustomerTo);
13    Range: binary;
14}

Where the widget looks as follows, including its specification:

../../_images/mapv1.png

To obtain the above image, we:

  1. Specify a two-dimensional parameter, whereby the second dimension is over a set with two elements, p_Coords in the example.

  2. Specify the first index as the node index, i_Customer.

  3. Add a layer for points.

  4. Add a layer for arcs, with contents: p01_TravelArc.

To obtain an equivalent map v2 arc, we:

../../_images/mapv2.png

Using the following steps:

  1. Create two one-dimensional parameters over the node set for the latitude and longitude respectively, for instance as follows:

    1Parameter p_Latitude {
2    IndexDomain: i_Customer;
3    Definition: p_Coords(i_Customer, 'Latitude');
4}
5Parameter p_Longitude {
6    IndexDomain: i_Customer;
7    Definition: p_Coords(i_Customer, 'Longitude');
8}

  2. Create a new widget of the same size, of type map

  3. In this new widget, we add a node set, with specification

    • index: : i_Customer

    • Latitude : p_Latitude(i_Customer)

    • Longitude : p_Longitude(i_Customer)

  4. Next, we add an arc set as follows:

    ../../_images/mapv2arcset.png

Some advantages of map V2 widgets over map v1 widgets are:

  • Support for multiple node sets

  • Support for multiple arc sets

  • Zooming and center control

Downloads:

AIMMS 4.66: Widget filtering

../../_images/Aimms465Filter.png

Open project in AIMMS 4.66, Open WebUI, and accept new theme!

Declare a set for the filtering, including a new index:

1Set s_VisibleElements {
2    SubsetOf: s_someElements;
3    Index: i_ve;
4    Definition: {
5        { i_sn | p01_visibleElements( i_sn ) }
6    }
7}

Next, we open the identifier attributes of the identifiers in the table, and filter by specifying the use of i_ve in the Identifier settings > Set slicing per index:

../../_images/Aimms466Slicing.png

Downloads:

AIMMS 4.67: Serialize WebUI specification with a single file

Up to AIMMS 4.66, the essence of the WebUI is serialized in three folders:

  • application

  • pages

  • widgets

The resources used by the WebUI are serialized in the folder resources.

A WebUI folder thus had the following structure:

../../_images/Aimms466WebUIFolderStructure.png

The three folders forming the essence of the WebUI are replaced by a single file, named webui.json This lead to the following folder structure.

../../_images/Aimms467WebUIFolderStructure.png

The three folders are no longer used.

When using source code management (version control)

When you are using a source code management system, you should remove the three folders from your source and add the file webui.json.

Downloads:

AIMMS 4.71: Identifier based tailoring

In AIMMS 4.70 Identifier based tailoring of the identifier X to:

  1. Specify read-only elements, was done via the identifier X_flags. In AIMMS 4.72 the annotation webui::FlagsIdentifier is used. Note that in the example provided, you cannot change the value for Annet, because the read-only flag is set.

  2. X_tooltips –> webui::TooltipIdentifier

  3. X_text –> ? webui::ItemTextIdentifier, not demoed here, requires Gantt Chart.

In the following image use is made of a flag and a tooltip identifier.

../../_images/AIMMS470ReadOnlyToolTip.png

The flag identifier sets the data for p_associatedValues('a') to readonly, and tooltip for p_associatedValues('a') is "wears facemask". The difference between AIMMS 4.70 and AIMMS 4.71 is the selection of identifier where this is specified.

  1. In AIMMS 4.70, the flag and tooltip identifier are associated by name: for an identifier named p_associatedValues, the

    1. Flag identifier must be named p_associatedValues_flags

    2. Tooltip identifier must be named p_associatedValues_tooltips

    3. Text in Gantt Chart bar, the identifier must be named p_associatedValues_text. This is not illustrated here.

  2. In AIMMS 4.71, the flag and tooltip identifier are associated by annotation: for an identifier named p_associatedValues, the

    1. Flag identifier is specified in the annotation webui::FlagsIdentifier

    2. Tooltip identifier is specified in the annotation webui::TooltipIdentifier

    3. Text in Gantt Chart bar, the identifier is specified in the annotation webui::ItemTextIdentifier. This is not illustrated here.

When you open the AIMMS 4.70 project in AIMMS 4.71 you will get warnings like the following:

../../_images/Aimms471Warnings.png

You can easily adapt your application by specifying the annotations, highlighted below:

1Parameter p_associatedValues {
2    IndexDomain: i_sn;
3    webui::AnnotationsIdentifier: sp_associatedValuesAnnotations;
4    webui::FlagsIdentifier: p_associatedValues_flags;
5    webui::TooltipIdentifier: p_associatedValues_tooltips;
6}

After this edit, the behavior of the application does not change; but the warnings disappeared after a restart.

Downloads:

AIMMS 4.72: Data modifications

In AIMMS 4.71, the procedure associated with changes in the data of p_associatedValues must be named uponchange_p_associatedValues. In AIMMS 4.72, you can select a procedure via an annotation.

We use the following simple procedure here that just displays the data in the listing file:

1Procedure uponchange_p_associatedValues {
2    Body: {
3        display p_associatedValues ;
4    }
5}

In AIMMS 4.72, the procedure is linked using the annotation:

1Parameter p_associatedValues {
2    IndexDomain: i_sn;
3    webui::AnnotationsIdentifier: sp_associatedValuesAnnotations;
4    webui::FlagsIdentifier: p_associatedValues_flags;
5    webui::TooltipIdentifier: p_associatedValues_tooltips;
6    webui::UponChangeProcedure: uponchange_p_associatedValues;
7}

Downloads: