## 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:

• 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 the AIMMS PRO in the AIMMS PRO client application, end-users can initiate optimization runs on the server that are auto-queued 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.

## Installation

AIMMS PRO installation summary

In order to install the AIMMS PRO Framework on your server, you need to follow a number of steps:

• verify the system requirements for running AIMMS PRO,
• install the AIMMS Network License Server,
• configure the AIMMS Network License Server,
• install AIMMS PRO, and
• configure AIMMS PRO.

For an initial setup, we advise to run both the Network License Server and AIMMS PRO on the same server.

### System requirements

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 are:

• Windows Server 2003 64-bit (x64), or Windows Server 2008 64-bit (x64)
• sufficient network bandwidth (if available, 1 Gb network advised)
• minimum of 4 cores
• minimum of 4 GB RAM
• 500 GB available hard disk space

In assessing the actual server requirements, one has 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 multipied 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 Vista or Windows 7, 32-bit (x86) or 64-bit (x64), Windows 8
• 100 Mb network connectivity
• 2 GB RAM
• 10 GB of available hard disk space
• 32-bit browser: IE 8+, Firefox, Chrome, or Opera

### 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 of the AIMMS Network License Server installer is available from http://main.aimms.com/downloads/aimms/download-aimms/aimms-network-license-server. 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 of the AIMMS Network License Server 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”.

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 file 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) (the name key), 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.

General architecture

The general architecture of AIMMS PRO is illustrated below.

### Installation of AIMMS PRO

Installing AIMMS PRO

Now that you have installed the AIMMS Network License Server and set up the
required licenses and profiles, you can install AIMMS PRO.

The AIMMS PRO installer will install three Windows services:

• AIMMS PRO postgresql-x64-9.3
• AIMMS PRO Service
• AIMMS PRO Portal Service

The AIMMS PRO services are not configured to start automatically. The AIMMS PRO Portal Service will fail to start if the AIMMS PRO Service is not already running. Depending on the host performance, a minimum of 30 seconds is required for the AIMMS PRO Service to start.

Database support
AIMMS PRO stores all of its configuration in a database. The only supported database is PostgreSQL. In order to ensure the optimal performance of AIMMS PRO, the database should be in the same data center as the AIMMS PRO installation. The PostgreSQL admin console can be found in {\tt installDir/pgsql/bin/pgAdmin3.exe}.

Java runtime

AIMMS PRO only supports Java version 1.7 or higher. If Java is not present on the host, it will default to the bundled Java version (1.7.0.25).
If you want to specify a different Java version, set the environment variable PRO_JAVA_JRE to a valid Java 1.7 Runtime Environment (JRE).

Installation and data location

As part of the installation of AIMMS PRO, you can select the locations where the AIMMS PRO executable files will be installed (from now on referred to as installDir), as well as the location where the AIMMS PRO will store its configuration files and runtime data (from now on referred to as dataDir). The default install location is

C:/Program Files/AimmsPRO

whereas the default data location is

C:/ProgramData/AimmsPRO

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, and configure HTTPS access to the portal by modifying the server configuration file, as detailed in the next section

### Changing settings in the AIMMS PRO configuration

Certain settings of the AIMMS PRO server are configurable via the configuration files in dataDir/Config

dataDir/Config/connection.properties
dataDir/Config/migration.properties
dataDir/Config/AimmsPROServer.json
dataDir/Config/AimmsPROPortalServer.json

Directly after starting up the AIMMS PRO Service for the first time, the configuration file will be created using default values. Any changes you make to the AIMMS PRO configuration file will only take effect after you restart the AIMMS PRO Service. These files are never deleted, not even by uninstalling AIMMS PRO. If they already exist, they will not be replaced by the installer either.

The migration.properties file

The file migration.properties is used by the migration process (in case you are migrating from AIMMS PRO 1.0.x). For more information about the migration procedure, refer to the Migration section.

The AimmsPROServer.json file

If the database configured in the previous step is empty, after starting up the AIMMS PRO Service for the first time, the file AimmsPROServer.json will be created using default values. The values in this file will be used to initialize the database. From now on, the AIMMS PRO Service will use the configuration in the database.

The AimmsPROPortalServer.json file

The file AimmsPROPortalServer.json is generated automatically at every AIMMS PRO Service start based on the configuration in the database. It is used by the AIMMS PRO Portal Service. This file should never be changed manually.

Changing settings

When you want to make changes to the AIMMS PRO configuration, modify the AimmsPROServer.json file as needed and rename the config.noreload file to config.reload. Afterwards, restart the AIMMS PRO Service. At startup, the server checks whether this file exists and if yes, all configuration parameters are updated with the new values and new parameters are added. The file is then renamed back to config.noreload. If, for any reason you do not find this file in the dataDir/Config/ directory, just create the file when you need to reload the parameters.

NOTE: No parameters are removed. E.g.: Updating an existing execution rule is not possible. When you change the existing execution rule and reload the configuration, the old execution rule will be kept and a new execution rule that reflects the new changes will be created.

JSON format

The AIMMS PRO configuration file is represented in the JSON format. Any changes that you make to the configuration file should result in a valid JSON file. If the AIMMS PRO server cannot read the configuration file during startup, it will reinitialize it with the default values, and backup any existing configuration file to AimmsPROServer.json.orig. After repairing the backup file, and renaming it to its original name, you can retry to start the server. If you are uncertain about the error, you may want to consult the http://jsonlint.com.

Configuration file security

Note that the AIMMS PRO configuration file is stored in a directory which requires administrative access for writing. If you try to write the configuration file from a non-administrative account, Windows may virtualize the file for you. This may lead to unexpected results, because for you the file may look like it contains the changes you made to it, while for the system account the file remains unaltered.

Server settings

The most likely server settings that you may want to change include:

• server/listenPorts: this setting denotes the port(s) on which the AIMMS PRO back-end server will listen. By default, the backend will listen on URI tcp://:19340/. On this port it will accept regular connections over TCP. Alternatively, you can specify a URI like, for example, ssl://:19341/, which would accept encrypted connections over SSL. For SSL connections
you must specify a PKCS12 file that contains the certificate and private key to be used for the server, along with the password through which the PKCS12 file is protected. In order to enable client side verification of the server certificate, set the clientPkcs12File to the PKCS12 file that contains the certificate that was used to sign the server key. If you leave this property empty, SSL will start, but there will be not verification of the certificate done by the client.
• server/internalURI: this setting denotes through which of the above URIs the AIMMS PRO portal will connect to the backend server. The value entered here should have a matching listenPort configuration.
• server/externalURI: this setting denotes through which of the above URIs external AIMMS clients will connect to the backend server. The value entered here should have a matching listenPort configuration. For normal, unencrypted, TCP connections, use tcp://<hostname>:<portnumber>/
• If you want to use any encrypted SSL connections you configured, use ssl://<hostname>:<portnumber>/
• server/portalPorts: this setting denotes the HTTP and/or HTTPS ports on which the AIMMS PRO portal will listen. For HTTPS connectivity you must
again specify a PKCS12 file containing the server certificate and private key to be used by the portal server.

License profiles

You can specify AIMMS license profiles to be used by client- and server-side AIMMS sessions through the following settings:

• publishing/licenseProfiles/clientProfile: this setting denotes which license profile is used by client-side AIMMS sessions.
• publishing/licenseProfiles/workerProfiles: this setting denotes which license profiles are available for server-side AIMMS worker sessions to perform server-based optimization tasks.

For each of the worker profiles you must specify a capacity, which should match the amount of licenses available through this license profile in the AIMMS Network License Server. These capacities serve as one of the shared resources which the AIMMS PRO server will use to determine which of the jobs available in the queue will be run next, as detailed below.

Queuing rules

The following server-side settings also serve as shared resources with a given capacity:

• session/queueRule: this setting contains a configurable list of rules that are applied to any request matching criteria specified for a particular rule.
• session/serverNodes: this setting specifies a list of servers that can be used by the AIMMS PRO server to dispatch server-side AIMMS sessions to. By default this list only contains the current AIMMS PRO server host, with a capacity of 1.

Shared resources

The total usage of each of the shared resources listed above by all requests being executed concurrently at any time, can never exceed the capacity of such a shared resource. Thus, license profiles can never be used beyond their availability, and the queuing rules allow you to limit the concurrent execution of execution requests sharing particular characteristics. Please note that specifying a capacity of 0 for a particular shared resource, will prevent any request in need of such a shared resource from being executed at all.

Queue priorities

The following settings set priorities for all queued requests

• session/queuePriority/defaultPriority: this setting sets the default priority for all requests, that have no other matching priorities.
• session/queuePriority/priority: this setting contains a list of priorities for requests 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.

Regular expressions allowed

In some of the queueRule and priority fields in the server configuration file, you can use Perl-compatible regular expressions(see also http://www.cs.tut.fi/~jkorpela/perl/regexp.html). The fields where regular expressions can be used are:

• appName, matched against the application name of the request
• appVersion, matched against the application version of the request
• nodeName, matched against the server node on which the request can be executed
• user matched against the value <user>@<environment> for the user associated with the session.

Example

To specify a rule that will only apply to all users within the ROOT environment you can specify “.*@ROOT” for the userName field.

Queuing algorithm

In determining which request in the queue is up for execution, the following rules are applied:

• Requests are queued according to assigned priority, requests with the same priority are queued according to their submission time. Whenever a request has completed its execution, all shared resources occupied by that request are released. The first request on the queue for which all applicable shared resources are available will be selected next for execution.

Notice that this means that requests will not necessarily be executed strictly in the order in which they appear in the queue. If a request needs, for instance, a license profile that is not available when the queue is re-inspected upon termination of a request, or is still hitting an execution rule that limits the number of concurrent sessions for a particular request configuration, it will be skipped and only be reconsidered when another request terminates.

Automatically deleting old jobs

Through the setting session/jobRetentionInDays you can control how long data of non-deleted jobs will be retained on the server. After the specified job retention time, the data of still-existing jobs on the server will be automatically deleted. Default value is 30 days. Deleted jobs will still be taken into account when displaying job statistics (see also Section Statistics).

### 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. In the default configuration, all log files are stored in the

dataDir/Log

directory. The content of the log files is in the log4j  XML format.

Logging level

For each component you can specify the level at which logging events are logged. By default all components log at the INFO level. You can modify the logging level by editing the log configuration files in the dataDir/Config folder for the various components. In case of unexpected errors you may want to (temporarily) change the logging level of the corresponding component to TRACE, which will create a log file containing all available logging events for that component. For further logging configuration options we refer to the documentation of log4j.

Inspecting the log files

The amount of logging information produced by the various components of AIMMS PRO may be substantial, especially at the TRACE level. If you want to inspect the log files, the use of one of the free or commercial log4j-compatible log viewers may be advisable.

### Migration from AIMMS PRO 1.0.x

The migration procedure can only be started after the installation of AIMMS PRO 2.0 using the following procedure.

1. Open the dataDir/Config/connection.properties} file.
2. \item Configure the path to the existing file storage of PRO in the {\tt pathToDBFile} key. The path can be found in {\tt AimmsPROServer.json} of the AIMMS PRO 1.0.x installation, under {\tt database:connectionString}. Make sure you also include the file extension. Note that the path uses slashes as separator.
3. \item Configure the database that will hold the PRO data as described in paragraph \ref{par:connection.properties}.
\item Before proceeding, make sure that the referred database schema exists.
\item Run the batch file {\tt installDir/convertAimms.bat} giving it as single arguments, the absolute path to {\tt dataDir}, excluding trailing slashes.
\begin{exampl
Example: installDir\convertAimms.bat dataDir\Config
\end{example}
4. Note: The migration, because of the significant changes between PRO 1.0, cannot also migrate the PRO configuration file {\tt AimmsPROServer.json}. The old file will be renamed to {\tt aimmsproserver.json\_old}. The configuration file, {\tt aimmsproserver.json} will be initialized with the default parameters during the first server start.

A successful migration should end with the message “FINISHED Converting PRO database”.

If you see an error message related to missing tables, the migration failed probably because one of the above steps was missed. Carefully check that the migration steps were done in the correct order and that all the settings made are correct. If the migration still fails, please contact our support team.

\chapter{Server Administration}
\label{ch:pro:server_administration}

\paragraph{Server administration}

After you have successfully installed the AIMMS PRO Framework, you can open the portal to perform administrative tasks.
By default, the portal can be reached at the URL {\tt http://<your-server>:8080}. To perform administrative tasks you can login
using the administrative account {\tt admin} within the {\tt ROOT} environment. Upon installation, the {\tt admin} account is delivered
with the default password {\tt admin}. You are advised to change the password for the {\tt admin@ROOT} account as soon as possible, which
can be done by clicking on the {\tt admin@ROOT} account settings on the top right of the screen.

\paragraph{Administrative tasks}

Through the AIMMS PRO portal you can perform the following administrative tasks:
\begin{itemize}
\item user management,
\item management of AIMMS versions, and
\item management of published AIMMS applications.
\end{itemize}

\section{User Management}

\paragraph{User management}

In the {\bf Users} area of the portal, you can perform all user management tasks related to AIMMS PRO. The following user management concepts are supported:
\begin{itemize}
\item {\em environments},
\item {\em groups}, and
\item {\em users}.
\end{itemize}

\paragraph{Environments}

An {\em 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.

\paragraph{Groups}

Within each environment, you can define one or more user {\em 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 {\em 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.

\paragraph{Users}

{\em 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.

\paragraph{The {\tt ROOT} environment}

By default, AIMMS PRO comes with a single environment installed, the {\tt ROOT} environment. The global {\tt admin} account is part of the {\tt 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.
\begin{itemize}
\item The {\tt admin} group: all users in the {\tt admin} group have global administrative privileges equal to the {\tt admin} account.
\item The {\tt AuthorizedServers} group: this group contains all servers that are authorized to cooperate within this AIMMS PRO instance. These server accounts also have full administrative privileges.
\item The {\tt AimmsPublishers} group: all users in this group are allowed to publish new AIMMS versions. These AIMMS versions can be used to run published AIMMS applications.
\item The {\tt AppPublishers} group: all users in this group are allowed to publish {\em new} AIMMS applications.
\end{itemize}
Please note that these system accounts and groups cannot be deleted.

\paragraph{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 {\tt admin} group and user within that environment. The {\tt admin} user of a particular environment (with default password {\tt admin}), and members of its {\tt admin} group, have full administrative privileges within that environment:
\begin{itemize}
\item they can add, delete and modify users and groups within the environment,
\item they inherit the same access rights to objects in- and outside of the environment as assigned to any of the environment’s users or user groups,
\item they can link an environment to an Active Directory domain.
\end{itemize}
The {\tt admin} group and user associated with an environment cannot be deleted.

\paragraph{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.

\paragraph{Adding new entities}

Above the column of each type, there is an {\bf 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.

\paragraph{Add a new user}

By clicking on the {\bf 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.

\paragraph{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.

\paragraph{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.

\subsection{Linking environments to Active Directory domains}

\paragraph{Link to Active Directory for AD member servers}

The AIMMS PRO framework allows you to link any environment to an Active Directory domain. 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. 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 should point to the AIMMS PRO Server at hand.

\paragraph{\dots\ for a server not in the AD domain}

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.
\begin{itemize}
\item Your IT department needs to set up a service account, with rights to delegate to any service using Kerberos.
\item You need to specify the credentials of this service account in the {\bf authentication/serviceAccount} area of the PRO configuration file.
\item You need to associate the Service Principal Name of your PRO server with this service account through the {\tt setspn} command.
\end{itemize}

\paragraph{Determining 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. Typically, this is the DNS name you specified in the {\bf server/externalURI} field in the PRO configuration file. Assuming this DNS name is {\tt foo.bar.com}, the Service Principal Name you need to associate with the service account will be
\begin{example}
HTTP/foor.bar.com
\end{example}
If the service account is, for instance, {\tt PROServiceAccount} within the AD domain {\tt MyADDomain} then you can associate the SPN with it through the command
\begin{example}
setspn -a HTTP/foo.bar.com MyADDomain\PROServiceAccount
\end{example}
If needed, you can associate multiple SPNs with a single service account. You can check which SPNs are associated with the account by entering
\begin{example}
setspn -l MyADDomain\PROServiceAccount
\end{example}
After you have added the association, it may take some time before these changes are replicated throughout your AD forest.

\paragraph{Setting up the link}

After you have prepared the service account as above, you can associate a PRO environment with {\tt MyADDomain} 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 {\tt noDomain}. You should replace it by {\tt MyADDomain}.

\paragraph{Single sign-on}

After enabling an environment for Active Directory authentication, any user connecting to that environment, will automatically authenticate 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.

\paragraph{Requirements for AD users}
Users that want to use the AD login functionality should have the AIMMS PRO Plugin properly installed, otherwise they will get an error message.

\paragraph{Single environ- ment 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 there are multiple environments linked to the same Active Directory domain, users may be logged on to the wrong environment, or may fail to logon because there are no matching groups.

\paragraph{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 {\tt admin} group of the environment or to groups within other environments will not be affected by this dynamic group membership modification mechanism.

\paragraph{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 {\em 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 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.

\paragraph{On demand user inform- ation 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.

\paragraph{Project publish- ing rights for Active Directory users}

In order for a user to be able to publish AIMMS projects, the user needs to be a member of the {\tt AppPublishers} group in the {\tt 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 {\tt 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:
\begin{itemize}
\item Select the environment corresponding to the Active Directory,
\item Select any of the user groups this user is a member of,
\item Select the {\tt ROOT} environment (this will not change the list of users, but only the list of user groups),
\item Drag the user into the {\tt AppPublishers} user group.
\end{itemize}
Following the same steps, but only dragging the user into the {\tt AimmsPublishers} group will give AIMMS version publishing rights to the Active Directory user.
\section{AIMMS Version Management}

\paragraph{AIMMS versions}

As part of every AIMMS release, so-called AIMMS PRO Server packages will be made available. Through the AIMMS PRO portal, all users with global administrative privileges and users who are member of the {\tt 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:
\begin{itemize}
\item 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
\item an AIMMS component with all solvers included, to run the server-side optimization sessions.
\end{itemize}
All published AIMMS versions are available for deployment of end-user applications to all users from all environments.

\section{AIMMS Application Management}\label{sec:pro:apps}

\paragraph{Publishing applications}

Any AIMMS PRO-enabled AIMMS project can be published onto an AIMMS PRO Server. PRO-enabled projects must be made available in the form of a {\tt .aimms\-pack} file, and can be published through the {\bf Apps} area of the portal. All members of the {\tt admin} and of the {\tt AppPublishers} groups will have a {\bf publish} button available in the {\bf Apps} area, through which they can publish PRO-enabled {\tt .aimmspack} files. After selecting a {\tt .aimmspack} file and an (optional) application icon to be used in the portal, you have to provide some additional information about the application:
\begin{itemize}
\item {\bf application name}: the unique name by which the application is identified within the AIMMS PRO Framework.
\item {\bf application version}: the application version
\item {\bf description}: a descriptive text to be displayed in the portal
\item {\bf AIMMS version}: the published AIMMS version used to deploy the AIMMS application
\item {\bf license profile}: the license profile to be used for server-side optimization sessions of this application
\end{itemize}

\paragraph{Configure 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.

\paragraph{Different rights}
In the blocks you will see three different rights:
\begin{itemize}
\item {\bf 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.
\item {\bf 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.
\item {\bf 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.
\end{itemize}
For ordinary application access, you need to enable read and execute access.

\paragraph{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 permissions 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).

\paragraph{Changing permissions}

After you have published the application, you can always change the access rights of the application through the {\bf permissions} link in the
info box of the application. You will only see this link if you have write access to the application.

\paragraph{Updating and deleting applications}

If you have write access to the application, you may also update and delete the application. When updating an application, after uploading a new {\tt .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.

\paragraph{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.

\section{Cluster configuration}\label{sec:pro:cluster:config}
\setcounter{secnumdepth}{6}
This section describes how to setup AIMMS PRO to be able to run optimization sessions on multiple servers.

\paragraph{Cluster prerequisites}

In order to have an AIMMS PRO multiple server configuration you should keep the following aspects in mind:
\begin{itemize}
\item All AIMMS PRO servers need to be able to reach the same database host. This might include configuring the database to accept remote connections (not from the localhost).
\item All AIMMS PRO servers need to be able to reach a network shared storage and should have full access to the folder that will be used for storage.
\item All AIMMS PRO servers need to have 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.
\end{itemize}

\paragraph{Setting up the cluster}
It is assumed that you already have a fully functional instance of PRO running (from now on referred as S1) and you want to create a cluster configuration by adding another PRO server (referred to as S2). All these actions need to be performed on S2 unless stated otherwise.
\begin{enumerate}
\item Make sure that S1 storage configuration is pointing to a network storage. The SMB/CIFS networking protocol is supported, but all backward slashes need to be transformed to double backward slashes (e.g. \textbackslash host\textbackslash path should appear in the configuration as \textbackslash\textbackslash host\textbackslash\textbackslash path). After making this change you will have to go through the steps described in paragraph \ref{par:ChangingSettings}.
\begin{example}
“storage” : {
“maxConcurrentTransfersIn” : 128,
“maxConcurrentTransfersOut” : 128,
“workspace” : “\\\\networkStorage\\prostorage”
}
\end{example}
\item Install AIMMS PRO on S2.
\item Start AIMMS PRO Service.
\end{enumerate}

The server will default to capacity 1. To increase it, modify the section {\tt session/serverNodes} in the AIMMS PRO config file. The name property should use the fully qualified domain name (FQDN) of the newly added host.

\paragraph{Running as a 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 intance 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 intances.

\paragraph{Changing the AIMMS PRO configuration when running as a cluster}
Due to the distributed nature of the cluster we recommend changing the AIMMS PRO configuration ({\tt AimmsPROServer.json}) from a single server all the time (typically, this is the first server that was added to the cluster, i.e. S1). The configuration file is not synchronized across PRO servers and you could end up using an out of date configuration file to update the database configuration. This will lead to unexpected behavior. It is not recommended that you make the changes directly in the database as this could lead to an unknown state of the database.

\section{General remarks}

\paragraph{Case sensitivity}
AIMMS PRO is case insensitive. This is valid for the following parameters: user names, environment names, group names, AIMMS application name and version, the strings in the execution and priority rules structures, the labels for the storage bucket, the labels for the objects stored in the storage buckets. The first time any of these parameters is created, the case is saved, but after that, any try 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).

\section{Commonly encountered errors}
This section presents the most common errors that can be encountered during the use of an AIMMS PRO application.

\paragraph{Job finished with errors}
\textit{Too many retries for starting}\newline
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.\newline
\newline
\textit{Solution}\newline
Make sure that you have enough licenses defined under {\tt workerProfiles} in {\tt AimmsPROServer.json}. Also, make sure that the AIMMS Network License Manager is reachable by AIMMS PRO.

\paragraph{Did not get a valid ticket from the server during Active Directory logon}
\textit{Did not get a valid ticket from the server during Active Directory logon,\newline you may possibly not be a member of any AD-linked PRO group, and therefore\newline be refused access. Please contact your application or AIMMS PRO administra\-tor.}\newline
Possible cause 1: Could appear because the AIMMS PRO Plugin is not installed, needs to be updated or is incompatible with the current AIMMS PRO version.\newline
Possible cause 2: 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.\newline
\newline
\textit{Solution 1}\newline
Install the AIMMS PRO or update as indicated on the AIMMS PRO page. As a last resort, try to uninstalling and installing the plugin.\newline
\textit{Solution 2}\newline
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.
\newline

\paragraph{Errors shown by the AIMMS PRO Plugin}
\textit{Unable to determine version for object ‘someObjectName’, due to Exception\newline ‘Version for object ‘someObjectName’ does not match the expected version’}\newline
OR\newline
\textit{…Packet buffer exhausted…}\newline
Appear because you have opened two different versions of AIMMS PRO in the same browser instance (e.g. in two different tabs or in two different windows).\newline
\textit{Solution}\newline
You need to make sure that you are using a single version of AIMMS PRO per browser. Either use each version one at a time in the same browser (you will need to restart the browser in between), or use two different browsers for the two different AIMMS PRO versions (e.g. open one in Firefox and one in Chrome).

\paragraph{{\tt Install PRO Plugin} button still appears on Chrome}
\textit{Install PRO Plugin button still appears on Chrome after installing the plugin and restarting Chrome}\newline
This is caused by the security settings of Chrome. It is also accompanied by the message \textit{AimmsPROPlugin needs your permission to run} in the upper part of the web page. The message appears when connecting for the first time to the AIMMS PRO Portal.\newline
\textit{Solution}\newline
You need to click {\tt Always run on this site} to allow the plugin to run and refresh the page and you will not see the {\tt Install PRO Plugin} button anymore.

\paragraph{AIMMS PRO client errors}
\textit{{\tt invocation request timed out [error 2004]} message appears in the AIMMS PRO client}\newline
The AIMMS PRO client communicates with AIMMS PRO through a connection that is established at the first run of the client. If the connection is not used for some time, configurable in AIMMS PRO, the server will close the connection automatically. The error appears when the client tries to communicate with the server after that connection has been closed.\newline
\textit{Solution}\newline
Close the client that is showing you that error and launch it again from the AIMMS PRO Portal.