Aimms Pro 2.16.3.155 PDF

AIMMS PRO
2 Last update: 2017/07/18

AIMMS
Copyright AIMMS B.V.

Table of Contents
Introduction to the AIMMS PRO Platform............................................................................................. 2
Installation ............................................................................................................................................. 4
System Requirements ........................................................................................................................ 5
Installation and Configuration of the License Server........................................................................... 7
General Architecture .......................................................................................................................... 9
Installation of AIMMS PRO on Windows ........................................................................................... 12
Installation of AIMMS PRO on Linux ................................................................................................ 13
Installation of License Server on Linux ............................................................................................. 18
Instructions to install License Server together with AIMMS PRO ................................................. 21
Using the AIMMS PRO Configurator ................................................................................................ 24
Configuring the configurator........................................................................................................ 25
Various sections of the configurator ............................................................................................ 26
Connection configuration ....................................................................................................... 27
PRO configuration ................................................................................................................. 28
General settings ............................................................................................................... 29
Web configuration ............................................................................................................ 30
Worker profiles................................................................................................................. 31
Queue priority settings ..................................................................................................... 32
Queue rules ..................................................................................................................... 33
Ports to listen ................................................................................................................... 34
Configuration specific for separate nodes......................................................................... 35
Migration from AIMMS PRO 1.0.x .......................................................................................... 36
Start/stop services................................................................................................................. 37
Backup management ............................................................................................................. 38
Setting up an AIMMS PRO Cluster ................................................................................................... 41
Server-side Logging ......................................................................................................................... 44
Server Administration ......................................................................................................................... 46

AIMMS Application Management...................................................................................................... 47
AIMMS Version Management ........................................................................................................... 49
User Management............................................................................................................................ 50
Monitoring ........................................................................................................................................ 53
Configuration ................................................................................................................................... 54
AD Settings ................................................................................................................................ 55
Retention Settings ...................................................................................................................... 56
Portal Customization................................................................................................................... 57
Tunnels....................................................................................................................................... 59
Log Management ........................................................................................................................ 60
Linking Environments to Active Directory Domains........................................................................... 63
Link to Active Directory for AD Member Servers ......................................................................... 64
Link to Active Directory for Non-AD Member Servers .................................................................. 67
Tunneling support ............................................................................................................................ 73
General Design........................................................................................................................... 74
Tunnel configuration ................................................................................................................... 76
Security ...................................................................................................................................... 79
Changes to AIMMS model .......................................................................................................... 82
Known issues ............................................................................................................................. 84
General Remarks ............................................................................................................................. 85
Commonly Encountered Errors ........................................................................................................ 86
AIMMS PRO End-User Portal .............................................................................................................. 89

PRO Jobs ........................................................................................................................................ 90
Application Statistics ........................................................................................................................ 92
Project Setup ....................................................................................................................................... 93

Adding PRO Libraries to your Project ............................................................................................... 94
Basic AIMMS PRO Workflow............................................................................................................ 95
Conversion Guidelines ..................................................................................................................... 97
AIMMS PRO and Data Management ................................................................................................ 99
Advanced AIMMS PRO Workflows ................................................................................................. 103
Determining the Application State to Transfer ........................................................................... 104
Advanced Usage of pro::DelegateToServer .............................................................................. 107
Communication Between client-side and Server-side Sessions................................................. 112
Using Messages in Your PRO Applications ............................................................................... 115
The PRO Progress Window ...................................................................................................... 117
Debugging PRO-enabled Projects.................................................................................................. 119
AIMMS PRO API ................................................................................................................................. 123

AIMMS AIMMS PRO - 2
Introduction to the AIMMS PRO Platform

Why do you need AIMMS PRO?
The AIMMS PRO Platform is a new way for your organization to deploy optimization technology into your
organization. See it as your own App Store of AIMMS-based optimization solutions; a collaboration
platform for making better decisions. Every optimization solution (or update of such a solution) can be
made available to the users in your organization in a matter of a few clicks. As our solutions help your
users make better decisions, it will allow you to increase your bottom line (or reduce your cost) almost
instantly. This means that your organization will perform better and will be more agile with the AIMMS
PRO Platform.
What is AIMMS PRO?
The AIMMS Publishing and Remote Optimization Platform makes it possible to deploy AIMMS
Applications to end-users quickly and efficiently through the AIMMS PRO Portal. More importantly, the
AIMMS PRO Portal assures end-users can access the latest version of these AIMMS Applications at all
times through a web browser. While end-users can view and manage data, create scenarios, and initiate
optimization runs, the actual processing is dispatched automatically to (high performance) central
servers connected by the AIMMS PRO Platform. So, instead of coding your own interfaces, deployment
setups etc., AIMMS PRO does it all for you.
How to use AIMMS PRO?
The AIMMS PRO Portal is the control center for users of the AIMMS PRO Platform. It allows for
management of users, publishing of applications and AIMMS versions, setting use restrictions for
applications, etc. Whether you are a developer, an end-user, or an IT manager, the portal provides you
the controls to make optimal use of AIMMS possible. This is also true for sharing prototypes and pre-
releases in a controlled way. Thus scaling up a solution, sharing new optimization concepts, or offering a
large set of different AIMMS Applications to your organization, is now easier than ever before.
Some important characteristics of AIMMS PRO
We envision that the AIMMS PRO Platform will become your collaboration platform for true interactive
decision-making, leading to better decisions and, therefore, better bottom-line results. Our first release of
AIMMS PRO already provides you with a great set of features to start this collaboration and we will
continuously develop new features in the years to come.
The AIMMS PRO portal
The AIMMS PRO Portal provides a central control point for various users:
Page 2 of 123
AIMMS AIMMS PRO - 2
Developers can upload/manage/start applications

End-users can start AIMMS Applications through an Apps list
End-users can watch and interact with jobs that are running on the server
IT can upload/manage AIMMS versions
IT can manage users and user rights
IT can connect user management to Active Directory
IT can assign special publication rights to users
Statistics are available throughout the portal
Running apps from the AIMMS PRO Portal
By starting an application from AIMMS PRO in the AIMMS PRO client application, end-users can initiate
optimization runs on the server that are autoqueued and processed based on capacity and priority rules.
All licensing is arranged centrally with special AIMMS PRO licenses: AIMMS PRO Clients (required to
start Apps), and AIMMS PRO Server Sessions (required to execute optimization runs). The number of
PRO Clients and PRO Server Sessions can be extended to increase the reach and/or calculation power.
Page 3 of 123
AIMMS AIMMS PRO - 2
Installation
As AIMMS PRO will become a central resource in your organization; it is essential that both first time
installations and upgrades of AIMMS PRO are well planned, controlled, and successful. That is why we,
at AIMMS, are more than willing to assist in this process; please contact our support staff for first time
AIMMS PRO installations or upgrades of AIMMS PRO. In addition, please check that the system
requirements are met and that the AIMMS License server is installed.
You will also need to install the AIMMS License Server. After these steps, you may proceed with the
installation and the configuration.
Page 4 of 123
AIMMS AIMMS PRO - 2
System Requirements
AIMMS PRO comprises both server- and client-side components. In this section we will describe the
minimum server requirements for running AIMMS PRO, as well as requirements for desktop users
connecting to the AIMMS PRO Server through the AIMMS PRO client.
Minimum Server Requirements
The minimum server requirements for Windows Server are:
Windows Server 2008 64-bit, or Windows Server 2012 64-bit, up-to-date with latest security
patches
minimum of 4 cores
minimum of 16 GB RAM
500 GB available hard disk space
The minimum server requirements for Linux Server are:
Ubuntu 14.04 or Centos 6.6 with Docker Version 1.6.0 or higher

minimum of 4 cores
minimum of 16 GB RAM
500 GB available hard disk space
In assessing the actual server requirements, you have to take into account the anticipated number of
concurrent server sessions n, in which case n + 1 cores would be advisable. Similarly, the memory
requirements for the server are determined by the size of the data of the largest job running on the
server multiplied by the number of concurrent server sessions. Using AIMMS PRO over time may
accumulate application data in the PRO storage directory.
Client Requirements
The minimum client requirements are:
Windows 7 or higher, 32-bit (x86) or 64-bit (x64)

8 GB RAM, or, for apps deploying desktop clients, as much memory as required to hold the
application data
10 GB of available hard disk space
32-bit browser: IE 8+, Firefox, Chrome, or Opera
Page 5 of 123
AIMMS AIMMS PRO - 2
Network Requirements
As far as network requirements are concerned, specifying an exact number for client apps is very
application-specific. While for AIMMS apps with a WebUI the bandwidth requirements are mostly
determined by the amount of data actually displayed on a page, and the rate at which this data needs to
be updated, for AIMMS apps deploying a Windows desktop client bandwidth usage are of a much more
spiky nature. The main bandwidth consumption in this case comes from streaming the runtime and app
(if not already cached on the users desktop), and case files containing the application inputs and results
being communicated with the server. Depending the size of typical case files for a specific app, the
maximum bandwidth requirements are mainly determined by the download times of case files, such that
these still lead to an acceptable user experience.
Please note that most AIMMS apps are intended to serve as decision support applications. Typical for
such applications is the ability for the end-user to ``play with all available data in the application in order
to understand and gain confidence in the presented solution, and observe the sensitivities of the model
output with respect to changes in the input data. For this reason, AIMMS apps hold all available data in
memory, which may lead to spikes in network traffic not seen in typical transaction systems.
Concurrent Connections
By default AIMMS PRO allows 50 concurrent connections, that means its possible to run 25 desktop
applications(solver sessions) or 50 WebUI applications(data sessions) at the same time. Please note
that any desktop application requires 2 connections and any WebUI application requires 1 connection. If
you really want to make 50 concurrent connection then you should increase the memory limits for
AimmsPROWebService. (Go to C:\Program Files\AimmsPRO 2.0\AimmsPROWebService.cfg. Inside this
config file you can find -Xms256m,-Xmx512m parameters under jvmOptions section. Change these
parameters to -Xms512m,-Xmx1024m).
License Session Count
Starting from AIMMS PRO 2.13.3 and AIMMS License Server 4.0.0.50, Client license sessions are now
counted per user/device combination, instead of per session. Which means one user can now run
multiple apps whilst only occupying one session.
Page 6 of 123
AIMMS AIMMS PRO - 2
Installation and Configuration of the License

Server
Before installing AIMMS PRO, you must first install and configure the AIMMS Network License Server.
AIMMS PRO requires that you run at least version 4.0 of the AIMMS Network License Server. The latest
version is available here. Executing the installer will install the AIMMS Network License Server service
on your server. This service is configured to start automatically.
Installation Location and Default Ports
The AIMMS Network License Server installs to
C:\Program Files (x86)\AIMMS\AIMMS License Server
and stores its runtime data in
C:\ProgramData\AIMMS
By default, the AIMMS Network License Server listens on TCP port 3400 for incoming license requests.
If this port is in use during the initial installation, this will cause the installation to fail. Later on, you can
change this port through the AIMMS Network License Manager program, as detailed in the installation
instructions of the AIMMS Network License Server.
Setting up Licenses
After you have installed the AIMMS Network License Server, you must activate the license for the PRO
server itself, as well as the AIMMS licenses for client and server-side AIMMS sessions that you received
with your AIMMS PRO installation. Follow the installation instructions that come with the AIMMS Network
License Server to activate these licenses. Please make sure you select the option Machine nodelock
when you activate the licenses.
Setting up License Profiles
By default, the AIMMS PRO Server assumes that you make
the AIMMS PRO server license available using the license profile name ProLicense, and
the client-side AIMMS session license(s) available using the license profile name Client, and
the server-side AIMMS session license(s) available using the license profile name Server.
Page 7 of 123
AIMMS AIMMS PRO - 2
Please note that you can change the names of these license profiles. If you use non-default names,
however, you should also change the AIMMS PRO configuration accordingly. You may want to use non-
default names for the client and especially the server licenses to prevent unauthorized use of these
licenses. Note that if you change the name of the server-side AIMMS session license(s), all the
applications that depend on that workerProfile will stop working. Exact details on how to add and/or
rename license profiles can be found in the documentation of the AIMMS Network License Server.
License Server Maintenance
Whenever you need to perform maintenance to your license server, it is advisory to also stop the AIMMS
PRO service if it has a non-empty job queue. When you leave the maintenance mode of the AIMMS
Network License Server, it is restarted for the changes you made to take effect. This will cause all
currently running jobs to be terminated with an error condition, as well as all queued jobs that will start
during the restart of the license server.
Page 8 of 123
AIMMS AIMMS PRO - 2
General Architecture
To provide you with a better understanding of whats going on in an AIMMS PRO setup in terms of
communication between the various components, we created the following schema. Please click on it to
see a larger version.
Overview from left to right

Left: the users view
Mid: the provisions given
Right: the resources
High availability and failover
Overview from left to right
This discuss this overview as it corresponds by going from the user view to the realization view.
1. On the left we have the AIMMS PRO PORTAL in a browser. Via this portal, a user can logon and
subsequently launch either a WebUI data session or a Desktop client session.
2. In the middle we have the enterprise firewall which is passed thru, always, via HTTPS. As you know,
HTTPS bases its encryption on SSL.
3. On the right we have the PRO Cluster consisting of one or more PRO servers running Windows. Each
server has three processes at the front: WebUI Service, Portal Service, and Secure Websocket
Proxy. These three processes are serviced by a Jetty Application Server. The central service at the
backend is the PRO Service. The PRO service invokes zero, one or more data sessions and zero, one
Page 9 of 123
AIMMS AIMMS PRO - 2
or more optimization sessions. The communication between these four services, data sessions and
optimization sessions is via ARMI/SSL.
4. On the far right we have three resources shared by the servers: the PRO Storage, the PRO
Administrative database, and the license service. The PRO Storage stores the AIMMS packages, the
apps, and the cases and is only accessed via the PRO Service. Here SMB or CIFS is used to
communicate. The PRO Admin Database is a PostgreSQL database storing information about users and
apps, and is only accessed by the PRO Service via a secure database connection. The License Service
is a service that connects to the other services via a binary proprietary protocol.
Left: the users view
Lets zoom in to the left and detail the user requirements met.
The user starts with the PRO portal via a browser such as Chrome or Internet Explorer 8+. At this portal,
the following actions are supported:
- Uploading an AIMMS version. These versions are signed by AIMMS B.V.
- Uploading an AIMMS end-user application, a so-called app. An app is created from within the AIMMS
development environment from an AIMMS project by using SSL based encryption of the project.
- Launch a desktop application. Here a Windows computer is required. We support Windows 7 and later.
A desktop application runs its own data session. This is still a viable route when only Internet Explorer is
available.
- Launch a WebUI application. Here a Chrome browser is required. Since AIMMS 4.31.1 we also support
IE 11 and Microsoft Edge.
- Finally, the packages, apps, and running jobs are managed via this portal.
Mid: the provisions given
Lets zoom in on the middle and detail provisions given:
Each PRO server in the PRO cluster can handle each of the following tasks:
- WebUI service
- Portal
- Secure Web-socket proxy
- PRO Service
- Zero, one, or more data sessions
- Zero, one, or more optimization sessions
Together, the WebUI service, Portal, PRO Service and Secure web-socket service realize the PRO
environment.
The most important tasks run on PRO are the data session and 0, 1 or more optimization sessions per
data session. There are two important distinctions between a data session and an optimization session:
- A data session is solver-less. The data session is actually run on the client computer when running the
Page 10 of 123
AIMMS AIMMS PRO - 2
desktop client, and run on a PRO Server when running a WebUI app.
- An optimization session supports solving mathematical programs and is always run on a PRO server.
Right: the resources
Third lets zoom in to the far right and detail the resources.
The PRO Servers in the PRO cluster make use of three unique resources:
- The PRO Storage: disk space where the AIMMS packages, the apps, and cases (binary compressed
data snapshots) are stored.
- The PRO Admin database, this is a PostgreSQL databases where administrative data concerning,
users, apps, access rights and so forth are stored.
- The License service, this is a tool that allows you to monitor AIMMS usage.
High availability and failover
Lets aim for high availability and failover.
The PRO Cluster itself is designed for high availability and failover. There is a master, which is self-
elected, spreading the tasks over the available servers in the cluster. Every minute, via the PRO Admin
Database, all available servers check whether the master and its peers are still running. The incomplete
jobs that ran on a server that went down are queued again for a maximum of three times.
Up to a point you can improve the availability of the entire system by improving the availability of the
resources:
You can improve the availability of the PRO Shared Storage Area by using a SAN, NAS or like
storage device.
There is no means yet to improve the availability of the License Service.
You can improve the availability of the PRO Admin Database by replicating this database.
Page 11 of 123
AIMMS AIMMS PRO - 2
Installation of AIMMS PRO on Windows

Now that you have installed the AIMMS Network License Server and set up the required licenses and
profiles, you can install AIMMS PRO 2.0. The installer will install three Windows services:
AIMMS PRO 2.0 Portal Service

PRO 2.0 Service
AIMMS PRO postgresql-x64-9.3
The AIMMS PRO services are configured to start automatically. The AIMMS PRO 2.0 Portal Service will
fail to start if the AIMMS PRO 2.0 Service is not already running. Depending on the host performance, a
minimum of 30 seconds is required for the AIMMS PRO 2.0 Service to start.
Database Support
AIMMS PRO 2.0 stores all of its data in a database. The database used is PostgreSQL. In order to
ensure the optimal performance of AIMMS PRO 2.0, the database should be in the same data center as
the AIMMS PRO installation. The PostgreSQL administration application (called pgAdmin) can be found
in installDir/pgsql/bin/pgAdmin3.exe.
Installation and Data Location
As part of the installation of AIMMS PRO, you can select the locations where the executable files will be
installed (from now on referred to as installDir), as well as the location where AIMMS PRO will store its
configuration files and runtime data (from now on referred to as dataDir). The default installation location
is:
C:/Program Files/AimmsPRO 2.0
whereas the default data location is:
C:/ProgramData/AimmsPRO 2.0
Default Ports
By default, the AIMMS PRO service is configured to listen on TCP port 19340, whereas the AIMMS PRO
Portal service will listen on port 8080 over HTTP. You can modify these settings, configure SSL for PRO
communications and HTTPS access to the portal using the AIMMS PRO Configurator tool, which is
automatically installed for you when installing AIMMS PRO 2.0.
Page 12 of 123
AIMMS AIMMS PRO - 2
Installation of AIMMS PRO on Linux

Running AIMMS PRO on a Linux Server
Running AIMMS PRO on a Linux Server is somewhat different from running AIMMS PRO on a Windows
Server. The main difference lies in a field of AIMMS PRO installation. Windows installation requires
running an installer, an MSI file you get from AIMMS. Linux setup uses Docker. Here is the brief
introduction to Docker, how to install PRO on Linux and walk through of aimmsProWithPostgres.yml file.
What is Docker
Docker is an open-source project that automates the deployment of applications inside software
containers, by providing an additional layer of abstraction and automation of operating-system-level
virtualization on Linux. Docker uses resource isolation features of the Linux kernel such as cgroups and
kernel namespaces to allow independent containers to run within a single Linux instance, avoiding the
overhead of starting and maintaining virtual machines (from Wikipedia).
You can read more about Docker and its advantages on its official website.
Docker installation
AIMMS PRO supports Ubuntu 14.04 or Centos 6.6 with Docker version 1.6.0 or higher. Also please
note that Docker requires the Linux kernel to be 3.10 at minimum. You may find detailed information
about Docker installation on different platforms (including cloud, e.g. AWS) on Docker website.
Please also walk through the official Docker Get Started guide in order to understand the basic concepts
and terminology of Docker.
Additional requirements
There are lots of tools that you can use to manage your Docker containers. This manual will focus on
using Docker Compose because that tool allows to easily manage several Docker containers at a time
and at the same time Docker Compose is easily configurable. You may find documentation about
installing Docker Compose on its website.
What needs to be configured
First of all, you will need to get an AIMMS PRO image. AIMMS PRO images are located on Docker hub
https://hub.docker.com/u/aimms/
Once you have an image you can run it but you first need to configure several things:
Page 13 of 123
AIMMS AIMMS PRO - 2
1. Ports. You need to decide what ports would be available from the AIMMS PRO image to the outside
world. AIMMS PRO uses the following port:
- HTTP port for AIMMS PRO Configurator. By default 9191.
- HTTP and/or HTTPS ports for AIMMS PRO Web (Portal). By default 8080.
- TCP and/or SSL ports for internal communication between PRO components. These ports does not
need to be exposed if youre not running a cluster.
2. Data folder. The folder (called a volume in Docker terminology) that stores AIMMS PRO Data. Please
note that in case you have a cluster, you need to make sure that Storage subfolder is shared between all
nodes (e.g. pointing to a shared mounted network folder).
3. Host. The hostname under which your running container would be reachable from the outside.
How to start AIMMS PRO as a Docker container
As we said before, we think that Docker Compose is a tool that eases configuration and deployment of
Docker container. Here is a Docker Compose configuration file (lets call it
aimmsProWithPostgres.yml, you need to create this file with following configuration) that can be used
to run AIMMS PRO as a Docker container using Docker Compose:
aimmsProPostgres:
image: aimms/pro-postgres:9.3
volumes:
- /home/user/aimmsPro/aimmsProPostgres:/var/lib/postgresql/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
aimmsPro:
image: aimms/pro:PRO_VERSION
ports:
- 19340:19340
- 19341:19341
- 8080:8080
- 8443:8443
- 9191:9191
volumes:
- /home/user/aimmsPro/aimmsProData:/data/aimmspro
hostname: aimms-pro
links:
- aimmsProPostgres
restart: always
And now you can run AIMMS PRO using command
docker-compose -f aimmsProWithPostgres.yml up -d
And to stop AIMMS PRO use
Page 14 of 123
AIMMS AIMMS PRO - 2
docker-compose -f aimmsProWithPostgres.yml stop
Walk through proposed config file line by line
aimmsProPostgres:
This line starts the Postgres image section. Remove this section completely if youre planning to use
standalone database or a Postgres instance on another node of you cluster.
This line means take Postgres image from AIMMS Docker repository. AIMMS PRO Postgres image is a
slightly modified official Postgres image, the only difference is that it already has AIMMS PRO DB user
and schema.
volumes:
This section starts the volumes configuration. Volumes are host machine folders mapped to locations at
the running container.
- /home/user/aimmsPro/aimmsProPostgres:/var/lib/postgresql/data
This line means that Postgres will store its data at /home/user/aimmsPro/aimmsProPostgres folder at the
host machine. Change this configuration to the folder you want.
These two lines are used to make the running container to use the same time settings as its host
machine.
aimmsPro:
This line starts the AIMMS PRO image section.
image: aimms/pro:PRO_VERSION
Please dont forget to change the image version to the one that you need.
ports:
- 19340:19340
- 19341:19341
- 8080:8080
Page 15 of 123
AIMMS AIMMS PRO - 2
- 8443:8443
- 9191:9191
This is the section with ports mappings that were described above. Change them if needed (e.g. put
9292:9191 instead of 9191:9191 if you want AIMMS PRO Configurator to be available at port 9292).
volumes:
This section starts the volumes configuration for AIMMS PRO container.
- /home/user/aimmsPro/aimmsProData:/data/aimmspro
This line means that AIMMS PRO will store all of its changing data (logs, configs, published apps, etc) at
/home/user/aimmsPro/aimmsProData folder at the host machine. Change this configuration to the folder
you need. Please note that in case you have a cluster, you need to make sure that Storage subfolder is
shared between all nodes (e.g. a hyperlink to a network folder).
hostname: aimms-pro
This is the hostname by which AIMMS PRO would be available from the outside.
links:
- aimmsProPostgres
This section says that our AIMMS PRO container would be linked to AIMMS PRO Postgres container
that weve described above. You may read more about linking containers at Docker website. But in few
words: by linking container we allow one container to access another container. So AIMMS PRO
container can access Postgres database running in AIMMS PRO Postgres container using hostname
aimmsProPostgres and port 5432 (which is not exposed from AIMMS PRO Postgres container to the
outer world, but can be reached from the linked container).
restart: always
Always restart the container regardless of the exit status. This is useful to have your AIMMS PRO
instance always running.
Managing started AIMMS PRO
When AIMMS PRO container has successfully started, you may configure AIMMS PRO using a tool
called AIMMS PRO Configurator. It should be available at http://your AIMMS PRO host:Configurator
Port. Please read above how you can change AIMMS PRO host and Configurator port.
Page 16 of 123
AIMMS AIMMS PRO - 2
Please read the information about AIMMS PRO Configurator for the overall configuration of your AIMMS
PRO.
Once youve successfully configured AIMMS PRO and started its services, the services would be started
automatically once youve started AIMMS PRO Docker container.
Notes:
In order to run your Apps from linux PRO server, you need to publish it with linux AIMMS Version
(i.e. linux compatible AimmsPROPackages) which are available with each AIMMS release starting
from AIMMS 4.14.
License Server: You can use Windows license server or Linux license server. Please contact our
support staff to get Linux license server.
AIMMS PRO Upgrade
In order to upgrade your existing installation of AIMMS PRO, do the following:
1. Stop AIMMS PRO container if its running.

2. Change AIMMS PRO image version in aimmsProWithPostgres.yml
3. Start AIMMS PRO container.
No additional setup is required.
Back to top
Page 17 of 123
AIMMS AIMMS PRO - 2
Installation of License Server on Linux

Following are the instructions to install License server and AIMMS PRO on different linux machines.
Note: These instructions kind of suggest that you should have some experience with Linux in order to
follow it.
License Server installation steps.
1. Create a base folder for your License Server installation.

2. Create data folders aimmsLicenseData using inside your PRO installation folder. i.e.
mkdir aimmsLicenseData
3. Create lic.yml (docker-compose configuration file) as shown below and put it into your PRO
installation folder.
aimmsLicenseServer:
image: aimms/license-server:4.0.0.59
ports:
- 3400:3400
- 3401:3401
volumes:
- ./aimmsLicenseData:/data
hostname: aimmsLicenseServerTest
mac_address: 02:42:ac:10:00:10
links:
- aimmsLicenseServer:aimmsLicenseServerTest
restart: always
4. Install docker-compose on your server, see https://docs.docker.com/compose/install/ for details.

Version 1.8.0 should work fine.
5. Start license server using command docker-compose -f lic.yml up -d
6. Execute the command docker ps, you should see something like
CONTAINER ID IMAGE COMMAND

CREATED STATUS PORTS NAMES
d2131d499d92 aimms/license-server:4.0.0.59 "/docker-entrypoint.s"
2 minutes ago Up 2 minutes 3400-3401/tcp
aimmspro_aimmsLicenseServer_1
Please note the CONTAINER ID of the license-server, in this example it is d2131d499d92
Page 18 of 123
AIMMS AIMMS PRO - 2
7. Execute the command docker exec -ti id bash where id is the CONTAINER ID of the license
server from step 6, so for this example command will be docker exec -ti d2131d499d92 bash
8. Now you should be inside license servers running Docker container. The command line prompt
should change to root@id
9. You should have 3 licenses for your AIMMS PRO: Client, Server and PROLicense. For each of them
you should also have an activation code and the license number. For example, you have PROLicense
with the following data: Profile: PROLicense License Number: 123.456.789.012 Activation Code: xxxx-
xxxx-xxxx-xxxx-xxxx
10. For each license execute the following commands:

/usr/local/Aimms/Bin/licman --nodelock-activate <license number without dots>
--type machine --activation-code <activation code> --add-license
/usr/local/Aimms/Bin/licman --profile-add PROLicense --license <license
number without dots>
For example,
/usr/local/Aimms/Bin/licman --nodelock-activate 123456789012 --type machine
--activation-code xxxx-xxxx-xxxx-xxxx-xxxx --add-license
/usr/local/Aimms/Bin/licman --profile-add <license profile> --license
123456789012
11. Repeat step-10 for other 2 PRO Licenses (Client and Server).
12. Exit the running container by running command exit in the command prompt.
13. Restart your license server by running command docker-compose -f lic.yml restart.
AIMMS PRO installation steps
1. Create a base folder for your AIMMS PRO installation.

2. Create 2 data folders aimmsProPostgres, aimmsProData, aimmsLicenseData using inside your PRO
installation folder. i.e.
mkdir aimmsProPostgres
mkdir aimmsProData
3. Create pro.yml (docker-compose configuration file) as shown below and put it into your PRO
aimmsProPostgres:
volumes:
Page 19 of 123
AIMMS AIMMS PRO - 2
- ./aimmsProPostgres:/var/lib/postgresql/data
aimmsPro:
image: aimms/pro:<PRO_VERSION>
ports:
- 19340:19340
- 19341:19341
- 8080:8080
- 8443:8443
- 9191:9191
volumes:
- ./aimmsProData:/data/aimmspro
hostname: aimms-pro
links:
- aimmsProPostgres
restart: always
4. Start PRO and Postgres using command docker-compose -f pro.yml up -d

5. Now your AIMMS PRO should be running. Open the browser, go to http://localhost:9191. You should
see AIMMS PRO Configurator.
6. Enter aimmsLicenseServerTest:3400,ProLicense as PRO Server License,
aimmsLicenseServerTest:3400,Client as PRO Client License, aimmsLicenseServerTest:3400,Server as
Profile in Worker Profiles and click Save All Settings button.
7. You should see PRO settings saved message. Now you may go to Start/Stop Services page and start
your AIMMS PRO instance.
Page 20 of 123
AIMMS AIMMS PRO - 2
Instructions to install License Server

together with AIMMS PRO
Following are the instruction to install License Server together with AIMMS PRO on the same machine.
Note: These instructions kind of suggest that you should have some experience with Linux in order to
follow it.
1. Create a base folder for your AIMMS PRO installation.

2. Create 3 data folders aimmsProPostgres, aimmsProData, aimmsLicenseData using inside your PRO
installation folder. i.e.
mkdir aimmsProPostgres
mkdir aimmsProData
mkdir aimmsLicenseData
3. Create pro.yml (docker-compose configuration file) as shown below and put it into your PRO
aimmsLicenseServer:
image: aimms/license-server:4.0.0.59
volumes:
- ./aimmsLicenseData:/data
hostname: aimmsLicenseServerTest
aimmsProPostgres:
volumes:
- ./aimmsProPostgres:/var/lib/postgresql/data
aimmsPro:
image: aimms/pro:<PRO_VERSION>
ports:
- 19340:19340
- 19341:19341
- 8080:8080
- 8443:8443
- 9191:9191
volumes:
- ./aimmsProData:/data/aimmspro
hostname: aimms-pro
links:
- aimmsProPostgres
- aimmsLicenseServer:aimmsLicenseServerTest
restart: always
Page 21 of 123
AIMMS AIMMS PRO - 2
4. Install docker-compose on your server, see https://docs.docker.com/compose/install/ for details.

Version 1.8.0 should work fine.
5. Start PRO, Postgres and license server using command docker-compose -f pro.yml up -d
6. Execute the command docker ps, you should see something like
CONTAINER ID IMAGE COMMAND

CREATED STATUS
PORTS
NAMES
dd87763a3be4 aimms/ 2.12.2.816 "/opt/aimmspro/pro-en" 2
minutes ago Up 2 minutes 0.0.0.0:8080->8080/tcp,
0.0.0.0:8443->8443/tcp, 0.0.0.0:9191->9191/tcp,
0.0.0.0:19340-19341->19340-19341/tcp aimmspro_aimmsPro_1
d2131d499d92 aimms/license-server:4.0.0.59 "/docker-entrypoint.s"
2 minutes ago Up 2 minutes 3400-3401/
tcp
aimmspro_aimmsLicenseServer_1
b31230dc8c64 aimms/pro-postgres:9.3 "/docker-entrypoint.s"
About an hour ago Up 2 minutes 5432/
tcp
aimmspro_aimmsProPostgres_1
Please note the CONTAINER ID of the license-server, in this example it is d2131d499d92
7. Execute the command docker exec -ti id bash where id is the CONTAINER ID of the license
server from step 6, so for this example command will be docker exec -ti d2131d499d92 bash
8. Now you should be inside license servers running Docker container. The command line prompt
should change to root@id.
9. You should have 3 licenses for your AIMMS PRO: Client, Server and PROLicense. For each of them
you should also have an activation code and the license number. For example, you have PROLicense
with the following data: Profile: PROLicense License Number: 123.456.789.012 Activation Code: xxxx-
xxxx-xxxx-xxxx-xxxx
10. For each license execute the following commands:

/usr/local/Aimms/Bin/licman --nodelock-activate <license number without dots>
--type machine --activation-code <activation code> --add-license
/usr/local/Aimms/Bin/licman --profile-add PROLicense --license <license
number without dots>
For example,
/usr/local/Aimms/Bin/licman --nodelock-activate 123456789012 --type machine
--activation-code xxxx-xxxx-xxxx-xxxx-xxxx --add-license
Page 22 of 123
AIMMS AIMMS PRO - 2
/usr/local/Aimms/Bin/licman --profile-add <license profile> --license

123456789012
11. Repeat step-10 for other 2 PRO Licenses (Client and Server).
12. Exit the running container by running command exit in the command prompt.
13. Restart your PRO by running command docker-compose -f pro.yml restart
14. Now your AIMMS PRO should be running. Open the browser, go to http://localhost:9191. You should
see AIMMS PRO Configurator.
15. Enter aimmsLicenseServer:3400,ProLicense as PRO Server License,
aimmsLicenseServer:3400,Client as PRO Client License, aimmsLicenseServer:3400,Server as Profile in
Worker Profiles and click Save All Settings button.
16. You should see PRO settings saved message. Now you may go to Start/Stop Services page and
start your AIMMS PRO instance.
Page 23 of 123
AIMMS AIMMS PRO - 2
Using the AIMMS PRO Configurator

AIMMS PRO 2.0 can be configured using the AIMMS PRO Configurator tool which is installed to your
server together with PRO itself. It can be accessed any time using the AIMMS PRO Management
shortcut on the desktop or by navigating to http://localhost:9191 on the server hosting PRO.
Configuring the configurator

Various sections of the configurator
Page 24 of 123
AIMMS AIMMS PRO - 2
Configuring the configurator

The configurator runs as a web service, thus it is available via HTTP/HTTPS on a specific port (by
default, HTTP port 9191). These values can be changed in the configurator.properties file, found in
dataDir/config. An empty value means disabled.
http.port change this if the default 9191 does not work for you
https.port disabled by default. Fill in a port to allow HTTPS connections
https.keyStoreFile the full path to the PKCS 12 file holding the server certificate that will be used
by the Configurator for HTTPS connections
https.keyStorePassword the password for the keyStoreFile
In order to apply the changes done to this file, you will need to restart the AIMMS PRO Configurator
Service from the Windows Services management console.
Page 25 of 123
AIMMS AIMMS PRO - 2
Various sections of the configurator

The AIMMS PRO Configurator has several sections.
Each settings section comes with default values, so you dont need to input all settings from scratch for a
new installation. You just need to go through the Connection configuration and PRO configuration
sections, make changes if needed (or just to make sure that everything is correct) and save the settings.
If some settings are wrong, you will see the corresponding error messages next to the incorrect value(s).
You will need to fix these errors before the changes that you made can be saved. Fields often have
tooltips that help you to understand what value needs to be entered. Just move your mouse over the [?]
icon to see the help message.
Configuration
Connection Configuration
PRO Configuration
Portal Customization
Migration from PRO 1.0
Backup Management
Start/stop services
Page 26 of 123
AIMMS AIMMS PRO - 2
Connection configuration
In the Connection configuration section, you can configure the PostgreSQL database that AIMMS PRO
connects to for storing its internal data. PostgreSQL comes bundled with the AIMMS PRO installation, so
there is no need to set it up separately. The bundled PostgreSQL installation works out of the box. You
need to enter the host (in JDBC format). You may also need to change the username, the password and
the schema name in the corresponding fields.
You can use the buttons at the bottom of the window to either save your database connection settings,
to test them (without saving) or to reset the changes that you have made to the settings without saving.
If the connection cannot be established with the settings you provided, you will see an error message
describing what went wrong. If you want your PRO to work in a cluster setup, you need to make
sure that all your cluster nodes are connecting to the same database. Please refer to the section
Setting up a cluster for further information.
Back to top
Page 27 of 123
AIMMS AIMMS PRO - 2
PRO configuration
In this section, you can change all settings related to your PRO instance(s). This includes both settings
that are common for all nodes in a cluster (if you have one) and settings for any particular node in your
cluster. This section contains the settings that were available in the AimmsPROServer.json file in AIMMS
PRO 1.0. If youve performed a migration as described below, these settings will appear in this section;
you will just need to make sure that they are correct. Some of the settings can be changed while running
PRO; these will be applied immediately. If your changes however require a restart of all your nodes, you
will get a message telling you so. The PRO configuration section consists of several subsections, each
of which is explained in detail below.
Note: Please note that after the fresh installation of AIMMS PRO, PRO configuration page is pre-loaded
with some default information. Hence as an Administrator it is required to check this information and click
Save before starting PRO services.
Page 28 of 123
AIMMS AIMMS PRO - 2
General settings
These are the general settings that the whole of your PRO setup is using, i.e. all nodes in a cluster setup
(if you have one), not just the machine on which you run the AIMMS PRO Configurator.
Here you may change the following settings:
PRO server license: URI for the PRO server license on your license server. Format: :,
Client license server: URI for your client-side AIMMS session license. Format: :,
Storage directory: directory in which files are stored. Should be shared between all nodes (i.e. a
shared directory on a network drive). Please note that if your PRO server is running on linux then
this field is disabled and configured externally.
Job retention time (days): time (in days) after which a job will be removed from the jobs list.
Page 29 of 123
AIMMS AIMMS PRO - 2
Web configuration
Here you can specify HTTP and/or HTTPS ports on which the AIMMS PRO portal will listen.
For HTTPS connectivity, you must specify an SSL Key store file (optionally with a password) containing
the server certificate and the private key to be used by the portal server.
Note: If your PRO server is running on linux then HTTP and HTTPS ports fields are disabled and
configured externally.
Page 30 of 123
AIMMS AIMMS PRO - 2
Worker profiles
This section denotes which license profiles are available for server-side AIMMS worker sessions to
perform server-based optimization tasks. Please note that the first (top) profile will be used as the
default.
For each worker profile, you need to specify the following settings:
Name: a name for the profile. Please give it some meaningful name, as it will appear on the
publishing screen for a new app, where you will need to select the profile based on the name.
Please note that if you change this value or remove this profile, then all projects that are already
using this worker profile will be using the default (first) worker profile.
Capacity: this value denotes how many sessions this license profile can handle at the same time.
The capacity should match (be less than or equal to) the amount of licenses available through this
license profile in the AIMMS Network License Server.
Profile: server-side AIMMS session license. Format: :,
Page 31 of 123
AIMMS AIMMS PRO - 2
Queue priority settings
A list of priorities for PRO jobs that match the criteria specified in the priority rule.
If a request matches multiple priority rules, the highest priority (i.e. the lowest value) will be selected.
Here you need to enter the Default priority the priority for all requests that have no other matching
priorities. You may also add as many specific priorities as needed. For each of them you need to specify
the following:
Priority: a lower number means a higher priority.

User: the user that runs the application. Use .* for all users of all environments, .*@ for all users of
a specific environment, or @ for a specific user and a specific environment.
Application name: the name of an application. Use .* for all applications. Application names are
case sensitive.
Application version: the version of an application. Use .* for all application versions. Application
versions are case sensitive.
Page 32 of 123
AIMMS AIMMS PRO - 2
Queue rules
A configurable list of rules that are applied to any request matching criteria specified for a particular rule.
With these rules you can limit the number of jobs that can be run simultaneously by a particular user
and/or a particular application on a particular node.
If you want to introduce such a limit for each rule, you need to specify the following:
Capacity: the maximum capacity that may be used for the jobs for this rule.
User: the user that runs the application. Use .* for all users of all environments, .*@ for all users of
a specific environment, or @ for a specific user and a specific environment.
Application name: the application name for the rule. Use .* for all applications. Application names
are case sensitive.
Application version: the application version for the rule. Use .* for all application versions.
Application versions are case sensitive.
Node name: the name of the node for the rule. Please keep in mind that nodes have their own
capacity (see below), so the smaller capacity will be used to decide whether a node can process a
particular job.
Page 33 of 123
AIMMS AIMMS PRO - 2
Ports to listen
Port(s) on which the AIMMS PRO server will listen.
You may specify several ports separate for internal and external connections (see External URI and
Internal URI below). There must be at least one port to listen on, otherwise AIMMS PRO will not be able
to operate. All nodes in your cluster will be listening to the same ports that you specify in this section.
For SSL connections, you must specify an SSL Key store file that contains the certificate and private key
to be used for the server, along with the password (if any) by which the SSL Key store file is protected.
Each listening port has the following fields:
URI: a protocol with a port to listen to. Format: ://: (e.g. tcp://:19340).
SSL Key store file: the file or URL of the SSL Key store (if needed)
Key store password: the password (if any) by which the SSL Key store file is protected.
Note: If your PRO server is running on linux then URI field is disabled and configured externally.
Page 34 of 123
AIMMS AIMMS PRO - 2
Configuration specific for separate nodes
A list of settings for the servers that can be used by the AIMMS PRO server to dispatch server-side
AIMMS sessions to. Each node automatically appears in this list when you are adding it to your cluster.
You cannot add or remove server nodes from within the AIMMS PRO Configurator.
For each node you can change the following settings:
Capacity: the number of parallel sessions that this node can handle at a time.
Internal URI: The host to which AIMMS PRO web server will connect to the backend server. The
value entered here should have a matching ports to listen configuration. Format: ://: (e.g.
tcp://myhost:19340).
Web URI: The host (without schema or port) by which AIMMS PRO web server will be available in
users browser. Usually, the default value is correct. Change this if the PRO host has a different
hostname on the external network (the one that users are on). Format: ://: (e.g. myhost).
Page 35 of 123
AIMMS AIMMS PRO - 2
Migration from AIMMS PRO 1.0.x

The migration from AIMMS PRO 1.0.x is facilitated by the AIMMS PRO Configurator.
In order to perform a successful migration from AIMMS PRO 1.0.x to AIMMS PRO 2.0, you need to make
sure that the following criteria are met:
The Connection configuration should be correct. This means that the database that you have
configured in the Connection configuration section is available with the settings you have
provided there.
Your new installation should be using the same data folder as PRO 1.0. By default, it is
C:\ProgramData\AimmsPRO.
The old database can be found at the Data subfolder of your data folder from previous the
criterion above. Look for the AimmsPRO.db3 file, which contains the configuration information of
your AIMMS PRO 1.0.x installation.
The old configuration file can be found at the Config subfolder of your data folder. Look for the
AimmsPROServer.json file.
The AIMMS PRO configurator will check these criteria for you and will show an error message if they are
not met. Otherwise, you can start the data migration using the corresponding button on the screen.
Page 36 of 123
AIMMS AIMMS PRO - 2
Start/stop services
In this section you may start or stop AIMMS PRO 2.0 services and view service statuses.
You will not be able to start or stop services if your PRO configuration is not valid. If so, you will get a
message telling you what is wrong.
Page 37 of 123
AIMMS AIMMS PRO - 2
Backup management
AIMMS PRO Configurator has a section called Backup management that allows to manage backups of
the AIMMS PRO database and configuration (but not the storage folder). Using this section PRO
Administrator may manually make backups or schedule automatic backups (see below).
This section consists of three sections.
General settings
These are the general setting for AIMMS PRO backups.
You may change here the following settings:
1. Backup folder path to the folder where the backups are stored on this server. By default the
value is %AIMMS_PRO_DATA%\Backup (e.g. C:\ProgramData\AimmsPRO\Backup)
2. Actions timeout (in minutes) timeout for all backup-restore actions (in minutes). 0 means
indefinite timeout. Change this value if you have a large PRO database and backup (or restore) of
the database takes a long time.
3. Backup schedule a cron expression for running backups automatically. This cron expression is
represented by six fields: second, minute, hour, day of month, month, day(s) of week where
- (*) means match any

- */X means every X
- ? means no specific value.
Page 38 of 123
AIMMS AIMMS PRO - 2
Leave this field blank to disable automatic backups. Default value is 0 5 0 * * ? which means that
backups will be created every day 5 minutes after midnight.
The button Save settings validates and saves backup settings.
The button Backup now immediately creates a backup.
Back to top
Backups from current version of AIMMS PRO suite
This section shows backups that were made from the current major version of your AIMMS PRO Suite.
So if you had version 2.5.1003.100 installed, made some backups there, then installed 2.6.1001.200,
made some backups and later on upgraded to 2.6.1003.300 then you will see backups from
2.6.1001.200 and 2.6.1003.300 in this section. Backups from 2.5.1003.100 will go to Backups from
other versions of AIMMS PRO suite section (see below).
Each backup name contains the following:
Version of the AIMMS PRO installation on which it was created

Name of the node on which it was created
Date and time of the creation
You may select several backups and delete them if needed. You may select one backup and revert your
database and configuration to the state that backup presents. Of course, that would mean that you will
lose all applications published after that backup point. But if you restore to backup that contains those
applications they will be available again.
Back to top
Page 39 of 123
AIMMS AIMMS PRO - 2
Backups from other versions of AIMMS PRO suite
This section shows backups that were made from the versions different from the current major version of
your AIMMS PRO Suite. See explanation about current major version concept in Backups from current
version of AIMMS PRO suite section above.
You may select several backups and delete them if needed. You may not restore any backup from this
section.
Full backup of all of your AIMMS PRO data
Please note. This backup section provides only possibility to backup AIMMS PRO database and its
configuration files (that are located in %AIMMS_PRO_DATA%\Config folder, e.g. C:\ProgramData\
AimmsPRO\Config\). PRO administrator needs to backup the storage folder using some external tools if
that is needed (for example, this way). There are lot of tools available for incremental backups.
Back to top
Return to Using the AIMMS PRO Configurator section.
Page 40 of 123
AIMMS AIMMS PRO - 2
Setting up an AIMMS PRO Cluster

Setting up a PRO cluster is a task that consists of two steps: connecting all nodes to the same database
and pointing them to a shared storage directory.
Connecting all Nodes to the Same Database
All your nodes need to be connected to the same database. This can be a database on one of the nodes
(AIMMS PRO comes with a bundled PostgreSQL database) or a PostgreSQL database running on a
dedicated server.
Before proceeding to connect all the nodes to the database, make sure that your PostgreSQL server
settings allow non-local connections. Stop your Aimms PRO Postgresql-x64-9.3 Windows service,
modify pg_hba.conf (located in dataDir\pgsql\data\, by default that would be C:\ProgramData\
AimmsPRO 2.0\pgsql\data\). The comments in the file will tell you what you need to do.
For example, to enable all incoming IPv4 connections (this is a security risk), add the following line in the
IPv4 local connections section:
host all all 127.0.0.1/0 md5
After youre done, start the Aimms PRO Postgresql-x64-9.3 Windows service again.
Please also make sure that the firewall on the machine where you have your database server allows
incoming connections to the specified database ports.
In order to have all the AIMMS PRO nodes pointing to the same database, you need to run the AIMMS
PRO Configurator on each node and change the settings in the Connection configuration section. More
specifically, the host field should point to the fully qualified domain name (FQDN) of the server on which
the shared database resides. So, on the second node that you add to a cluster, replace the localhost
part with the FQDN of the first node of the cluster.
The values in the PRO Configuration section are common for all your nodes. If you configured AIMMS
PRO properly on one node, there is no need to go through this step on other nodes in your cluster, as
the information is simply retrieved from the commonly accessed database. However, you may want to
modify the capacity or the URIs for particular nodes as described in Configuration specific for separate
nodes.
PRO internal database connections
Depending on the way you will be using AIMMS PRO, the number of connections that the bundled
database server handles at a time can prevent AIMMS PRO from functioning properly. AIMMS PRO
Page 41 of 123
AIMMS AIMMS PRO - 2
needs 16 connections per node, plus 2 connections for each job that you want to run on your cluster.
The resulting number needs to be increased to be a multiple of 16 (i.e. 16, 32, 48, etc).
The formula is: 16*N + 2*S. N is the number of nodes in the cluster, S is the maximum number of
sessions your cluster allows to run in parallel. For example: if you have a cluster of 4 nodes and you
intend to run 100 sessions at the same time on that cluster you will need 264 connections. So you will
need to allow 272 connections (272 is the closest bigger number than 264 is a multiple of 16).
You will see a warning message in the Start/stop services section of the AIMMS PRO Configurator if
your database server allows less connections than the number required.
By default, the bundled PostgreSQL server that comes with your AIMMS PRO installation is configured
to allow a maximum of 128 connections. If that is not enough, you will need to stop the Aimms PRO
Postgresql-x64-9.3 Windows service, modify the postgresql.conf file (located in dataDir\pgsql\data\; by
default that would be C:\ProgramData\AimmsPRO 2.0\pgsql\data\) and start the Windows service
again. The setting you need to modify is called max_connections.
Shared storage directory
In order to successfully work, the AIMMS PRO cluster needs to have access to a network shared
directory (supporting SMB/CIFS). It can be a directory on a dedicated file server or a shared directory on
one of your cluster nodes. You should set the path to that directory in the Storage Directory parameter in
the PRO configuration section of the AIMMS PRO Configurator as described above.
Please note that AIMMS PRO 2.0 runs as a service, so the windows user that runs that service (Local
system by default) needs to have full access to the directory. This may require changing the Log On
settings for your Aimms PRO 2.0 Service Windows service.
Check that the cluster was set up properly
After you have added the second node to the cluster, according to the instructions above, you should
start the AIMMS PRO services on that second node. To make sure that the cluster setup was done
properly, publish an application and run a couple of jobs from it. After doing so, by looking at the jobs
page of the portal, you should see that jobs were executed on both nodes of the cluster.
Other prerequisites
All AIMMS PRO nodes need to have a synchronized date and time. The functioning of the cluster
requires that the servers that are part of it have the same date and time. This is usually achieved by
using NTP.
Page 42 of 123
AIMMS AIMMS PRO - 2
Guidelines for using the cluster
When running in a cluster, all the servers will have a fully functional AIMMS PRO installation running on
them. This means that an AIMMS PRO Portal instance will be available on every server. As a best
practice, we recommend not giving their addresses directly to users, but creating a general entry in the
DNS and relating that to the AIMMS PRO Portal instances.
Moving from a single node configuration
A likely scenario is that you have used AIMMS PRO in a single node configuration and now you are
switching to a multiple node configuration (cluster). If you have already published AIMMS versions and
AIMMS applications, they have been stored on the local machine storage. Now that you have configured
the Shared storage to be a network folder, you will need to manually move those files from the local
storage folder to the network folder. This folder is located at dataDir\Data\Storage. By default, you can
find this folder in
C:\ProgramData\AimmsPRO\Data\Storage.
Page 43 of 123
AIMMS AIMMS PRO - 2
Server-side Logging
All activities of the AIMMS PRO Service, Portal Service and server-side sessions are logged. Such logs
may be useful when tracing the cause of unexpected errors that may occur while running AIMMS PRO.
Logs Location
All log files are gathered in Log subfolder of the AIMMS PRO data folder, by default that would be
C:\ProgramData\AimmsPRO\Log. You may change the logs configuration as described below in order to
get more detailed logging information, change file names, file generation policy, etc.
Log files
If something does not work you may want to check the following files for errors:
AimmsPROServer.log AIMMS PRO Backend logs
AimmsPROWeb.log AIMMS PRO Web (Portal&WebUI) logs
AimmsPROConfigurator.log AIMMS PRO Configurator logs
Files with the similar names but with the date appended contain logs from previous days. For example,
AimmsPROServer.2015-06-21.0.log contains AIMMS PRO Backend logs for 21st of June 2015.
Log Configuration
All log configuration files are located in the dataDirConfig directory. AIMMS PRO 2.0 uses the following
log configuration files:
AimmsPROServerLog.xml AIMMS PRO 2 Service logging

AimmsPROSessionLog.xml Server-side sessions logging
AimmsPROConfiguratorLog.xml AIMMS PRO Configurator logging
AimmsPROWebLog.cfg AIMMS PRO Web Service logging
AimmsDispatcherServiceLog.cfg AIMMS Dispatcher Service
Changing the logging Level
For each component, you can specify the detail level at which logging events should take place. By
default, all components log at the INFO level. You can modify the logging level by editing the log
configuration files mentioned above. In case of unexpected errors, you may want to (temporarily) change
Page 44 of 123
AIMMS AIMMS PRO - 2
the logging level of the corresponding component to DEBUG or

TRACE, which will create a log file containing all available logging events for that component.
For AIMMS PRO 2 Service, changing the log level is very easy: open AimmsPROServerLog.xml
and change the value of the property PRO_LOG_LEVEL from INFO to TRACE. The service will
automatically reload the configuration file within 30 seconds, no restart is required.
For the configuration files with the .cfg extension, change the entry log4j.rootLogger=INFO,Logfile
to log4j.rootLogger=trace,Logfile. The corresponding service needs to be restarted to pickup the
new configuration.
For the configuration files with the .xml extension, look for the node root and change the entry
level value=info to level value=trace . The corresponding service needs to be restarted to
pickup the new configuration.
Page 45 of 123
AIMMS AIMMS PRO - 2
Server Administration
After you have successfully installed AIMMS PRO 2.0, you can open the portal to perform administrative
tasks. By default, the portal can be reached at the URL http://:8080. To perform administrative tasks, you
can log in using the administrative account admin within the ROOT environment. Upon installation, the
admin account is delivered with the default password admin. You are advised to change this password
as soon as possible, which can be done by clicking on the admin@ROOT menu on the top right of the
screen, and selecting Account settings from the menu that pops down.
Administrative Tasks
Through the AIMMS PRO portal, you can perform the following administrative tasks:
user management,
management of AIMMS versions,
management of published AIMMS applications, and
management of jobs.
Page 46 of 123
AIMMS AIMMS PRO - 2
AIMMS Application Management

Publishing Applications
Any PRO-enabled AIMMS project can be published onto an AIMMS PRO Server. PRO-enabled projects
must be made available in the form of a .aimmspack file, and can be published through the Apps area of
the portal. All members of the admin and the AppPublishers groups will have a publish button available
in the Apps area, through which they can publish PRO-enabled .aimmspack files. After selecting a
.aimmspack file and an (optional) application icon to be used in the portal, you have to provide some
additional information about the application:
Application name: the name by which the application will be identified within the AIMMS PRO
Framework.
Application version: the application version. The combination of the name and version should be
unique.
Description: a descriptive text to be displayed in the portal.
AIMMS version: the published AIMMS version used to deploy the AIMMS application.
License profile: the license profile to be used for server-side optimization sessions of this
application.
Configuring User Access
After supplying the application details, you will get the possibility of setting the user access rights for this
application. In the screen that follows, you will see a block for each environment, user group, and user.
Different Rights
In the blocks you will see three different rights:
r: This stands for read access. If a user has read access for an application, it means that the user
will see this application in his application list on his app screen.
w: This stands for write access. If a user has write access for an application, it means that the
user is able to modify the properties and access rights of the application. Furthermore, the user is
also allowed to delete and update the application.
x: This stands for execute access. If a user has execute access for an application, it means that
the user is able to run the application.
For ordinary application access, you need to enable read and execute access.
Page 47 of 123
AIMMS AIMMS PRO - 2
Hierarchy of Rights
Next to each of the rights indicators, you will see a color. If the circle is grey, it means that this user, or
user group has the same rights as its parent (i.e. a user will inherit the rights from the user groups it is in
and a user group will inherit the rights from its parent environment). For the particular case of
environments, if permissions have not been defined yet (i.e. are grey), the users of that environment will
not have any kind of access to that application. If the circle is green, it means that the user has this
particular right, while the color red indicates that the user, user group or environment has been denied
this particular access right. Deny will always take precedence over any other permissions in the
Hierarchy of rights (e.g.: setting a red execute permission for an app at the environment level will
prevent anyone in that environment from executing the app, even if that user or group have explicitly set
green execute permission for the app; this same rule applies for users that are part of different
environments, deny will always take precedence).
Changing Permissions
After you have published the application, you can always change the access rights of the application
through the permissions link in the info box of the application. You will only see this link if you have
write access to the application.
Updating and Deleting Applications
If you have write and execute access to the application, you may also update and delete the application.
When updating an application, after uploading a new .aimmspack file, the AIMMS PRO server will
already copy all the settings and access rights of the application version you wish to upgrade, allowing
you to change only those values that really need to be changed. You have the option to keep or to hide
the previous version of the application. If you hide it, it will become invisible to all users, except those
with global administrative privileges, but existing queued jobs will still be able to access it. If you delete
an application, queued jobs may fail altogether. You are therefore strongly advised to select the option to
hide the previous version, and only delete it after all queued requests have been completed successfully.
Starting from PRO 2.16, you can delete multiple Apps together by using Delete selected button. This
will also delete the application from PRO storage.
Windows 8 support
In case your users use Windows 8 or above, only the applications published with an AIMMS version
higher than 3.13.2.370 will work on their machines.
Page 48 of 123
AIMMS AIMMS PRO - 2
AIMMS Version Management

As part of every AIMMS release, so-called AIMMS PRO Server packages (for Windows and Linux) will
be made available. Through the AIMMS PRO portal, all users with global administrative privileges and
users who are member of the AIMMSPublishers group can publish AIMMS PRO Server packages to
AIMMS PRO. You can use published AIMMS PRO Server packages to deploy AIMMS applications that
are developed and tested using the corresponding AIMMS developer releases. Each AIMMS PRO
Server package contains:
an installation-free AIMMS PRO Client without solvers, which will run the client part of the
application on the computer of the end-user, and
an AIMMS component with all solvers included, to run the server-side optimization sessions.
All published AIMMS versions are available for deployment of end-user applications to all users from all
environments.
Please note that if your PRO server is running on Linux then you need to publish linux AIMMS versions
(i.e. AimmsPROPackage-4.14.0.71-linux64-x64/x86.7z) which are available with each AIMMS release
starting from AIMMS 4.14.
Deletion
On the AIMMS Versions section of the PRO Portal, you can also delete AIMMS PRO Server packages
that you dont need anymore. In case the version that you want to delete it still in use by one or more
apps, an error message will tell you so, and the version is not deleted.
Starting from PRO 2.16, Portal allows you to delete all unused AIMMS Versions in one go by using
Delete unused AIMMS Version button. This will check if there are any unused AIMMS Versions and if
so then it will delete all such AIMMS versions.
Page 49 of 123
AIMMS AIMMS PRO - 2
User Management
In the Users area of the portal, you can perform all user management tasks related to AIMMS PRO. The
following user management concepts are supported:
Environments
Groups
Users
Environments
An environment within AIMMS PRO denotes an entity of users which is clearly separated from the users
in all other environments. For instance, through the concept of environments you may provide AIMMS
applications to multiple companies or departments within a company, where you can (but need not)
delegate the user administration of a particular environment to a user within that environment. Each
environment can make its own distinguishable set of AIMMS applications available to its users. Each
environment can be linked to a separate Active Directory domain, to allow a single sign-on experience
for the users of that environment. AIMMS PRO supports up to 127 environments.
Groups
Within each environment, you can define one or more user groups, to which you can assign one or more
users from within the same environment (but, if you see the need, also from other environments).
Groups allow you to introduce role-based authorization within AIMMS PRO, because the authorizations
of all AIMMS PRO objects are defined in terms of users groups as well as individual users.
Users
Users represent the users of the AIMMS PRO Framework. You can assign particular roles to a user by
associating that user with a user group corresponding to the intended role. For each user, you can
specify such information as their full name and email address. Any user must be part of at least one user
group. User accounts are either password protected for standalone environments, or are authenticated
against a linked Active Directory domain to provide a single sign-on experience.
The ROOT Environment
By default, AIMMS PRO comes with a single environment installed, the ROOT environment. The global
admin account is part of the ROOT environment, as well as a number of system groups. These
associations cannot be changed and the permissions cannot be revoked for this user through the AIMMS
PRO permission mechanism.
Page 50 of 123
AIMMS AIMMS PRO - 2
The admin group: all users in the admin group have global administrative privileges equal to the
admin account.
The AIMMSPublishers group: all users in this group are allowed to publish AIMMS versions. These
AIMMS versions can be used to run published AIMMS applications.
The AppPublishers group: all users in this group are allowed to publish AIMMS applications.
Please note that these system accounts and groups cannot be deleted.
Creating a New Environment
Within the portal, any user with global administrative privileges can create new environments. Each
environment is created by default with an admin group and user within that environment. The admin user
of a particular environment (with default password admin), and members of its admin group, have full
administrative privileges within that environment:
they can add, delete and modify users and groups within the environment,
they inherit the same access rights to objects in- and outside of the environment as assigned to
any of the environments users or user groups,
they can link an environment to an Active Directory domain.
The admin group and user associated with an environment cannot be deleted.
Hierarchy
Within an environment, user groups and users have a hierarchical relation: if you click on an
environment, you will see all the user groups in the environment. Similarly, if you click on a user group,
you will get to see all of the users that are in the selected user group.
Adding New Entities
Above the column of each type, there is an add link that allows you to add a new item of the type of that
column. This way you can add new environments, add new user groups to the currently selected
environment or create new users within the current user group.
Adding a New User
By clicking on the add link in the column of the users, you will create a new user. When you create a
new user, you will be presented with a list of properties to be filled in for the new user like the username,
password, full name, and email address. By default, the newly created user will only be in the last
selected user group.
Page 51 of 123
AIMMS AIMMS PRO - 2
Group Membership
You can add an existing user to another group simply by dragging the user onto that group. You can
remove a user from a group by first clicking on the group you want to remove the user from. After that,
you can click the unlink icon of the user to remove. Note that each user must be member of at least one
group.
Editing and Deleting Users and Groups
If you hover over a user or user group, you will see two icons appear. These two icons will allow you to
either edit or delete that entity. In case of users, you will also get the aforementioned third icon to unlink
the user from the currently selected user group.
Page 52 of 123
AIMMS AIMMS PRO - 2
Monitoring
Starting with PRO 2.3+, in the PRO Portal, all the members of the admin group in the ROOT and other
environments have a new drop-down menu available in the top horizontal navigation bar:
Administrative Tools. This menu provides more information about what is happening in the PRO
environment. It is particularly relevant when running PRO in a cluster configuration.
The options that are currently available for monitoring are:
Cluster setup: displays details about the nodes that make up the PRO cluster. Has a link View
Details to Server Monitoring page which displays the details about the PRO Server. Also the
details of the running Solver sessions/ Data sessions and ability to Terminate running sessions.
Database Monitoring: displays details about the connections made from the current node to the
database.
Licenses Monitoring: displays details about the currently configured PRO license profiles.
Job rules Monitoring: displays details about the queue priorities and rules.
Seats Monitoring: displays detailed information about the usage of the client licenses and ability
to Delete reserved seats for WinUI apps. Please Note that starting from AIMMS PRO 2.13.3+ and
AIMMS License Server 4.0.0.50+, Client License sessions are counted per user.device
combination, instead of per session meaning that one user can now run multiple apps whilst only
occupying one session.
Page 53 of 123
AIMMS AIMMS PRO - 2
Configuration
Starting with AIMMS PRO 2.16, in the PRO Portal, all the members of the admin group in the ROOT
environment have a new menu available in the top horizontal navigation bar: Configuration. Using this
menu AIMMS PRO administrator can configure several settings of AIMMS PRO like Active Directory,
Retention Time settings, Portal customization and Tunnels. It also contains Log Management and Link to
open AIMMS PRO Configurator.
The options that are currently available for configuration are:
AD Settings: Allows you to specify the Active Directory credentials to allow loging in to non-
domain computers
Retention Settings: Allows you to configure Job retention time.
Portal Customization: Allows you to customise your AIMMS PRO Portal where you can upload
Image for Login page and your Company logo.
Tunnels: Allows you to configure your database tunnels .
Log Management: Admin user of the ROOT environment can download AIMMS PRO log files in a
single zip archive and submit it to AIMMS Client support in case of any issue. It also allows to
change the AIMMS PRO log level to track down an issue.
AIMMS PRO Configurator: Link to open AIMMS PRO Configurator.
Page 54 of 123
AIMMS AIMMS PRO - 2
AD Settings
This subsection allows you to specify the Active Directory credentials to allow loging in to non-domain
computers
Page 55 of 123
AIMMS AIMMS PRO - 2
Retention Settings
This section allows you to set retention time (in days) after which a job will be removed from the list.
Page 56 of 123
AIMMS AIMMS PRO - 2
Portal Customization
These settings allows you to customise you AIMMS PRO Portal where you can upload Image for Login
page and your Company logo. You can also specify in-house support contact details which will be
displayed on all Portal Pages. (see below).
You need to specify following fields.
Login Page Background Background Image for the left-hand side of the login screen (JPEG,
PNG or GIF). Image width should be between 640 and 2500 and image height should be between
800 and 2500.
Your Company Logo Logo for all portal pages except login page (JPEG, PNG or GIF). Image
width should be between 10 and 120 and image height should be between 10 and 80.
You can view this image by view current image link and can delete current image by selecting Delete
current image check box.
Support Contact Title The title for the support contact block (plain text).
Support Contact Text The text for the support contact block. This can contain any HTML.
Page 57 of 123
AIMMS AIMMS PRO - 2
The button Save Settings validates and save the settings. You must restart the services in order to see
these changes on Portal.
Back to top
Page 58 of 123
AIMMS AIMMS PRO - 2
Tunnels
This section allows you to configure your tunnels to any TCP-enabled applications running inside the
firewall.
For more details please go to Tunnel configuration
Page 59 of 123
AIMMS AIMMS PRO - 2
Log Management
Log Management is the page at AIMMS PRO Portal (starting from AIMMS PRO 2.11) which is available
only for admin user at ROOT environment. So to access this page, you need to login as a admin user to
ROOT environment, then click on menu item Configuration and then click Log Management.
This page consists of two sections.
Download logs and crash dump files
This section allows admin user to download log and crash dump files for this AIMMS PRO instance. User
needs to select the time span for the downloaded files. By default, the time span is set to the last day,
but it is possible to also download all files or files for specific period. To download files for the particular
period, select Specific dates in the time span drop-down and then fill the start and end dates in the
form that appears.
Please note that time span means the files that were last modified in that period. So if some files were
modified after the period, they would be filtered out.
After pressing the Download logs button, the user will get a zip archive with the files. That file will
contain at least one of the following components:
componentVersion.txt the file with the list of AIMMS PRO components versions. That file is used
by AIMMS Client Support to figure out if some issue has already been fixed in the next releases of
AIMMS PRO
Log the folder with the log files. May not be present if there are no logs for the selected time
span.
ErrorReports the folder with AIMMS crash dumps. May not be present if there are no crash
dumps for the selected time span. Please note that AIMMS Version should be at least 4.22 in
order crash dumps to be available.
Page 60 of 123
AIMMS AIMMS PRO - 2
Logs settings
In this section an admin user may change log level for different components of AIMMS PRO. To change
the log level, select new value in the dropdown and press Save Settings. Please take into account that
the settings wont be applied immediately, it may take up to 10 seconds before logs are written with the
new settings.
The components are the following:
AIMMS Sessions change this setting if you need more logs about the state of your solver or data
sessions.
Backend change this setting if you need more information about the behaviour of the AIMMS
PRO itself. For example, if you experience problems with permissions for an application.
Configurator setting for AIMMS PRO Configurator log level.
WebUI corresponds to the WebUI logs. Change it if you need to understand better what is
happening within your WebUI application.
Portal change this setting if you need more (or less) logs for PRO Portal itself. Please note, that
WebUI logs and logs for WS-Proxy have separate settings.
WS Proxy log setting for websockets proxy. Change this setting to figure out issues with tunnels
or connections to the license server.
WAR Launcher generic web part of AIMMS PRO log setting. Probably, you almost never will
need to change this setting.
Page 61 of 123
AIMMS AIMMS PRO - 2
Please note that in case of the issues it makes sense to increase log level for several components. For
example, if you have issues with a WebUI app, you may want to set log level for AIMMS Sessions,
Backend and WebUI to trace. In case of general problems with a desktop app set log level to trace for
Backend and WS Proxy. And if you have issue with a solver session, change log settings for Backend,
AIMMS Sessions and WS Proxy. And, of course, you may just set all setting to the trace level, reproduce
an issue and then restore settings to defaults. Actually, thats the advised approach.
The log levels influence the amount of information you get in the logs. It goes from top to down: trace
level gives you a lot of information, error level gives you very little information. It does not make sense to
have log settings at trace level, because not only your disk space will be eaten very fast, but AIMMS
PRO will also work slower, especially solver and data sessions. So after reproducing an issue with log
level set to trace, we advice you to set it back to info level.
If the settings for a particular component cannot be read (e.g. you have very old installation), you will see
a message saying Could not parse config file. Please restore it to defaults.. In this case the logs are
still written, you just cannot change the settings for that component from the portal. In order to be able to
change them, restore settings for that component to defaults.
User can reset settings for a particular component or for all components at once to defaults using
corresponding buttons. This may be useful in case of upgrade from an old AIMMS PRO version or when
logs settings were changed in order to track a specific issue and now log levels may return to their
default values.
Page 62 of 123
AIMMS AIMMS PRO - 2
Linking Environments to Active Directory

Domains
The AIMMS PRO framework allows you to link any environment to an Active Directory domain. This can
be described in two scenarios,
a) Link to Active Directory for AD Member Servers.

b) Link to Active Directory for Non-AD Member Servers.
Page 63 of 123
AIMMS AIMMS PRO - 2
Link to Active Directory for AD Member

Servers
If your PRO server is a member server of your Active Directory domain, setting up the link is
straightforward: push the link icon on the right side of the environment box in the users tab of the AIMMS
PRO Portal. This will open a dialog in which you must specify the name of the Active Directory domain
and the authentication URL for the Active Directory. Typically, the default values provided by the dialog
will be ok already. If the server is a member of the Active Directory itself, the default value that is filled in
for the Active Directory domain is the name of the domain the AIMMS PRO server is a member of. The
Authenticator URI will automatically point to the AIMMS PRO Server.
Browser configuration
Below, you can find the configuration that needs to be done to the browsers of the AIMMS PRO users.
You will need to go through these steps for HTTP as well as for HTTPS.
IE: Add example.com to the Local intranet zone. For this, click the Settings Gear in IE->Internet
Options->Security->Local intranet->Sites->Advanced. Then add the url of the AIMMS PRO Portal
(example: http://example.com).
Google-chrome uses the IE configuration steps above.
Firefox: go to about:config, say youll be careful, change the value for network.negotiate-
auth.trusted-uris into https://,http://example.com and the value for network.negotiate-
auth.delegation-uris into http://example.com
Note for IT administrators

To reduce the hassle for your users, you could propagate this setting as a Windows Group Policy. For
more information, visit the Adding Sites to the Enhanced Security Configuration Zones page.
Single Sign-on
After enabling an environment for Active Directory authentication, any user navigating to the AIMMS
PRO portal will be logged in automatically (without seeing the login screen) with his/her Active Directory
account. As a result of a successful authentication, the PRO server will create a corresponding user
within the Active Directory enabled environment. In order to log in as a different user or on a different
environment, the user should log out. When that happens (manually logout), the user will be returned to
the AIMMS PRO login screen.
Page 64 of 123
AIMMS AIMMS PRO - 2
Single Environment for Each Domain
Because of the way the single sign-on procedure works, you should only have a single environment
linked to any particular Active Directory domain. If you try to link another environment to an Active
Directory domain which already has an environment linked to it, you will see a corresponding error
message and your changes will not be saved.
Role-based Authentication
When you add groups to an Active Directory enabled environment of which the name matches the name
of a security group within the Active Directory domain,
logged on users will be dynamically added to the user groups within the environment that correspond to
security groups of which they are a member. When the group membership changes upon a next logon,
the group membership within the AIMMS PRO environment will change accordingly. Group membership
of the admin group of the environment or groups within other environments will not be affected by this
dynamic group membership modification mechanism.
Please note that User Group names in AIMMS PRO are case sensitive, i.e., the name of the Active
Directory security group and the PRO group have to match in a case sensitive manner for AIMMS PRO
to recognize it correctly.
On-demand User Information Retrieval
After you link an environment to an Active Directory, the environment will not be populated with all users
and security groups from the Active Directory. When a user logs in via an environment that is linked to
an Active Directory, AIMMS PRO will only check if any of the Active Directory security groups that the
user is a member of, matches with a user group in AIMMS PRO. If a matching user group is found, the
user is automatically added to this user group in the environment. When no matching groups can be
found, the user will be denied access to the AIMMS PRO server. This means that in order to work with
role-based authentication, you must first add a user group to the environment for each Active Directory
security group that is relevant.
Time before user changes are propagated to the PRO server
AIMMS PRO uses the SPNEGO protocol to obtain a Kerberos ticket for an AD user on behalf of the PRO
server. The PRO server retrieves the user info, and the Active Directory groups of which the user is a
member from this Kerberos ticket. The ticket is requested by, and cached at, the client computer from
which the user connects to the PRO server, and passed on to the PRO server without reconnecting to
the Active Directory KDC to obtain a refreshed Kerberos ticket until the lifetime of the Kerberos ticket
has expired. Hence, the speed by which the PRO server will be updated with modified group
membership is determined by the Kerberos ticket lifetime that is specified within your Active Directory
domain.
Page 65 of 123
AIMMS AIMMS PRO - 2
Project Publishing Rights for Active Directory Users
In order for a user to be allowed to publish AIMMS projects, the user needs to be a member of the
AppPublishers group in the ROOT environment. However, Active Directory users are only added to user
groups in the environments that correspond to the Active Directory security groups they are a member
of, after they login for the first time. This means that before you can add a specific Active Directory user
to the AppPublishers group, this user must first have logged in once to the AIMMS PRO Framework.
After this, you can give app publishing permissions to this user with the following steps:
select the environment corresponding to the Active Directory,

select any of the user groups this user is a member of,
select the ROOT environment (this will not change the list of users, but only the list of user
groups), and
drag the user into the AppPublishers user group.
Following the same steps, but only dragging the user into the AimmsPublishers group will give AIMMS
version publishing rights to the Active Directory user.
Page 66 of 123
AIMMS AIMMS PRO - 2
Link to Active Directory for Non-AD Member

Servers
The AIMMS PRO framework also allows setting up a link to an Active Directory domain, if the PRO
server is not a member of the Active Directory domain. In that case, some additional steps are required:
1. Your IT department needs to set up a service account, with rights to delegate to any service using
Kerberos.
2. You need to specify the credentials of this service account in the AD settings section under the
Configuration Menu of AIMMS PRO Portal.
3. You need to associate the Service Principal Name of your PRO server with this service account
through the setspn command.
4. The users browsers need to be properly configured.
Setting up a service account

As mentioned above your IT department needs to set up a service account, with rights to delegate to any
service using Kerberos. This procedure wont be covered in this manual.
But lets assume that now you have such an account with username ADUser and password
ADPassword. And you have a domain called ADDomain that will be used for your users to access
AIMMS PRO. And your PRO portal is available at host pro.myhost.com.
Set Active directory settings under Configuration menu of PRO Portal

1. Navigate to AD settings under the Configuration menu of the AIMMS PRO Portal.
2. Enter ADDomain in domain field, ADUser in Username field, ADPassword in Password field.
3. Save your configuration by clicking the corresponding button.
Associate the Service Principal Name

To determine the Service Principal Name (SPN) for your PRO server, you must know the DNS name by
which PRO clients will reach the PRO server. This is the host name you specified in the Web URI field in
the PRO Configurator for this node. Assuming this DNS name is pro.myhost.com, the Service Principal
Name you need to associate with the service account will be
HTTP/pro.myhost.com
(please note the capitals used). If the service account username is ADUser within the AD domain
ADDomain, you can associate the SPN with it through the command
setspn -a HTTP/pro.myhost.com ADUser
Page 67 of 123
AIMMS AIMMS PRO - 2
If needed, you can associate multiple SPNs with a single service account. Important notice: do not run
this command for PRO server instances that ARE in the AD domain. Running the command will result in
breaking AD functionality (and this can be fixed by invoking setspn -d ).
You can check which SPNs are associated with the account by entering
setspn -l ADUser
After you have added the association, it may take some time before these changes are replicated
throughout your AD forest.
After you have prepared the service account as above, you can associate a PRO environment with
ADDomain by clicking the link icon on the right side of the environment box. Because your PRO server is
now not a member of an AD domain, the domain field will show noDomain. You should replace it by
ADDomain.
Please see the section Group SIDs (for a Server not in the AD Domain) below in order to understand
how to create user groups for a Server not in the AD Domain.
Useful diagram explaining which AD setup you should choose.
Page 68 of 123
AIMMS AIMMS PRO - 2
Browser configuration
Below, you can find the configuration that needs to be done to the browsers of the AIMMS PRO users.
You will need to go through these steps for HTTP as well as for HTTPS.
IE: Add example.com to the Local intranet zone. For this, click the Settings Gear in IE->Internet
Options->Security->Local intranet->Sites->Advanced. Then add the url of the AIMMS PRO Portal
(example: http://example.com).
Google-chrome uses the IE configuration steps above.
Page 69 of 123
AIMMS AIMMS PRO - 2
Firefox: go to about:config, say youll be careful, change the value for network.negotiate-
auth.trusted-uris into https://,http://example.com and the value for network.negotiate-
auth.delegation-uris into http://example.com
Note for IT administrators

To reduce the hassle for your users, you could propagate this setting as a Windows Group Policy. For
more information, visit the Adding Sites to the Enhanced Security Configuration Zones page.
Single Sign-on
After enabling an environment for Active Directory authentication, any user navigating to the AIMMS
PRO portal will be logged in automatically (without seeing the login screen) with his/her Active Directory
account. As a result of a successful authentication, the PRO server will create a corresponding user
within the Active Directory enabled environment. In order to log in as a different user or on a different
environment, the user should log out. When that happens (manually logout), the user will be returned to
the AIMMS PRO login screen.
Single Environment for Each Domain
Because of the way the single sign-on procedure works, you should only have a single environment
linked to any particular Active Directory domain. If you try to link another environment to an Active
Directory domain which already has an environment linked to it, you will see a corresponding error
message and your changes will not be saved.
Role-based Authentication
When you add groups to an Active Directory enabled environment of which the name matches the name
of a security group within the Active Directory domain,
logged on users will be dynamically added to the user groups within the environment that correspond to
security groups of which they are a member. When the group membership changes upon a next logon,
the group membership within the AIMMS PRO environment will change accordingly. Group membership
of the admin group of the environment or groups within other environments will not be affected by this
dynamic group membership modification mechanism.
Group SIDs
When the PRO server is not a member server of your AD domain, it will not be able to retrieve the
names of the security groups of which AD users are a member, because such servers do not have, or
need to have, a direct connection to your Active Directory infrastructure. In such a case, the server will
have access to the Security Identifier (SID) of any group of which the logged-on user is a member. In
such a case, you should enter the group SID of any AD security group you want to link to the PRO
Page 70 of 123
AIMMS AIMMS PRO - 2
environment in the description field of the corresponding PRO group. This will allow the PRO server to
also match PRO and AD groups on the basis of SIDs.
Tip: To obtain the AD group SID, use the command psgetsid from the Sysinternals suite.
On-demand User Information Retrieval
After you link an environment to an Active Directory, the environment will not be populated with all users
and security groups from the Active Directory. When a user logs in via an environment that is linked to
an Active Directory, AIMMS PRO will only check if any of the Active Directory security groups that the
user is a member of, matches with a user group in AIMMS PRO. If a matching user group is found, the
user is automatically added to this user group in the environment. When no matching groups can be
found, the user will be denied access to the AIMMS PRO server. This means that in order to work with
role-based authentication, you must first add a user group to the environment for each Active Directory
security group that is relevant.
Time before user changes are propagated to the PRO server
AIMMS PRO uses the SPNEGO protocol to obtain a Kerberos ticket for an AD user on behalf of the PRO
server. The PRO server retrieves the user info, and the Active Directory groups of which the user is a
member from this Kerberos ticket. The ticket is requested by, and cached at, the client computer from
which the user connects to the PRO server, and passed on to the PRO server without reconnecting to
the Active Directory KDC to obtain a refreshed Kerberos ticket until the lifetime of the Kerberos ticket
has expired. Hence, the speed by which the PRO server will be updated with modified group
membership is determined by the Kerberos ticket lifetime that is specified within your Active Directory
domain.
Project Publishing Rights for Active Directory Users
In order for a user to be allowed to publish AIMMS projects, the user needs to be a member of the
AppPublishers group in the ROOT environment. However, Active Directory users are only added to user
groups in the environments that correspond to the Active Directory security groups they are a member
of, after they login for the first time. This means that before you can add a specific Active Directory user
to the AppPublishers group, this user must first have logged in once to the AIMMS PRO Framework.
After this, you can give app publishing permissions to this user with the following steps:
select the environment corresponding to the Active Directory,

select any of the user groups this user is a member of,
select the ROOT environment (this will not change the list of users, but only the list of user
groups), and
drag the user into the AppPublishers user group.
Page 71 of 123
AIMMS AIMMS PRO - 2
Following the same steps, but only dragging the user into the AimmsPublishers group will give AIMMS
version publishing rights to the Active Directory user.
Page 72 of 123
AIMMS AIMMS PRO - 2
Tunneling support
AIMMS PRO allows the AIMMS PRO Client to connect to the AIMMS license server and the AIMMS PRO
backend via a websockets proxy running on the web port of PRO (the only port that needs to be opened
in case PRO is running behind a firewall, by default 8080). By using the PRO Configurator to enable the
tunneling functionality, any port and host reachable by PRO (but not by the client) can be made available
via the websockets proxy.
Page 73 of 123
AIMMS AIMMS PRO - 2
General Design
AIMMS PRO consists of four components:
License Server,
Backend,
Web and
Configurator
Only the Web component has a port that needs to be exposed to the outside world. Its an HTTP port in
Web component. AIMMS PRO allows traffic to any TCP socket behind the firewall to be proxied via the
HTTP port.
AIMMS PRO Configurator allows administrator to change all needed configuration required for running
AIMMS PRO. AIMMS PRO Configurator has a section called Tunneling. For configuration workflow see
Configuration section of this document.
Based on the configuration provided using AIMMS PRO Configurator, the Web component has a
mapping of websocket URIs to TCP sockets. When the websocket connection is opened, a security
check (details are below) is performed and the connection to the specified TCP socket is opened and all
traffic goes through the websocket to and from that TCP socket.
Page 74 of 123
AIMMS AIMMS PRO - 2
The Client application (e.g. AIMMS Model) needs to be changed in order to support tunneling through
websockets proxy. The changes that need to be made are described in Changes to AIMMS model
section.
Page 75 of 123
AIMMS AIMMS PRO - 2
Tunnel configuration
Starting from AIMMS PRO 2.16, PRO Portal allows Admin users (users who are member of admin group
under ROOT environment) to configure tunnels to any TCP-enabled applications running inside the
firewall. The look of this section can be found below.
Note: In lower AIMMS PRO versions (< 2.16), tunnels can be configured through AIMMS PRO
Configurator.
The proposed workflow for adding a new tunnel is the following:
1. Administrator opens AIMMS PRO Portal in a browser (by default that would be
http://myProHost:8080)
2. He or she navigates to configuration menu and then to a section Tunnels
3. In that section administrator clicks Add a new tunnel link and an input form appears (see the
image above).
4. Administrator inputs all three required parameters URI context path, Socket address and User
Groups (see the detailed information about parameters below).
5. Administrator saves the configuration and PRO Portal validates the input.
6. If the input is correct the tunnel can be accessed immediately. Otherwise administrator sees
validation errors and needs to fix the configuration to make it valid.
Existing tunnel can be modified or deleted using the same section in PRO Portal.
The configuration parameters for the tunnel are the following:
Page 76 of 123
AIMMS AIMMS PRO - 2
1. URI context path path in the URI of the AIMMS PRO Web sockets proxy to which this tunnel will
be mapped. URI context paths are case-insensitive (so Context and context point to the same
path).
2. Socket address (TCP) the combination of an IP address (or a host name) and a port number for
the proxied application.
3. User Groups semicolon (;) separated list of AIMMS PRO users that can use this tunnel.
4. The default is .@. meaning all PRO users are authorized to use this tunnel.
Specific groups go in the form Group@Environment.
.*@Environment means that any user with permissions to access that environment can use
that tunnel.
Group@.* means that user belonging to that group on any environment can use that tunnel.
Example scenario
PRO administrator wants to create a tunnel with the following parameters:
1. Tunnel works for a database that is available on host myDatabaseHost at port 1433
2. It is accessible for users that belong to the group AppPublishers from environment MyEnv or
AppUsers from environment AnotherEnv
3. Proxy can be accessed via URI ws://myProSHost:8080/ws-proxy/myDatabase
In order to configure such a tunnel PRO administrator does the following:
1. Opens PRO Portal, navigates to Configuration menu and then to a Tunnels

2. Clicks Add a new tunnel and then inputs the following parameters:
3. URI context path myDatabase ,
Socket address myDatabaseHost:1433,
User Groups AppPublishers@MyEnv;AppUsers@AnotherEnv.
4. Clicks Save and then after validation new configuration is saved and the proxy is available.
Please note that in order to work with the proxy you also need to modify your client application so that it
connects via web sockets, simply pointing application to ws://myProSHost:8080/ws-proxy/myDatabase
instead of myDatabaseHost:1433 wont work. The required changes are described in Changes to AIMMS
model.
Validation rules
The validation rules for the tunnel configuration are the following:
1. URI context is unique. Please not that context paths backend and license are used internally by
AIMMS PRO so those paths are reserved.
2. Socket address should be in the form ipAddress:port (e.g. 127.0.0.1:1433) or host:port (e.g.
localhost:1433).
Page 77 of 123
AIMMS AIMMS PRO - 2
3. User Groups and Environments should be present in the list of user groups and environments that
can be viewed/configured on PRO Portal.
Page 78 of 123
AIMMS AIMMS PRO - 2
Security
AIMMS PRO provides the security in the following way:
1. You can configure all your connections to go via HTTPS instead of HTTP.
2. For every request you need to provide a PRO Ticket that can be obtained from AIMMS PRO
Backend by providing username and password or using Active Directory. Ticket has expiration
date and needs to be periodically renewed.
3. PRO Ticket contains user ID so that PRO backend can check permissions. Every user and/or user
group may have different permissions. User may belong to one or more user groups.
The AIMMS PRO Tunneling uses the existing security model:

1. All connections to websockets proxy can go via HTTPS
2. For every connection to websockets proxy a PRO Ticket needs to be provided.
3. Administrator can restrict usage of websockets proxy only to some PRO user groups and/or some
environments as described in Configuration.
What ports need to open to the external world?
If your application uses AIMMS PRO Tunneling then the only port that needs to be exposed is HTTP for
AIMMS PRO Portal. All other application may stay behind the firewall.
How to setup HTTPS connection to AIMMS PRO Portal/AIMMS PRO

Configurator
Refer to this section of AIMMS PRO manual for information on HTTP/HTTPS setup for AIMMS PRO
Portal.
If you also want to secure access to AIMMS PRO Configurator then change configurator.properties file in
Config subfolder of your AIMMS PRO data folder (by default that would be C:\ProgramData\AimmsPro\
Config\) and restart AIMMS PRO Configurator Service.
How to make sure that tunnels configuration is not altered
AIMMS PRO reads tunnels configuration from AimmsPROWeb.json that is located file in Config
subfolder of your AIMMS PRO data folder (by default that would be C:\ProgramData\AimmsPro\Config\).
You may use some tool to parse that JSON file and make sure that the following section is correct:
{
"server": {
...
"webSocketsProxy": {
Page 79 of 123
AIMMS AIMMS PRO - 2
"socketBufferSize": "262144",
"tunnels": [
{
"context": "context",
"socketHost": "someSocketHost",
"socketPort": "234",
"userGroups": "admin@ROOT;users@ROOT"
}
]
},
...
},
...
}
Please note that this file should be secured in such a way that nobody from the outside can modify it.
Who can change tunnels configuration
AIMMS PRO Configurator requires login using username and password for admin user at ROOT
environment on PRO server. It means that only that user may configure AIMMS PRO. Password for that
user can be changed in PRO Portal.
Monitoring the PRO Configurator logs
AIMMS PRO Configurator logs all changes to PRO configuration at debug level. In your log file (by
default that would be C:\ProgramData\AimmsPRO\Log\ AimmsPROConfigurator.log, see corresponding
PRO manual section for details) you will see messages similar to this one:
10:10:14.441 [qtp1169794610-21] DEBUG c.a.p.c.s.config.ConfigServiceImpl.saveConfig():62 Saving
config PROConfig{authenticationConfig=AuthenticationConfig{ticketExpirationTime=86400},
publishingConfig=PublishingConfig{, clientLicenseProfile=licenseserver:3400,Client},
serverConfig=ServerConfig{proLicenseProfile= licenseserver:3400,ProLicense,
listenPorts=[com.aimms.pro.configurator.dto.config.ListenPortConfig@ce00a2a6],
tunnels=[TunnelConfig{context=mssql, socketAddress=sqlserver:1433, userGroups=Domain
Users@PDT}]}, serverNodes=[ServerNodeConfig{host=proHost, capacity=1,
internalUri=tcp://proHost:19340, webUri=proHost}],
storageConfig=StorageConfig{storageDirectory=C:/ProgramData/AimmsPro\Data\Storage},
portalConfig=PortalConfig{httpPort=8080, httpsPort=null, pkcs12File=, keystorePassword=},
adConfig=ADConfig{domain=, username=, password=},
sessionConfig=SessionConfig{jobRetentionInDays=30, defaultLevel=5,
queuePriorities=[QueuePriority{priority=5, user=., appName=., appVersion=.*}], queueRules=[]},
workerProfiles=[WorkerProfile{capacity=1, name=Default, profile=licenseserver:3400,Server}]}
As mentioned above only one user admin@ROOT may access the Configurator so you always know
the user who changed the configuration.
Page 80 of 123
AIMMS AIMMS PRO - 2
You may change logging settings for com.aimms.pro.configurator.service.config.ConfigServiceImpl so

that it outputs log to a separate file (or a database). Please refer to logback documentation for further
details.
Page 81 of 123
AIMMS AIMMS PRO - 2
Changes to AIMMS model

As mentioned above in order to work with the websockets tunnel you also need to modify your AIMMS
model:
1. The tunnel needs to be created; a socket on localhost is opened and the AIMMS PRO library will
tunnel this to the websocket endpoint.
2. The original code that connects to the target server needs to be modified to connect to the localhost/
port instead.
3. The tunnel should be closed to free up resources when it is no longer necessary.
Important things to check when setting up a database tunnel

The correct driver should be installed on the server
The correct driver should be specified in the connection string (as it is available on server).
When running multiple SQL Server instances on the same machine, only one of those instances is
running on the default port, others run on different ports.
Try to create the correct connection string (using the ODBC dialogs etc or DB4) on the server
before testing with AIMMS.
Make a small AIMMS model that just connects, no other complex stuff.
Tunnel creation
Use the following AIMMS PRO Library procedure:
tunnel::TunnelStart( @in contextPath : string )
Calling the start procedure will effectively connect to ws://myProSHost:8080/ws-proxy/ and open up a
listen socket on the localhost and return the portNumber. Under the hood, the server will verify ticket
validity, etc. and potentially raise an error to indicate starting the tunnel failed.
Change the target server endpoint
We will take as a first example an AIMMS model with an ODBC connection string like this:
DBConnectString:="Driver=SQL
Server;Server=sqlserver.example.com,1433;Database=testDB;Uid=tester;Pwd=test123;"
It needs to be altered such that it connects to the local tunnel entry-point like this:
DBConnectString:=FormatString("Driver=SQL
Server;Server=localhost,%i;Database=testDB;Uid=tester;Pwd=test123;",
tunnelPortNumber);
Page 82 of 123
AIMMS AIMMS PRO - 2
As a second example:
DBConnectString:="DRIVER=Oracle in
OraDB12Home1;dbq=oracle.example.com;UID=tester;DSN=OracleTestDB;Pwd=test123;"
;"
It needs to be altered such that it connects to the local tunnel entry-point like this:
DBConnectString:=FormatString("DRIVER=Oracle in
OraDB12Home1;dbq=localhost:%1;UID=tester;DSN=OracleTestDB;Pwd=test123;",
tunnelPortNumber);
Note the differences between these examples; the connection string should be built according to the
specifications of the database vendor.
Tunnel shutdown
Use the following AIMMS PRO Library procedure:
tunnel::TunnelStop( @in portNumber : parameter )
Page 83 of 123
AIMMS AIMMS PRO - 2
Known issues
The current state of AIMMS PRO Tunneling is that the so called happy flow works. It means that it is
possible to develop AIMMS models that use this functionality but error handling is not user-friendly yet
and you need to close the tunnel implicitly.
Known bugs/things not yet operational:
The actual tunnel is setup upon first connect from the client; if an error occurs on pro-level, e.g.
not allowed to use tunnel, no proper error message is given, instead the socket is just closed and
the client connecting (e.g. the ODBC SQL driver) will give an error, saying it is not able to connect
When you have started a tunnel, you must close it as well, otherwise this will cause a hang when
trying to exit AIMMS. It is possible to circumvent this by calling pro::tunnel:TunnelStopAll() in
pro::LibraryTermination.
Page 84 of 123
AIMMS AIMMS PRO - 2
General Remarks
Case Sensitivity
AIMMS PRO 2.0 is case insensitive, meaning that the values test and Test are treated as the same
value by AIMMS PRO 2.0. Please note that this was not yet the case with AIMMS PRO 1.0. This case
insensitivity is valid for all input parameters: user names, environment names, group names, AIMMS
application names and versions, the strings in the execution and priority rules structures, etc. The first
time any of these parameters is created, the case is saved, but after that, any attempt to create another
parameter with the same name, but with a different case will not succeed (failing or returning the already
existing name, depending on the situation).
It is very important to start and stop AIMMS PRO services through AIMMS PRO Configurator only in
order to get configuration changes propagated in the configuration files when you change some hidden
configuration in database, else this changes will not be reflected.
Page 85 of 123
AIMMS AIMMS PRO - 2
Commonly Encountered Errors

This section presents the most common errors that can be encountered during the use of an AIMMS
PRO application.
Job finished with errors
Too many retries for starting

could appear because a free server license was not available when AIMMS PRO tried to start the
application. AIMMS PRO attempts to start a job three times before showing this error.
Solution
Make sure that you have enough licenses defined under the Worker profiles section in the AIMMS PRO
Configurator. Also, make sure that the AIMMS Network License Manager is reachable by AIMMS PRO.
Did not get a valid ticket from the server during Active Directory logons
Did not get a valid ticket from the server during Active Directory logon, you may possibly not be a
member of any AD-linked PRO group, and therefore be refused access. Please contact your application
or AIMMS PRO administrator.
Possible cause: As the message suggests, none of the AD groups that the user is part of exists as a
user group in the environment that was linked to AD.
Solution
The environment administrator needs to create a group in the AD linked environment with the same
name as one of the AD groups that the user is part of.
Empty AllIdentifiers
Your AIMMS PRO-enabled model will start displaying undefined behavior when you have a statement to
empty the pre-defined AIMMS set AllIdentifiers in your model. The cause is that this pre-defined set also
includes all identifiers that are in the PRO library. As the correct functioning of the PRO library relies on
these identfiers, your model will start to behave incorrectly if these are emptied.
Solution
Dont use this statement. If you still want to empty all of your identifiers (but not those in the PRO
library), please create a subset of AllIdentifiers first which doesnt include the identifiers in the PRO
library.
Page 86 of 123
AIMMS AIMMS PRO - 2
The icon for the application does not appear on the portal
Youve provided an icon for the application but when opening the list of the applications on the portal
from another host the icon is not displayed
This may happen if you have a cluster of several nodes. Each of the nodes would be running PRO
Portal. The icon for the application will appear only on the portal on which youve uploaded the
application. The application would work fine though.
Solution 1
Open the portal on the node on which the applications were originally uploaded.
Solution 2
Ignore missing icons. The applications are still fully functional.
The jobs page on the portal is very slow
You have hundreds of jobs that youve run or still running. Now youre trying to open the jobs page on
the portal and it takes a lot of time (e.g. 10 seconds) for that page to be fully loaded.
Solution
Delete some jobs that youre not interested in anymore.
Jobs deletion is slow
You have thousands of jobs that youve run. Now youre trying to delete them all on the portal and it
makes your browser freeze for some time or even crash.
Solution
Delete jobs in smaller batches (i.e. select a hundred of jobs, click Delete button, wait until they are
deleted and then delete another hundred.
Using ScheduledAt argument with wrong value leads to created job
Youve used the ScheduledAt argument of the pro::DelegateToServer function. For some reason youve
used a string with the wrong format.The job is scheduled (i.e. launched), you dont get any error, but the
job gets a Created status and never gets out of that status.
Solution
Delete the job, correct the ScheduledAt argument and launch the job again.
Page 87 of 123
AIMMS AIMMS PRO - 2
Error in model after launching an AIMMS client application
The error could come in many forms, but it generally manifests after the application has started loading.
However, the process will throw an error (most likely in the body of LibraryInitialization) and the
application will not be usable (an example of error message can be found below).
Solution
The most probable cause for this is that you are using an outdated version of the AIMMS PRO Library in
your model. Update the library to the latest available version (note that since AIMMS 4.6 the AIMMS
PRO Library is available as a system library; we recommend that you use this approach).
Page 88 of 123
AIMMS AIMMS PRO - 2
AIMMS PRO End-User Portal

The AIMMS PRO portal page is the entrance to all functionality of the AIMMS PRO server. For ordinary
end-users, the portal displays
all applications which they are entitled to use, as well as

the status of any jobs they submitted for those applications and the statistics for those jobs.
The AppLauncher
To be able to use applications from the portal you will first have to install the AIMMS PRO AppLauncher.
If you dont have it, you will find the button for the installation on the Applications page (initially) or the
Getting started page (always).
Page 89 of 123
AIMMS AIMMS PRO - 2
PRO Jobs
Jobs Overview
The Jobs screen of the portal will show you the list of all jobs that you have submitted to the server,
together with their current status, their creation time, their queue or run-time and the server that they are
running on. If you are the administrator, you will not only see the jobs sent by the yourself, but also all
the jobs of all the other users.
Jobs and Requests
Please be aware that requests in the AIMMS User Request Manager in your apps are exactly the same
thing as jobs in the jobs overview in the portal. The terms can be used interchangeably.
Terminating Running Jobs
You can terminate running jobs that take too long to solve, or that you are no longer interested in, either
through the AIMMS PRO Request Manager within a client application, or through the Jobs screen of the
portal. In both cases, you can select the job you want to terminate, and press the Terminate button to
actually terminate the running job(s) on the server.
Inspecting Jobs
Any job that has run successfully, has failed, or has been terminated by the user, will remain visible in
the AIMMS PRO Request Manager and the Jobs screen of the portal. This will allow you to load the
results of any successfully completed request, or you may want to check the log files to inspect what
went wrong with a request that failed to complete successfully.
Deleting Jobs
Eventually, when you have inspected the results or log files, you should delete all completed jobs from
the list. This will free up all resources on the server, such as the input/output cases and log files, that are
kept for every job. You can delete completed jobs either through the AIMMS PRO Requests Manager or
via the Jobs screen in the portal, by selecting the requests you want to delete and pressing the Delete
button.
Please know that deleting many jobs (i.e. hundreds) may be a slow process. You may have to wait a bit,
or even restart your browser window in extreme cases. This is a known issue.
Page 90 of 123
AIMMS AIMMS PRO - 2
Completed jobs can also be automatically deleted. By default, all jobs that are older than 30 days will be
deleted. You can change this setting by modifying the Job retention time value through the Retention
Settings under the Configuration menu.
Page 91 of 123
AIMMS AIMMS PRO - 2
Application Statistics
Both from the Apps and the Jobs page of the PRO portal, you can retrieve statistics about the end-user
applications that you are working with. By selecting the Stats button on either an app on the Apps page,
or a job on the Jobs page, you can get statistics about the corresponding application.
Queued and Running Jobs
On the statistics page of an app you get information about the number of jobs currently in the queue for
that app, both for you and for all users together, as well as the current number of jobs running for that
application.
Historical Runtime Data
In addition, the statistics page will give you an overview of the historical runtime data (all the runs of the
application since it was published; the deleted jobs also count) for the application at hand for a selected
time period and time resolution. Per time slot in the selected period, you will get an overview of
the number of requests submitted,

the average and maximum queue time, and
the average and maximum run time.
How to Interprete
If the average queue times substantially exceed the average run times of your application on a regular
basis, this may be an indication that the number of licenses and other resources assigned to your
application is too low. You may expect that by increasing the capacity of the under-assigned resources
by one, the average queue time will decrease by the average run time.
Page 92 of 123
AIMMS AIMMS PRO - 2
Project Setup
Outline
To prepare a project to be used with the AIMMS PRO platform in its most basic Outline
form, you should perform the following steps:
Add the AIMMS PRO Client and GUI libraries to your project,
Modify the procedures that need to be executed at the server,
Add an action to your GUI that opens the Request Manager page,
Create a .aimmspack file and publish this to the server via the PRO portal as described in AIMMS
Application Management.
In this chapter we will describe each of these steps. In addition, we describe the additional features
offered by the AIMMS PRO framework that will allow you to create customized workflows between your
client application and a server-side session executing your (optimization) requests.
Page 93 of 123
AIMMS AIMMS PRO - 2
Adding PRO Libraries to your Project

Install AIMMS PRO System libraries
From AIMMS 4.4 onwards, the AIMMS PRO libraries are included as system libraries, which you can add
to your project through the File Library Manager menu. If you are upgrading from AIMMS 4.3 or
lower, you are strongly advised to replace any existing PRO libraries that are part of your project by the
PRO system libraries, as the system library version may support features that are not supported by older
AIMMS versions.
Downloading the AIMMS PRO Client library
For AIMMS 4.3 or lower you need to download the PRO libraries from the AIMMS PRO portal, and add
them to your project manually. After logging on to the AIMMS PRO portal, you will find a link on the Help
page to the AimmsPROLibrary.zip file containing the latest versions of the PRO Client and GUI libraries.
The PRO Client library provides a fixed interface to the model, through which you have access to the
functionalities offered by the PRO backend server. As the functionality of the back-end server may
change over time, this library will be updated automatically during deployment of your model. The PRO
GUI library offers standard PRO dialog boxes such as the PRO Request Manager and the PRO Progress
Window and depends solely on the (fixed) modeling interface offered by the PRO client library. The PRO
GUI library will therefore not be updated automatically, allowing you to make changes to it as required
for your project.
Adding the Client Library
After unzipping the contents of this zip file to the AimmsPROLibrary folder within the project folder of the
AIMMS project you want to PRO-enable, you can add this AIMMS library to your project via the Library
Manager. Keep in mind that this library is created with AIMMS 3.11, which is the minimal required
version to work with AIMMS PRO. You should never make any changes to the AIMMS PRO Client
library, because, at runtime, the AIMMS PRO Framework will automatically update the client library to
the latest available version, both client-side and server-side.
Adding the GUI Library
The AimmsPROLibrary.zip file also contains the AIMMS PRO GUI library, which unpacks into the
AimmsPROLibrary/AimmsProGUI folder. If you want to make use of the PRO User Request Manager or
the PRO Progress Window, you should add the PRO GUI library to your project as well. The PRO GUI
library will never be updated by the AIMMS PRO Framework. This allows you to localize the windows
contained in the PRO GUI library, or to modify and integrate them into your own application. Note that
the AIMMS PRO GUI library is already prepared for localization through the localization support offered
by AIMMS.
Page 94 of 123
AIMMS AIMMS PRO - 2
Basic AIMMS PRO Workflow

Basic Usage
In its most basic form, AIMMS PRO allows you, from within the PRO client application, to dispatch an
optimization request to the server, which will be scheduled for execution by a server-side AIMMS
session. By default, the PRO client library will transfer the application state between the client- and
server-side session by means of AIMMS case files. This will cause the server-side session to start from
exactly the same state as where the request was made in the client-side session. When the server-side
session is finished, the output results will be stored for the client session to retrieve, and the client
session will be notified that the request has completed. The end-user will then be able to load the output
results via the Request Manager dialog that is part of the PRO GUI library.
Other Workflows
Obviously, the AIMMS PRO framework allows you to implement other workflows between the client- and
server-side sessions. The additional features that are necessary to take more control over the interaction
between the client-side and the server-side sessions are described in Advanced AIMMS PRO workflows.
Modify Procedures
Any procedure that you would like to execute in a server-side session instead of within the client
session, should be modified by adding specific PRO-related code at the top of the procedure. Typically,
such procedure calls will involve optimization of a mathematical program, as a PRO client session does
not support optimization. However, you can also dispatch other computationally intensive tasks that do
not involve optimization to a server-side session. In its most basic form, to PRO-enable your project, you
should add the following code at the top of the procedure that you want to be executed in a server-side
session:
if pro::DelegateToServer then
return 1;
endif;
The behavior of this function varies, depending on whether it is running client-side or server-side.
Client-side Behavior of pro::DelegateToServer
The following section explains what happens on the client side when the pro::DelegateToServer
procedure is called from the AIMMS application.
When the pro::DelegateToServer statement is encountered, behind the scenes, it:
Page 95 of 123
AIMMS AIMMS PRO - 2
1. creates a case of type AllIdentifiers containing the current state of the application and sends to the
AIMMS PRO server.
2. prepares a message containing the name of the procedure (containing the DelegateToServer
statement) and all its arguments and sends to the AIMMS PRO server. This message will lead to a
complete re-execution of the procedure at the server-side worker session.
3. Because it is running client-side, the statement will return the numeric value 1. Since this value is
used in an if condition that has return 1 on the true branch, the statements after DelegateToClient
will not be executed.
Server-side Behavior of pro::DelegateToServer
When the PRO server receives the request, it queues the job, and eventually starts up a server-side
instance of the project. This session then loads the case and executes the same procedure call that
contains the pro::DelegateToServer statement on the client-side that initiated the server-side session.
On the server-side, the pro::DelegateToServer statement will return a value of 0, which results in the
original content of the procedure being executed. When the procedure containing the
pro::DelegateToServer call has finished executing, the PRO server will create a case file containing the
values of AllIdentifiers and will send a message to the client that the job is finished.
Displaying the Request Manager
The final modification required in your AIMMS model is that at some place (for exmaple, a button on a
page, or a button on the toolbar) you should add an action that opens the Request Manager contained in
the PRO GUI library. To open the Request Manager, you should call the procedure
guipro::OpenRequestManagement, which will open the Request Manager as a dialog. This will allow
end-users to get an overview of all the tasks that are finished or still running. Furthermore, the Request
Manager allows the end-user to download the results of finished jobs into the current session, to
terminate running jobs, and to delete finished jobs.
Create a .aimmspack File and Publish
After you made the above modifications to your project, the only step that is left is to create a
.aimmspack file of the project and publish it via the AIMMS PRO Portal. For more details about
publishing via the portal, see AIMMS Application Management.
Page 96 of 123
AIMMS AIMMS PRO - 2
Conversion Guidelines
Because part of the execution of your project is now disconnected from the computer of the end-user,
you must keep in mind that the PRO-enabled project itself, and more specifically, the procedure that is to
be run on the server (i.e. the procedure that contains the call to pro::DelegateToServer), will be subject
to certain limitations. Below you will find guidelines for the constructs to avoid when PRO-enabling your
model, and ways around certain limitations.
Constructs to Avoid
When preparing your AIMMS project for PRO, there are a couple of things you must not forget to ensure
that your project is compatible with running in PRO:
Do not use any of the dialog functions for output (e.g. DialogMessage, DialogError, etc.) in any
procedure that is being run on the server, because server-side sessions do not provide any
graphical output back to the client.
Do not use any of the dialog functions for input (e.g. DialogAsk) in any procedure that is being run
on the server, because the client session will not be able to display these questions.
Do not read anything from spreadsheets like Excel or OpenOffice via the AIMMS spreadsheet
functions in any procedure that is being run on the server, as these products will most likely not be
available on the server where your application will be executed, and will only work on a user
desktop.
Do not refer to absolute file or directory paths to store or retrieve persistent information in any
procedure that is being run on the server, as these files will most probably not be available on the
server where your model will be executed.
Do not use the user management built into AIMMS itself. AIMMS PRO is already offering user
management; using the user management in AIMMS will lead to a duplicated login sequence on
the client side, and will prevent server sessions to start altogether.
Do not remove the MainInitialization procedure in your project, because to function correctly,
AIMMS PRO requires this procedure.
Do not call pro::DelegateToServer or other methods from the PRO client library, before the
procedure pro::LibraryInitialization has been called by AIMMS during project startup. That means
that you should not use any PRO functionality in MainInitialization or in the LibraryInitialization
methods of other libraries that are part of your application, unless you have made sure that
pro::LibraryInitialization has been called explicitly.
Do not enter absolute paths in the SOURCE FILE attribute of sections and modules of your model,
as installation locations of both AIMMS and your project will be different from the stand-alone
scenario. Specifically, if you want to include a predefined AIMMS module, do not enter the
absolute installation path of AIMMS but rather use the environment variable AIMMSMODULES.
Page 97 of 123
AIMMS AIMMS PRO - 2
Symptoms When You Violate These Limitations
When publishing your model, AIMMS PRO will perform a verification run of your model. If your model
contains any of the above constructs, this may lead to a publication failure with unexpected or no error
messages at all. For instance, when your MainInitialization procedure contains a dialog box, your model
will hang indefinitely waiting for input, and will eventually time out without any relevant information as to
what caused the failure.
Application Experience
To create a complete application experience, use a custom menu bar for your application, where you
leave out
the File-Close Project menu item. You do not want end-users to be able to close your project and
end up in the stripped down installation free end-user AIMMS.
the Tools-License Configuration menu item. You do not want end-users to be able to make
modifications to the license configuration for PRO-enabled applications.
the Settings-Solver Configuration menu item. You do not want end-users to be able to make
modifications to the solver configuration of the PRO application, even though the PRO end-user
license actually does not allow the usage of any of the solvers.
Page 98 of 123
AIMMS AIMMS PRO - 2
AIMMS PRO and Data Management

Where to Locate Data
You can read data from files that are contained in the same directory as the published model, or in any
of its subdirectories, if such files are exported as part of the .aimmspack file as well. You should,
however, never write persistent data to such files, as a next session may be run from a different location,
or even on a different server. If you need to write persistent data to disk, you should locate such files on
e.g. a network share that can be reached from any server on which your server sessions are running.
PRO Central Data Management
Alternatively, when using the new data management style of AIMMS 3.12 or newer, using Disk Files
and Folders, you will also be able to store case files directly on the PRO server. Whenever you open
the AIMMS Case Manager dialog box from within a PRO client session, three new locations for saving
and loading cases will become visible, as shown in the figure below.
Page 99 of 123
AIMMS AIMMS PRO - 2
PRO User Cases
The PRO User Cases area in the AIMMS Case Manager refers to an application-specific central storage
location on the PRO server that is private to you. The storage location is the same for all published
versions of the same application, so if the published application is upgraded, the data from previous
versions is still available to you. You can access the cases stored in this location, from wherever you
start the application. The data you store here, is not accessible for other users except those that are part
of the admin group.
PRO Shared Cases
The PRO Shared Cases area in the AIMMS Case Manager refers to an application specific central
storage location on the PRO server that is accessible for all users that have permission to run the
application. The storage location is the same for all published versions of the same application, so if the
published application is upgraded, the data from previous versions is still available to all allowed users of
the application. All users allowed to use the application can also access the cases stored in this location,
from wherever they start the application. The shared case area for a published PRO application is
created and assigned the appropriate access rights when the application gets published. Please note
that if any new or existing user has been assign the permission to run the application, then shared cases
which where already created will not be available to this user. If user wants to access these cases then
user must be added to some User Group which has the permission to run the application.
PRO Central Storage
The PRO Central Storage area in the AIMMS Case Manager provides you with a full overview of the
complete central storage area available on the PRO server. Each folder and file in this storage area can
have read, write and execute access rights assigned to specific users and groups within PRO. These
access rights determine whether specific folders or files will be visible to you in the AIMMS Case
Manager, or whether you can write in certain locations. The Case Manager will automatically filter out all
files and folders to which you have no access.
Central Case URLs
You can also programmatically load cases to or save cases from the PRO Central Storage area through
existing AIMMS data management functions such as CaseFileLoad and CaseFileSave. The case URL
for cases stored in the PRO Central Storage area consists of the prefix PRO: (to indicate to the AIMMS
Case Manager that the case should be saved in the PRO Central Storage area), followed by the path in
the central storage area.
User and Shared Case Shortcuts
The PRO User Cases and PRO Shared Cases are just shortcuts to folders into the central storage area:
Page 100 of 123

AIMMS AIMMS PRO - 2
PRO User Cases is a shortcut to the path

PRO:/UserData/environment/user-name/Cases/project-name
PRO Shared Cases is a shortcut to the path
PRO:/PublicData/Cases/
Transferring Files
Besides centrally saving cases in the PRO Central Storage area through the Case Manager, you can
also manually transfer files between your local disk and the PRO Central Storage area through the
functions
pro::SaveFileToCentralStorage
pro::RetrieveFileFromCentralStorage
You can use these functions if your project depends on private files that need to be kept in sync from
wherever you run a client session to the project, or depends on shared files that need to be kept in sync
for all users from all locations. Both functions require a local path as well as a path in the PRO Central
Storage area.
Manipulating PRO Files and Folders
To manipulate files and folders in the PRO Central Storage area, you can use the following functions:
pro::CreateStorageFolder
pro::DeleteStorageFolder
pro::DeleteStorageFile
Access Rights
The functions pro::SaveFileToCentralStorage and pro::CreateCentralStorageFolder have an Access

rights optional permissions string argument through which you can specify the access rights for the files
and folders you create with these functions. When you do not explicitly specify access rights to the files
and folders you create in the central storage area, PRO will automatically only give access to the
currently logged on user.
Specifying Access Rights
To select which users and/or groups should have which access rights, you can call the function
progui::EditAuthorization which is part of the PRO GUI library. This function will open the Authorization
Manager dialog, through which you can modify a new or existing permissions string. You can then pass
this string as the permissions argument to the functions above.
Page 101 of 123

AIMMS AIMMS PRO - 2
Using a Database
For communicating the data between the client and the server session, or between multiple server
sessions, you also have the possibility to use a common database that both instances can access. If you
do want to use a common database for data communication, ensure that you have the required ODBC
drivers on both the server and client side installed. With regards to the server side, keep in mind that
most drivers must be installed separately for the 32-and 64-bit version of ODBC.
Page 102 of 123

AIMMS AIMMS PRO - 2
Advanced AIMMS PRO Workflows

The basic PRO workflow described in Basic AIMMS PRO Workflow can be modified to a great extent to
suit the particular requirements of your application. In this section we describe the capabilities offered by
AIMMS PRO to setup customized workflows:
1. Determining the Application State to Transfer

2. Advanced Usage of pro::DelegateToServer
3. Communication Between client-side and Server-side Sessions
4. Using Messages in Your PRO Applications
5. The PRO Progress Window
Page 103 of 123

AIMMS AIMMS PRO - 2
Determining the Application State to

Transfer
In many cases, it is not necessary to transfer the entire state of your client application to initiate the
server-side session appropriately. In some cases, you may not need to transfer any application state at
all, because the arguments of the procedure call initiating the server-side session already provide all the
information necessary to retrieve the data that is needed to successfully execute the request.
Specifying Case Content
To reduce the amount of data that is sent between the server and the client, or to prevent that data is
transferred at all, you can provide the AIMMS PRO library with information about what data should be
stored in the case files sent back and forth. The mechanisms are slightly different for projects using the
data management style storing all cases in a single .dat file, as opposed to the data management style
where all individual cases are directly stored in separate files on disk. The latter option is only available
in AIMMS 3.12 and later.
Specifying Case Types
For the single .dat file data management style, you can instruct the AIMMS PRO library to use a specific
case type by setting the following element parameters:
pro::ManagedSessionInputCaseType, denoting which case type should be used for data transfer
from the client to the server
pro::ManagedSessionOutputCaseType, denoting which case type should be used for data transfer
from the server to the client
If you do not set these two element parameters explicitly, the AIMMS PRO library will use the predefined
case type All Identifiers by default. This means that the values of all identifiers that do not have the
NoSave property set will be transferred back and forth. If you set any of the above element parameters
explicitly to the empty element, AIMMS PRO will not create and transfer an input, and/or output case file
respectively.
Specifying Case Content
For the data management style using separate files on disk for each case, case content is specified
through a subset of the predefined set AllIdentifiers. You can specify the contents sent in input and
output cases by filling the following sets:
pro::ManagedSessionInputCaseIdentifierSet, for input cases
Page 104 of 123

AIMMS AIMMS PRO - 2
pro::ManagedSessionOutputCaseIdentifierSet, for output cases
If not specified explicitly, both sets will default to AllIdentifiers. If you assign the empty set to any of
these sets, AIMMS PRO will not create and transfer an input, and/or output case file respectively.
Caveats:
pro::ManagedSessionOutputCaseIdentifierSet needs to be assigned during the solver

session.
Make sure that the data of sets and parameters referenced in the index domain attribute of the
variables computed server side and communicated via the output case to the client side, are also
available client side or passed in the output case.
Note: The function ReferencedIdentifiers can be used to find all referenced identifiers in a given
subset of AllIdentifiers and thus extend the identifier subsets pointed to by
pro::ManagedSessionInputCaseIdentifierSet and
pro::ManagedSessionOutputCaseIdentifierSet as needed.
Optional action to be taken after case load
You can specify the action to be taken after a case is loaded client or server side. In the client session,
the action to be taken after a case load is defined by the element parameter
pro::session::PostLoadResultCaseHook. For example, by setting:
pro::session::PostLoadResultCaseHook := 'postProcessComputedResults' ;
the procedure postProcessComputedResults will be executed by the

pro::delegateToServer completion callback procedures that load the result case, and by the
load results button in the Managed Requests dialogue. The element assigned to
pro::session::PostLoadResultCaseHook should reference a procedure without
arguments.
Similarly, the pro::session::PostLoadInputCaseHook can reference a procedure to be executed

in a server session after loading the input case.
Page 105 of 123

AIMMS AIMMS PRO - 2
Saving Log Files
By default, at the end of a server-side session, the messages.log file created during that session will be
stored for inspection within the client session. If you do not want to have this log file saved, you can
prevent this by setting the parameter pro::session::SaveSessionMessages to 0.
Page 106 of 123

AIMMS AIMMS PRO - 2
Advanced Usage of pro::DelegateToServer

pro::DelegateToServer arguments
So far, we have only discussed a basic workflow when using pro::DelegateToServer in your model. You
can influence this workflow by specifying one or more of the optional arguments of this procedure.
procedureName
requestDescription
completionCallback
timeOut
waitForCompletion
inputCase
delegationOverride
authorization
licenseName
priorityAdjustment
scheduledAt
Specifying a Procedure
Through the argument procedureName you can indicate which procedure you want to be called from
within the server-side session, after the session has been initialized by AIMMS PRO. If you do not
specify a procedure name, AIMMS PRO will take the name of the procedure from which the call to
pro::DelegateToServer was made. It can, however, be any procedure currently on your execution stack.
AIMMS PRO will determine the current content of all the arguments of the specified procedure, and use
these to serialize the procedure call, so that it can be re-executed in the server-side session.
Specifying a Description
Through the argument requestDescription you can specify a description of how you want the request to
be described in the Request Manager or the AIMMS PRO portal. If you do not specify a description
yourself, AIMMS will take the name of the current case, followed by the time at which the request was
made.
Specifying a Callback
By providing a callback procedure to the pro::DelegateToServer function, specified through the

completionCallback argument, you can instruct AIMMS to automatically execute the provided callback
procedure, whenever the server notifies the client that it has finished solving the submitted request. The
Page 107 of 123

AIMMS AIMMS PRO - 2
callback procedure that you supply must have a single string parameter as its input argument. This string
parameter will contain the session id of the PRO session. So, execution on the client side of the
following statement
if pro::DelegateToServer( completionCallback: procedureAfterServerFinished ) then

return 1 ;
endif ;
will save a case of the current state, send it to the server, and instruct the server to load the input case
and execute the same procedure on the server. After the server is finished, a message is sent back by
the server to the client, notifying the client that the server is finished. This notification triggers the AIMMS
PRO library to call the procedure you provided as the completionCallback argument.
Predefined Callbacks
The AIMMS PRO library already provides a number of predefined callbacks that you can use. They are:
pro::session::DefaultCallback, notifies the user via the status bar.

pro::session::LoadResultsCallback, automatically loads the results after completion of the request.
pro::session::EmptyCallback, does nothing.
Counting Completed Requests
A good use for a custom callback is when your end-user is sending lots of different instances to the
server (i.e. hundreds). Using a custom callback, you can count the number of instances that were
finished. If you know how many instances you sent to the server, this callback can easily determine
when all tasks you sent to the server are finished.
Counting Completed Requests
To prevent a server session from running indefinitely, the pro::DelegateToServer function provides an
optional timeOut argument. By specifying a value for the timeOut argument, you can control the
maximum time (in milliseconds) that a request is allowed to run. If this timeout is exceeded, the job will
be terminated automatically and will receive a request status of Terminated. If you do not specify this
argument, the default value will be one hour.
Timed-out Sessions
If a session is terminated because the maximum execution time has been reached, the PRO server will
call the fixed callback pro::session::ServerErrorCallback. If you want to have your own callback function
called as well in such cases, you can set this additional callback function via the element parameter
Page 108 of 123

AIMMS AIMMS PRO - 2
pro::session::ServerErrorCallbackHook into AllProcedures. When this time-out is reached, solver

sessions will be killed with error status and case will not be saved in this situation.
Asynchronous
By default, a call to pro::DelegateToServer will be executed asynchronously, that is, when the call
returns on the client, the results of the delegated request are not available by default. A successful call
only means that the request has been successfully queued at the server and will be executed when all
necessary resources are available for the request to run. By specifying callbacks as demonstrated
above, you will get a notification that your request has completed, but these callbacks are, by default,
also executed in a completely asynchronous manner.
Versus Blocking
By setting the waitForCompletion argument to 1, the call to pro::DelegateToServer will block until the
server-side session has been completed or interrupted because of the specified timeout. Upon return,
the completion or error callback will already have been executed. You have now created a synchronous
workflow.
Caveat
You should realize, however, that a call to pro::DelegateToServer will just add your execution request to
the existing job queue at the server, and that it may take a while before it is up for execution. In such
cases, or if the execution of your request takes a long time, the synchronous workflow enforced by the
waitForCompletion argument may not be the best approach in your situation, and it may be beneficial to
redesign your application to use an asynchronous workflow around the requests that need to be
executed on the server.
Using a Shared Input Case
By default, AIMMS PRO will save your application state prior to every request. This is a fine approach if
each request operates on different input data. However, if you want to use PRO, for instance, to run a
large number of scenarios all based on the same input data, saving the same application state for every
scenario is unnecessary and will introduce considerable overhead in space and time to schedule and
execute all requests. In such cases, you can pass a shared input case file reference to be used for all
execution requests through the inputCase argument, and indicate which scenario based on this input
case to execute through the arguments of the procedure call to be run within the server-side session.
Accepted Values
The inputCase argument accepts the following values:
the URL of an existing case stored in the PRO Central Storage area.
Page 109 of 123

AIMMS AIMMS PRO - 2
the id of an input case that was created as the result of a previous call to pro::DelegateToServer.
To determine the internal PRO id of an input case you can call the function pro::session::
CurrentInputCaseID which will return the input case id of the latest started session.
Distributing Work
By default, a call to pro::DelegateToServer will initiate a server-side session within the client session,
and will run locally within a server-side session. Through the delegationOverride argument you can
override the default behavior.
If the value is < 0, no server-side session will be initiated.

If the value equals 0 and the client session is run in developer mode, the PRO library will ask
whether to run locally or initiate a server-side session, or just initiate a server-side session if the
client session runs in end-user mode (default).
If the value is > 0, a new server-side session will only be initiated if the value is greater than the
value of pro::CurrentDelegationLevel.
By specifying values > 0, you can enforce that pro::DelegateToServer will initiate a new server-side
session, even when executed from within an existing server-side session. The value of
pro::CurrentDelegationLevel within a server-side session, equals the value of the delegationOverride
argument within the session that initiated the current server-side session.
Beware
As the value of pro::CurrentDelegationLevel increases in a session in which a delegated call is executed

compared to the session from which is was delegated, you should not use pro::CurrentDelegationLevel
directly in the call to pro::DelegateToServer. More specifically, the call
pro::DelegateToServer(delegationOverride: pro::CurrentDelegationLevel + 1);
will effectively start up new sessions recursively until you reach the number of available AIMMS licenses.
Rather, you should pass pro::CurrentDelegationLevel as an argument of the procedure you want to be
delegated, or assign it to a parameter that is part of your input case, and use either of these in the
delegationOverride argument.
Overriding the License Profile
Through the licenseName argument you can override the default license profile that has been associated
with the published project you are running. If licenseName refers to an existing license profile, that
Page 110 of 123

AIMMS AIMMS PRO - 2
license profile will be used by the server-side session. If licenseName does not refer to an existing
license profile, the default license profile will be used.
Note: Starting from AIMMS PRO 2.12.1, if licenseName does not refer to an existing license profile then
AIMMS will give error message and it will not use default license profile.
Adjusting the Job Priority
By default, your execution requests will be scheduled with a priority that is set by the administrators of
your AIMMS PRO installation. This priority can be dependent on a specific application, on specific users,
or combinations thereof. Through the priorityAdjustment argument, you can instruct the PRO framework
to lower the priority of the request you want to initiate by the specified amount. Note, that you can only
lower the priority of your requests in this way. Attempts to increase the priority of your request will cause
the call to pro::DelegateToServer to fail.
When to use
You can lower the priority of your requests, for instance, when you want to run a large number of
different scenarios and dont want these requests to disturb the execution requests of regular users.
Without lowering the priority of your requests, the requests of regular users may end up remaining
queued unacceptably long.
Scheduling a Session in the Future
By specifying the scheduledAt argument, you indicate to the PRO server, that you want the server-side
session to be scheduled for execution within one minute after the indicated time. The argument should
be a time string in the format YYYY-MM-DD hh:mm:ss, referring to the local time after which you want
the server-side session to be scheduled for execution. Until the scheduled time, the job will be in
Created status, afterwards it will appear in Queued status.
Page 111 of 123

AIMMS AIMMS PRO - 2
Communication Between client-side and

Server-side Sessions
Bidirectional Communication Between Sessions
AIMMS PRO allows two sessions to communicate in a bidirectional, asynchronous way. This is
accomplished by sending messages that serialize procedure calls made in one session, to a queue to
which the other session is listening. When a listening session receives such a message it will deserialize
the message, and execute the corresponding procedure call. The PRO library provides this basic
functionality through the procedure
pro::DelegateToPeer(requestQueue, procedureName, flags)
One or Multiple Peers
You can use pro::DelegateToPeer in procedures for which you want to delegate the execution to another
session in exactly the same manner as pro::DelegateToServer, where the requestQueue must be a
queue to which you know the peer session is listening. If multiple sessions are listening to this queue,
each of these sessions will execute the delegated procedure call.
Specializations
In most cases youll want to send messages from a client session to a server-side session or vice versa.
For these common cases, the PRO library offers two specializations, where you dont have to specify the
queue manually:
pro::DelegateToCurrentSession, delegates a procedure call from a client session to the latest

started server-side session.
pro::DelegateToClient, delegates a procedure call from a server-side session to its corresponding
client session.
Beware
These specializations make use of the internal state of the PRO library to determine whether a
procedure call is made at the client- or at the server-side session and act accordingly. However, if these
specializations are called in a chain of server-side sessions, they may not behave as expected, because
the PRO library is not able to determine unambiguously whether a particular server-side session acts as
a client- or as a server-side session at any particular moment. In such cases, calling
pro::DelegateToPeer with an explicit queue id that is also passed over to the other peer (for instance as
an argument to the procedure in which pro::DelegateToPeer is called) will prevent such ambiguities.
Page 112 of 123

AIMMS AIMMS PRO - 2
Current Session Info
The following functions allow you to retrieve information about the latest started session by calling
pro::DelegateToServer:
pro::session::CurrentSession, the intenal PRO session id.

pro::session::CurrentSessionQueue, the queue through which the client session can communicate
with the server session.
pro::session::CurrentClientQueue, the queue through which the server session will communicate
with the client session.
Message Flags
When delegating a procedure call through pro::DelegateToPeer, you can modify the way in which the
message is being handled by AIMMS PRO by adding one or more message flags:
pro::PROMFLAG PRIORITY, indicates priority message which is also dealt with in between
statements in your model, when your model is already running a procedure.
pro::PROMFLAG SYNC ONLY, indicates that the message should not be handled asynchronously,
but only through an explicit call to pro::WaitForHandledMessages in your model.
pro::PROMFLAG LIVE, indicates that AIMMS PRO will only pass this message to any session that
is currently listening on the indicated queue, and will not store the message for later retrieval when
there are no such sessions.
pro::PROMFLAG REQUEST, message flag used to indicate a request to initiate a session. When
the session-initiating procedure call is handled, the PRO library will also handle any additional
messages with this flag set that are sent from within your model.
pro::PROMFLAG RESPONSE, message flag used to indicate that the server-side session
completed.
pro::PROMFLAG ERROR, message flag used to indicate an error response, that the server-side
session timed-out.
pro::PROMFLAG SESSION, message flag used to indicate that this is not a message of any of the
above types. You can use this flag to wait for framework generated messages.
pro::PROMFLAG USER, the lowest flag value that you can use within your model to design your
own specialized workflows. You can create additional user-defined flags by multiplying
pro::PROMFLAG USER by any power of 2.
If you want to add multiple flags to a call to pro::DelegateToPeer, you should add all relevant
flag values.
Page 113 of 123

AIMMS AIMMS PRO - 2
Waiting for Messages
You can explicitly wait for incoming procedure calls, through the procedure
pro::messaging::WaitForHandledMessages(queueID,flags,timeOut)
This procedure will wait for a given timeOut time for messages that are sent to the specific
queueID and with the indicated flags set. Any messages that satisfy the given criteria will be
handled before the procedure returns, that is, delegated procedure calls encoded in the
message will be executed. The procedure will return the number of handled messages, or 0 if
no messages satisfying the given criteria arrived within the given timeOut. If you do not specify
a queueID, the procedure will listen on all queues. If you do not specify flags, the procedure will
handle all incoming messages.
Synchronous Workflows
By waiting for messages, you can create a synchronous workflow around the optimization requests that
will be executed in server-side sessions. For instance, from within a server-side session you can send a
message to the client session, and wait for a response for a given amount of time before continuing the
execution. This allows you to steer the execution through feedback given by the end-user. By adding
user flags to the message, you can make sure that you only wait for and handle those messages that are
meaningful in the context of your application.
Page 114 of 123

AIMMS AIMMS PRO - 2
Using Messages in Your PRO Applications

The messaging mechanism through which client- and server-side sessions communicate, can also be
used for other purposes in your own PRO-enabled applications. For instance, you can use it to
implement a message bus through which multiple users of the same application can notify each other of
data changes that are also relevant to other users.
Implementing a Message Bus
If you want to introduce a message bus into your application, the following steps are required:
Create a queue.
Start listening to the queue.
Communicate the queue id to other users of your application.
Send messages to other users.
Creating a Queue
You can create a queue by calling the function
pro::messaging::CreateQueue
When creating a queue, you can specify a queue authorization, determining which users can listen and
send messages to the queue. You can create the correct authorization string through the PRO
Authorization Editor, which you can invoke by calling the procedure progui::EditAuthorization.
Connecting to a Queue
Given a queueID of the queue you just created, you can listen to incoming messages on this queue by
attaching it to the connection your application already has with the AIMMS PRO server.
ret := pro::messaging::AddQueueToConnection(queueID, pro::ListeningConnectionId);
The method will return 1 if successful. If you want to stop listening, you can remove the queue
from the connection by calling
ret := pro::messaging::RemoveQueueFromConnection(queueID, pro::ListeningConnectionId);
Page 115 of 123

AIMMS AIMMS PRO - 2
Communicating the Queue to Other Users
Before other users of your application can listen to or send to the message bus just created, you must
communicate the queue id of the queue implementing the message bus to them. To accomplish this, you
can, for instance,
write the queue id to a file and store it to a fixed location in the PRO Central Storage area, or on a
network share all users have access to, or
write the queue id to a database that all other users have access to.
After retrieving the queue id, they can start listening to the message bus by adding the queue to their
connection with the PRO server, as illustrated above.
Sending Messages
All messages on the message bus come in the form of remote procedure call requests, created by
adding the statement
if (pro::DelegateToPeer(queueID: queueID)) then return 1; endif;
to those procedure calls that you want to pass to all listeners on the message bus. You can optionally
add message flags as discussed in the previous section, to influence the way in which messages are
handled by your application, or to create application-specific workflows.
Page 116 of 123

AIMMS AIMMS PRO - 2
The PRO Progress Window

When running your AIMMS project under AIMMS PRO, the regular AIMMS progress window only has
limited usability, as the most computation-intensive parts, namely solving your optimization model, will
take part asynchronously on the server. Nevertheless, the AIMMS PRO GUI library has a built-in
replacement for the regular progress window that will work with remote optimization runs, which allows
you to observe math program characteristics like objective, MIP gap, etc., and lets you stop the remote
optimization in exactly the same way as when you press Ctrl-Shift-S during an optimization run in the
AIMMS desktop version.
Preparing the Use of the PRO Progress Window
Unlike for the regular progress window, you have to slightly modify your model for the PRO progress
window to function. More specifically, the PRO progress window depends on installing a callback
procedure on any MATHEMATICAL PROGRAM you want to observe during a remote optimization run.
For a mathematical program MyModel, you need to set
MyModel.CallbackProcedure := guipro::progress::UpdateCallback;
MyModel.CallbackIterations := 1000;
prior to calling the SOLVE statement. It tells AIMMS that every 1000 iterations (or whatever
number of iterations makes sense for your project) the predefined callback procedure
guipro::progress::UpdateCallback is called during a solve. When instructed by the AIMMS PRO
client application, this callback will collect various characteristics of the model being optimized,
and send these back to the client.
From AIMMS 4.15 onwards you can also base progress information on elapsed time. To do so you need
to set
MyModel.CallbackTime := guipro::progress::UpdateCallback;
prior to calling the SOLVE statement. By default this callback procedure will be called every two
seconds. The frequency is controlled by the option Progress Time Interval which also
determines the time interval for the regular AIMMS progress window.
Page 117 of 123

AIMMS AIMMS PRO - 2
Opening the PRO Progress Window
You can open the PRO progress window through the PRO request manager. If you select any request
that has status running, click the Progress Window button. This will open the AIMMS PRO progress
window, which will try to connect to the running session. Note that, depending on where the server
session is in the solution process, it may take a while before there is an opportunity to notify the server
session.
Implemented Using Messages
The PRO progress window is completely implemented using the messaging functionality discussed in
Using Messages in Your PRO Applications. You can actually examine the underlying code in the PRO
GUI library as an example of how delegated procedure calls are used to communicate between the client
and server session.
Page 118 of 123

AIMMS AIMMS PRO - 2
Debugging PRO-enabled Projects

When you start an application via the portal, the AIMMS PRO AppLauncher will download the
.aimmspack file from the server, extract the contents, and start the installation-free PRO client version of
AIMMS with an end-user license obtained from the AIMMS PRO server. Because a PRO client uses an
end-user license, you are not able to use any of the AIMMS debugging tools to see what is going on in
the client-side of the project in case of problems. To debug a PRO-enabled AIMMS project, you should
start using the development version of your project, using the AIMMS developer version.
Connecting With the PRO Server
To connect a developer version of your project with the PRO server, a number of conditions need to be
met:
The PRO library version included in the development version of your project needs to match the
version provided by the PRO server you are connecting to.
Your development folder needs to contain a file pro_arguments.txt containing
pro::ReadArguments(pro::CL) := data
{ _pro-modelname : MyModel,
_pro-modelversion : 1.0,
_pro-dll-directory : C:\\Users\\<user>\\AppData\\Local\\AIMMS\\PRO\\<Pro
Server>\\AimmsPROLibrary-2.0\\vc120,
_pro-environment : ROOT,
_pro-username : admin,
_pro-tmpfolder : PROTemp,
_pro-endpoint : tcp://MyPROServer.mydomain.com:19340,
_pro-language : 1 } ;
where the various fields should match the model name and version published on the server, with
the PRO environment and user name you want to authenticate with, and with the endpoint through
which your PRO server can be reached.
Opening the Project
When you open the project with an AIMMS developer license in the presence of a pro arguments.txt
file, this file will define all the relevant command-line arguments necessary to setup the projects
connection with the server. When such a file is present, opening the project with a developer license will
Page 119 of 123

AIMMS AIMMS PRO - 2
cause the PRO library to use the contents of this file to properly initialize the project as if it were started
through the portal.
Logging on
The first time the PRO library actually tries to connect to the PRO server, you will be asked to provide
your logon information, as displayed in the figure below. The username and environment will be preset to
the username through which you logged on to the portal. When you click Connect, you will be asked for
your password, after which the connection to the PRO server is made. When you log on via Active
Directory; you do not need to retype your password.
Debugging the Client Session
After this step has completed, you can use the AIMMS debugger to walk through the AIMMS code of
your model and of the PRO library, to actually follow the flow of execution within a client session of your
project, and to detect any errors that may occur at this stage of your project.
Server-side Session Debugging is Hard
When you initiate a server-side session from within your client session, it is nearly impossible to verify
what is going on in such a server-side session when it is started by the PRO server. The only way to get
information from such a session would be by adding lots of log statements, which you can analyze after
the run to detect any problems during the run.
Page 120 of 123

AIMMS AIMMS PRO - 2
Server-side Debugging in Developer Mode
By checking the additional flag I want to manually start up a server-side debug session in the PRO
Logon dialog box, however, the PRO framework will allow you to debug a server-side session within an
AIMMS developer session. By checking the debug option, calls to pro::DelegateToServer will prepare a
server-side session, but will not actually queue it for execution at the PRO server. Instead, it will create
an additional file debug arguments.txt in the project folder. If you startup the project again, the dialog
box below will appear. Here you can select whether you want to debug the server-side session you just
created, or want to return to a regular client session.
Cavaet
When the argument waitForCompletion of pro::DelegateToServer is set to 1, during the setup of

the debug session, AIMMS will not return. Therefore you will need to set this argument to 0
when you setup a server side debug session.
Debugging a Server-side Session
If you requested to debug the server-side session you just prepared, the project will start up in exactly
the same way as it would when it would have been started by the PRO server. At the beginning of the
procedure that will be called by the PRO framework to initiate the server-side session, the AIMMS
execution will stop at the breakpoint illustrated in the figure below.
Page 121 of 123

AIMMS AIMMS PRO - 2
Debugging Your Model
From here on, you can use the AIMMS debugger to track any problems that may occur in your model
due to it being run in a server-side session. You can see what input cases will be read, you can examine
whether all data that you expect to be present actually is, and how running your project under PRO will
influence the optimization tasks that you want to be executed.
Page 122 of 123

AIMMS AIMMS PRO - 2
AIMMS PRO API

The AIMMS PRO API allows you to build custom Apps in Java or C# code using the AIMMS PRO
platform e.g. submit solve jobs from these Apps. Next to AIMMS Windows and Web Apps, this means
you can now deploy AIMMS inside Apps, ideal for e.g. closed loop optimization. In addition, the AIMMS
PRO API allows you to perform most tasks supported by the AIMMS PRO job request manager. For
details, please visit AIMMS PRO API Documentation.
The AIMMS PRO API is tightly coupled with the PRO version. You can download the latest PRO API via
the Help Getting Started menu on the AIMMS PRO Portal.
Page 123 of 123

Aimms Pro 2.16.3.155 PDF

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Aimms Pro 2.16.3.155 PDF

Uploaded by

Copyright:

Available Formats

AIMMS PRO

2 Last update: 2017/07/18

Copyright AIMMS B.V.

Server Administration ......................................................................................................................... 46

AIMMS PRO End-User Portal .............................................................................................................. 89

Project Setup ....................................................................................................................................... 93

AIMMS PRO API ................................................................................................................................. 123

Introduction to the AIMMS PRO Platform

What is AIMMS PRO?

How to use AIMMS PRO?

Some important characteristics of AIMMS PRO

The AIMMS PRO portal

Developers can upload/manage/start applications

Running apps from the AIMMS PRO Portal

Minimum Server Requirements

The minimum server requirements for Windows Server are:

The minimum server requirements for Linux Server are:

Ubuntu 14.04 or Centos 6.6 with Docker Version 1.6.0 or higher

The minimum client requirements are:

Windows 7 or higher, 32-bit (x86) or 64-bit (x64)

License Session Count

Installation and Configuration of the License

Installation Location and Default Ports

The AIMMS Network License Server installs to

C:\Program Files (x86)\AIMMS\AIMMS License Server

and stores its runtime data in

Setting up License Profiles

By default, the AIMMS PRO Server assumes that you make

License Server Maintenance

Overview from left to right

Overview from left to right

Left: the users view

Mid: the provisions given

Lets zoom in on the middle and detail provisions given:

Right: the resources

High availability and failover

Lets aim for high availability and failover.

There is no means yet to improve the availability of the License Service.

Installation of AIMMS PRO on Windows

AIMMS PRO 2.0 Portal Service

Installation and Data Location

Installation of AIMMS PRO on Linux

What needs to be configured

How to start AIMMS PRO as a Docker container

And now you can run AIMMS PRO using command

And to stop AIMMS PRO use

docker-compose -f aimmsProWithPostgres.yml stop

Walk through proposed config file line by line

This line starts the AIMMS PRO image section.

Managing started AIMMS PRO

AIMMS PRO Upgrade

In order to upgrade your existing installation of AIMMS PRO, do the following:

1. Stop AIMMS PRO container if its running.

No additional setup is required.

Installation of License Server on Linux

License Server installation steps.

1. Create a base folder for your License Server installation.

4. Install docker-compose on your server, see https://docs.docker.com/compose/install/ for details.

CONTAINER ID IMAGE COMMAND

Please note the CONTAINER ID of the license-server, in this example it is d2131d499d92

10. For each license execute the following commands:

AIMMS PRO installation steps

1. Create a base folder for your AIMMS PRO installation.

4. Start PRO and Postgres using command docker-compose -f pro.yml up -d