Skip to content
Architecture > Configuration Guide

Web

Note: To run the ami web, include web in the list of components found in the the ami.components property, ex: ami.components=web

License

  • ami.license.file: location of where to place/edit license file when using license wizard (under Help -> Enter/Update License). Default is ./f1license.txt
  • ami.web.disable.license.wizard: Hide the Help -> Enter/Update License menu item, even when not in developer mode
  • ami.web.license.auth.url: the url for connecting to 3forge's server and generating license files (accessed from Help ->Enter/Update License -> Generate License Key). If blank, then the Generaet License Key button is not available and licenses must be manually generated via the website portal.
  • f1.license.warning.days: The number of days prior to a valid license expiring that a warning message will start appearing on the login page. Default is 14 days
  • f1.license.file: The path to your f1license.txt file

HTTP Connection

  • http.port: sets the port that web browsers use to connect to AMI Web. The default port is 31313.
  • https.port: sets the port that web browsers use to connect securely to AMI Web. The default port is 3333 https.keystore.file: the path to the key store file generated using java's keytool that will be used for secure web connections.
  • https.keystore.password: the password associated with the key store file specified in the https.keystore.file property.
  • ami.web.http.connections.max: the maximum number of concurrent http connections (for preventing DOS attacks). Default is 100
  • ami.web.http.connections.timeout.ms: the number of milliseconds before an idle http connection is closed. Default is 30000
  • ami.session.check.period.seconds: the number of seconds between which AMI checks and removes expired sessions (users that have closed their AMI tab/browser, or are disconnected w/o a valid logout). Default is 60 seconds.
  • ami.session.timeout.seconds: the number of seconds that must pass before a session is considered expired, causing the user to automatically be logged out. Default is 300 seconds.
  • ami.allow.site.framed: allow the ami webpage to be framed inside an iframe. If false, then x-Frame-Options and SameSite options are included in header. Default is true
  • http.port.bindaddr: Optional. Specifies the network interface that the http.port server port will be bound to
  • https.port.bindaddr: Optional. Specifies the network interface that the https.port server port will be bound to
  • ami.session.cookiename: name of the cookie to store in the web browser for the sessionid. Default is F1SESSION. If multiple AMI instances are sharing a host then each must have a unique cookie name
  • http.port.whitelist: provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<New_line_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>
  • https.port.whitelist: provide either a list of permitted hostname patterns or plugin for blocking/granting access based on foreign network address. Syntax is either file:<file_containing_a_hostname_patterns_per_line> or text:<comma_delimited_list_of_hostname_patterns> or plugin:<class_name_implementing_com.f1.ami.amicommon.AmiServerSocketEntitlementsPlugin>

Session Options

  • amiscript.variable.*varname*: Declare a readonly variable available throughout the dashboard's amiscript. The value should be wrapped in quotes for a string, or properly formatted to indicate the type. Note, you can see declared variables via Menu -> Dashboard -> Session Variables. Examples:
    • amiscript.variable.hello="world" //declare a string named hello
    • amiscript.variable.num=123L //declare a long named num.
  • users.access.file.encrypt.mode: off indicates the access.txt file is plain text. password indicates that the password portion must be encrypted. See strEncrypt(...) function for encrypting passwords. Default if off. Can be set to password to turn encryption on.
  • ami.centers: a comma delimted list of centers' host:port to connect to. You can optionally prefix a host:port with an alias in the form alias=host:port, in which case the alias will be used to reference the center within the dashboard. If an alias is not provided, then the alias is the host:port. Note, the first supplied URL is considered the primary center.Ex: ami.centers=myprimary=localhost:3270,other=some.host.com:3270
  • ami.center.[name].keystore.file: Supply if center is using ssl connection. The path to the key store file, generated using java's keytool. (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.contents.base64: Supply if center is using ssl connection. The contents of the keystore as a base64 (instead of supplying the file name) (Name is the center name as it appears in ami.centers property)
  • ami.center.[name].keystore.password: Supply if center is using ssl connection. The password associated with the key store file (Name is the center name as it appears in ami.centers property)
  • ami.web.http.slow.response.warn.ms: Log a warning if a full round trip http request/response is greater than the specified duration in milliseconds. Default is 5000
  • ami.web.show.wait.icon.after.duration: the duration before displaying the loading / waiting icon. Default is 2000 milliseconds
  • ami.slow.amiscript.warn.ms: Log a warning if an amiscript block can not be executed the specified duration in milliseconds. Default is 1000
  • ami.web.portal.dialog.header.title: title on the portal dialog header (i.e. loading and error dialogs).

Login Options

  • ami.login.page.animated: Boolean indicating if login page should display animated background. True by default, recommended to set to false if used on remote desktops.
  • ami.login.page.title: the suffix to include in the login page web's title (appended to 3forge - )
  • ami.login.page.terms.and.conditions.file: Optional file to include in the login page, requiring user to acknowledge the terms and conditions before logging in.
  • contact.email: The email address for contacting support on a login issue, or to create a new account. Default is "support@3forge.com?subject=Ami Account Request"
  • ami.login.page.logo.file: Path to file containing image for login in login screen. Image will be scaled to a pixel width and height of 350x200. It's suggested that the image should be exactly that size to avoid scaling artifacts.
  • web.title: Change the title in the web browser tab
  • web.logged.out.url: url to redirect to when logged out, default is / which directs to login page. (Hint: set to /loggedout.htm for a logged out page instead, useful for OAUTH)
  • web.favicon: The icon to put in the tab
  • ami.web.splashscreen.info.html: Information to show on the splashscreen (rendered as html)
  • ami.web.default.MAXSESSIONS:Maximum number of sessions allowed per login of a user

Developer Options

  • ami.autosave.dir: the directory where autosaved versions of the layout are saved. Default is data/autosave
  • ami.autosave.count: The minimum number of backup revisions of layouts that should be saved per user
  • ami.autosave.layout.frequency: How often layouts will be automatically saved to the backup log file. Default is: 15 MINUTES
  • ami.messages.max.info: Maximum number of debug/info messages to store for debugging purposes in edit mode. Default is 100
  • ami.messages.max.warn: Maximum number of warming messages to store for debugging purposes in edit mode. Default is 100

Plugins

  • ami.web.auth.plugin.class: Class name of custom authenticator which must implement com.f1.ami.web.auth.AmiAuthenticator interface and be deposited in the plugin directory. The plugin will be responsible for user authentication and configuration. See Custom Java Plugins for details.
  • ami.auth.namespace: Optional namespace that will be passed into authenticator's authenticate(...) method
  • amiscript.custom.classes: A comma delimited list of classes to include for access within ami script. See Custom Java Plugins for details.
  • ami.style.files: Comma delimited list of files (wildcards supported) which contain ami styles. (see menu -> dashboard -> style manager)
  • ami.web.panels: Comma delimited list of custom panel type configurations.
  • ami.auth.timeout.ms: Amount of time, in milliseconds before AMI assumes the authentication plugin has timed out. Default is 5000 milliseconds
  • ami.web.data.filter.plugin.class: Class name of custom Data Filter which must implement the com.f1.ami.web.datafilter. AmiWebDataFilterPlugin interface and be deposited in the plugin directory. The plugin will be responsible for filtering out data that users shoud have and not have access to. See Custom Java Plugins for details
  • ami.guiservice.plugins: A comma delimited list of class names implementing the com.f1.ami.web.AmiWebGuiServicePlugin interface. (see Custom Java Plugins for details)
  • ami.web.permitted.cors.origins: control which origins are accepted in AMI Remote Procedure Calling (see RPC)

Layout and User Files

  • users.access.file: Location of the "access.txt" file, see User Parameters section below.
  • users.path: Directory containing the .ami_settings user files and the user preference files. Default is data/users.
  • ami.shared.layouts.dir: base directory of where shared layouts are stored (those layouts available to end non-dev users). Default is data/shared
  • ami.cloud.dir: base directory of the AMI Cloud. Layouts and user settings saved to the cloud will be stored in this directory.
  • ami.users.file: file name of the users configuration file. See "Access Configuration File for Web" section for details.
  • ami.web.default.layout.shared: [Deprecated, use ami.web.default.layout=SHARED:<layoutname>] Name of the layout's file name. If Specified, then any users that login will be automatically assigned to the specified layout, and developer/admin mode will not be available. See ami.shared.layouts.dir for where shared layouts are located.
  • ami.font.files: A list of true type font files (.ttf) to load which will be available for use in dashboards. May include wild cards, ex: my/fonts/.ttf*
  • ami.fonts.in.browser: A list of font family names that are assumed to be available in the browser, meaning the ttf definitions will not be transferred to the browser even if a corresponding ttf file is specified (see ami.font.files). The default is: Arial,Courier,Georgia,Impact,Lucida,Times New Roman,Verdana
  • ami.webmanager.host: Optional location for where to access webmanager, used for remotely loading files. If not specified, local file system is used.
  • ami.webmanager.port: Optional location for where to access webmanager, used for remotely loading files.
  • ami.web.default.LAYOUTS: A comma-delimited list of layout names that are accessible for the users that are non-dev and non-admin.

Default layout

The default layout is the layout to load when a particular user logs in. There are some properties that give a fine control on how the default layout is determined. The property with lower number of priority will be considered first.
If ami.web.default.DEFAULT_LAYOUT (with priority 0) is present, then all other properties with bigger priority values will be ignored.

  • ami.web.default.DEFAULT_LAYOUT: PRIORITY 0
  • ami.web.default.layout: PRIORITY 1
  • The user's ***ami_layout_shared*** in access.txt: PRIORITY 2
  • ami.web.default.layout.shared: PRIORITY 3 (This is deprecated, suggested to use ***ami.web.default.layout=SHARED:<layoutname> instead )
    • note that using ami.web.default.layout.shared in conjunction with ami.shared.layouts.dir=path/to/dir will load a specific layout to every user who logs in, regardless if they are present in access.txt or if you are using an authentication plugin.

The properties above will apply for all users in access.txt. If you want a finer control of default layouts for each individual user, you could put the <property> from the ami.web.default.<property\> at the end of each user clause in ***access.txt***, as an example: If there are two users: user1 and user2. We want to assignuser1_defaultLayout.amito user1 as the default layout, anduser2_defaultLayout.ami` for user2, then in access.txt:

1
2
user1|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user1_defaultLayout.ami
user2|123456|ISADMIN=true|ISDEV=true|DEFAULT_LAYOUT=user2_defaultLayout.ami

Deprecated

  • ami.web.default.layout;
  • ami.web.default.layout.shared; use ami.web.default.layout=SHARED:<layoutname>
  • ami.web.default.to.admin;

End User Behavior

User Settings

All default user-specific settings can be configured programmatically using ami.default.user.<User Setting Name> in local.properties, as an example:

  • ami.default.user.<property>: Set default user settings e.g. set users' default timezone to UTC with ami.default.user.timeZone=UTC (note timeZone uses a capital Z)

Other properties include:

Property Name(key) Property Value(value) Supported Value Example Usage
dateFormat String, format of date, by default is M/dd/yyyy [yyyy/MM/dd, MM/dd/yy,...] ami.default.user.dateFormat=yyyy/MM/dd
timeFormat String, format of date, by default is H:mm [hh:mm a, h:mm, HH:mm, h:mm a], (if time is 13:30, then H:mm->3:30, h:mm->1:30 PM, HH:mm->13:30, hh:mm a->01:30 PM) ami.default.user.timeFormat=HH:mm
numberSeparator String, determines on how the number should be separted, by default is 1,234,567,890.123 [1,234,567,890; 1,234,567,890.123; 1'234'567'890; 1234567890,123; ...] ami.default.user.numberSeparator=1,234,567,890
numberDecimalPrecision Integer, number from 0-10, by default is 2 Integer number from 0-10 ami.default.user.numberDecimalPrecision=4
sciNotDigitsLeft Integer, number from 1-20, by default is 1 Integer number from 1-20, ami.default.user.sciNotDigitsLeft=4
sciNotDigitsRight Integer, number from 1-20, by default is 3 Integer number from 1-20, ami.default.user.sciNotDigitsRight=5
numberNegativeFormat String, format of Negative Number. by default is sign, can take either sign or parenthesis [sign,parentheses] ami.default.user.numberNegativeFormat=parentheses
spreadSheetFormatOption String, spread sheet formating, by default is always, can take either always or never [always,never] ami.default.user.spreadSheetFormatOption=never
autoApplyUserPrefs String, whether or not automatically apply use preferances, by default is ask, can take always,never or ask [always,never,ask] ami.default.user.autoApplyUserPrefs=always
  • ami.show.menu.option.datastatistics: When to show the data statistics menu option: always, never, dev, admin. (dev - only in dev or admin mode, admin - only in admin mode) default is always
  • ami.show.menu.option.fullscreen: When to show the full screen menu option: always, never, dev, admin. (dev - only in dev or admin mode, admin - only in admin mode) default is always
  • ami.frames.per.second: the rate that the web browser is updated with new data. This is used to tune the performance of AMI and the user experience. We do not recommend a refresh rate of higher than 20 frames per second.
  • ami.web.default.cmd.timeout.ms: the number of milliseconds to wait for a response when sending a command to the backend. Default is 30000
  • ami.request.timeout.seconds: the amount of time before a user will be prompted that their request could not be serviced. Default is 60 seconds.
  • ami.show.menu.option.datastatistics: Determines which types of users can view data statistics (under Menu Bar -> Help -> Data Statistics) . Valid options are always, never, dev or admin. Default is always
  • ami.show.menu.option.fullscreen: Determines which types of users can set the browser to full screen (under Menu Bar -> Windows -> Full Screen) . Valid options are always, never, dev or admin. Default is always
  • ami.web.default.to.admin: by default is true, which means that if there are no admin users registered (See Menu Bar -> Account -> Manage Users) then all users are considered admins. Setting to false means that users will be strictly assigned the role they are associated with.
  • ami.web.default.ISADMIN: by default is false, which means that if ISADMIN is not supplied in access.txt, what is the default value
  • ami.web.default.ISDEV: by default is false, which means that if ISDEV is not supplied in access.txt, what is the default value
  • general.error.message: The generic error message displayed to users when an exception is not caught. Default is: "Frontend encountered unhandled condition"
  • general.error.emailTo: The email address to send error reports to when a user clicks to report an error. Default is: "support@3forge.com"
  • general.error.emailSubject: The default subject used to populate the error report email (see general.error.emailTo). Default is "Support Issue"
  • general.error.emailBody: The introductory sentence in the error report email (see general.error.emailTo). Default is "Please find details below:"
  • ami.web.filter.dialog.max.options: Maximum number of options to show in the table filter dialog

Performance

  • ami.web.precached.tables: A comma delimited list of tables (aka types) to automatically cache real-time inside the webserver. Any types that a layout references that are not explicitly listed in this property will require a snapshot request from the Ami Center.
  • ami.chart.threading.suggestedPointsPerThread: Determines the number of threads to use for a chart, based on the number of points to render. Default is 100000
  • ami.chart.threading.maxThreadsPerLayer: Provides a ceiling on total threads that can be used. Default is 10
  • ami.chart.threading.threadPoolSize: The total number of threads (across all users) to allocate for chart image processing. Default is 100
  • ami.chart.threading.antialiasCutoff: The number of points before anti-aliasing should be turned off, so that rendering is faster for high density charts. Default is 100000
  • ami.chart.compressionLevel: The PNG compression level for the images that are transferred to the front end where 0=off, 10=Full compression. Default is 2
  • ami.frames.per.second:The number of times that the AMI application's display is refreshed in a single second. Default is 15fps

Style

  • web.loadingbar.styles: this property takes in a list of key-value pairs. The keys are: dialogBgColor, headerBgColor, stripeColor1, stripeColor2, stripeColor3.

Example usage:

1
web.loadingbar.styles=dialogBgColor=#234567,headerBgColor=#123456,stripeColor1=#ff0000,stripeColor2=#ff00ff,stripeColor3=#f0f0f0

Default Authentication Access File

When an authentication plugin is not supplied a configurable "access" file is referenced by default. Note, this should only be used for testing and other non-production purposes due the lack of security, etc. This is where usernames, passwords, default layouts, and user parameters are defined. The access configuration files lives in the directory of the Web application and is named data/access.txt by default. Each line should contain a single user's entry which is pipe (|) delimited. The first entry is the username, 2nd is the password, additional parameters are key=value.

Username: First Param, the username defined is what a user needs to login as.

Password: Second Param, this is the only place that passwords can be set for users.

key=value: Additional parameters. The following keys are supported:

  • ISDEV=true/false - Determines if the user should have developer rights, aka should they have the green toggle button in the upper right corner
  • ISADMIN=true/false - If ISDEV is set to false, then this has no effect. If ISDEV is set to true and ISADMIN is set to true, then dev user can shutdown AMI from the GUI via File -> Shutdown.
  • amiscript.variable.<varname>=value - Defines a variable in the user session, with the type inferred. For example amiscript.variable.blah=123 creates a variable named blah of type int with the value 123. Alternatively, amiscript.variable.blah="123" would create the variable as a string instead.
  • amivar.<varname>=value - Deprecated - defines a variable of type string in the user session prefixed with user<dot> For example amivar.blah=123 creates a variable inside user user's session named user.blah with the string value "123"
  • developer_ami_editor_keyboard=vi/default - For developer mode, should the editor use plain text or vi mode
  • ami_layout_shared=default layout to load (under the directory configured using the ami.shared.layouts.dir property)
  • ami_layout_current= Current layout
  • LAYOUTS= A comma delimited list of regular expressions for layouts that are available to this user. This is only applicable to CLOUD layouts.

User Parameters: parameters can be assigned to a user. These parameters can then be used to modify the user's access to data and inputs.

Example Configuration File

1
2
3
4
jdoe|jdoe123|ami_layout_shared=ACME.ami|amivar_group=ops
csmith|password1234
exampleusername|pass24|amivar_region=asia
exampleusername|pass24|LAYOUTS=overview.ami, report.ami, *rfp.ami

JavaScript

In order to allow JavaScript code to be ran from within an HTML panel in a window, this property needs to be set in your local.properties file to allow the code to be recognized:

  • ami.web.allow.javascript.embedded.in.html: Boolean indicating if JavaScript is enabled for an HTML panel. False by default for security purposes to prevent Cross-Site Scripting (XSS) attacks, where JavaScript code is inherently removed from all HTML panels. Set to true to enable JavaScript within an HTML panel.