App Settings

Introduction

In the App Settings dialog box, you can alter the settings that are applicable to the whole app:

The categories described below are available.

Configurations Tab

A configuration is a group of settings. You can define any number of configurations. The active configuration (meaning, the one that will be used when running your application) is determined by the drop-down menu in the toolbar of Studio Pro.

For more information on settings in a configuration, see Configuration.

Runtime Tab

These settings influence the behavior of the Runtime when running your application.

Use React Client

This setting enables the new React version of the Mendix Client. This React client was released into beta in Mendix 10.7. As of Mendix 10.18, it is in GA. There are three options:

• No: Do not use the React client (default).
• Yes: Use the React client. In this mode, you will get consistency errors for incompatible widgets.
• Migration mode: Use the React client and ignore incompatible widgets. Placeholders are displayed in the case of incompatible widgets. Recommended when trying out the new client.

Static Resources from Disk

If this option is enabled, the static resources for your mobile application are downloaded as soon as you open your application rather than bit by bit as you navigate through the app. This can drastically cut down the number of network requests, as the files can be retrieved from the disk rather than from the server.

The resources are downloaded to the device once for each deployment and are reused for subsequent runs of your app. This affects a number of files, including your theme, the JavaScript client, CSS files, and pages.

Optimize Network Calls

If this option is enabled (true by default), Mendix analyzes every microflow that can be triggered from the client to minimize the number of objects required to be sent. This speeds up your app significantly.

If you experience an issue while running your app in which objects seem to be lost, this option can be disabled to resolve that issue. If this does resolve the issue, please file a bug report so that we can fix the issue in the platform.

URL Prefix

Here you have the option to change the default URL prefix for all pages and microflows in your application. The default prefix value is /p/.

The URL prefix must be alphanumeric. It cannot be empty, contain whitespace, or contain any of the following values:

• “api-doc”
• “file”
• “odata”
• “odata-doc”
• “reload”
• “rest-doc”
• “ws”
• “ws-doc”
• “xas”

Furthermore, static files are served on /. So any prefix that has the same name as a static folder located in /deployment/web/ will cause an error.

If the URL prefix breaks any of the rules mentioned above, then you will get a consistency error.

Java Version

Here you can select which Java version to use for you application.

For local development the Java version configured here needs to have a corresponding JDK configured in the Studio Pro preferences.

Applications deployed to the cloud will use this setting to select which Java version to use.

After Startup

Here you can select a microflow that is automatically executed immediately after the application has been started up.

Before Shutdown

Here you can select a microflow that is automatically executed when a shutdown command has been given, just before the application shuts down.

Health Check

Here you can select a microflow which performs the checks on a running app that you think are required to assess the app’s health.

The result of each check is returned as a string, which is displayed in the Mendix Portal. When the microflow returns an empty string, the application is healthy; otherwise, the string presents an explanation of why the application is not healthy.

This microflow gets called every 10 seconds to check if the app is still healthy. This is done by executing it using m2ee on the admin port of your app. For more information, see the section Health Check in Monitoring Mendix Runtime.

First Day of the Week

The First day of the week setting determines the first day of the week in the date picker widget.

Option	Description
Default (based on locale) (default)	The first day of the week in date picker widgets is based on the locale of the user.
Sunday	Use Sunday as first day of the week in date picker widgets.
Monday	Use Monday as first day of the week in date picker widgets.
Tuesday	Use Tuesday as first day of the week in date picker widgets.
Wednesday	Use Wednesday as first day of the week in date picker widgets.
Thursday	Use Thursday as first day of the week in date picker widgets.
Friday	Use Friday as first day of the week in date picker widgets.
Saturday	Use Saturday as first day of the week in date picker widgets.

Default Time Zone

The Default time zone determines the time zone for newly created users. If your application is only used in one time zone, setting this default will make sure that users of your application never have to worry about setting their time zone.

Scheduled Event Time Zone

The Scheduled event time zone defines under which time zone scheduled events run. The default is UTC. If you would like to run scheduled events under another time zone (such as the time zone of the company office or the app default time zone), you can select it here.

This affects time zone-related operations, such as parsing and formatting dates from/to strings and obtaining the beginning of the current day.

If you run on-premises, then you can select the time zone to which the server is set. However, please note that no guarantees are given for the whereabouts of application servers in the cloud.

Hash Algorithm

The Hash algorithm is used to generate hash values for attributes of the hashed string type, such as the password of a user. Mendix offers two recommended hashing algorithms:

Option	Description
BCrypt (default, recommended)	Resistant to brute-force search attacks.
SSHA256	Salted Secure Hash Algorithm 2, digest length 256 bits.

Mendix believes both algorithms are secure enough to store passwords within Mendix. The main difference between BCrypt and SSHA256 is that the BCrypt algorithm has been configured so that it is relatively slow on purpose, since it was designed specifically to stop brute force attacks. That’s why this results in a slight performance difference with the SSHA256 algorithm.

BCrypt Cost

BCrypt cost is used to specify the cost of the BCrypt algorithm. The default value is 12, and can go up to 30. The higher the value is, the slower the process of hashing values. For more information, see the subsections below.

Performance

If the BCrypt cost is low, the performance difference is hardly noticeable to a single user when signing in (meaning, the password you enter when signing in is hashed using the selected algorithm). This means performance alone is not a reason to choose SSHA256 over BCrypt. The situation can change when dealing with high concurrency of hashing operations, for example, published web services exposing operations that compute quickly, like short-running microflows.

Performance Tests

A (web service) user will sign in to execute a web service operation, wait for the operation to finish, and finally get the result back (if any).

Imagine an empty microflow that returns nothing at all exposed as a published web service. We ask one user to execute this operation as many times as they can in one minute (simulated with SoapUI). First we set the hashing algorithm to BCrypt (with cost value 10), then we set it to SSHA256. Any extra overhead here (on top of establishing the connection, building the XML message and so forth) is basically the hashing algorithm, as the operation should take near zero milliseconds and there is no result. So that leaves only the login, or, more precisely, the hashing of the password.

Hashing Algorithm	Total Operations Executed	Operation per Second	Overhead in Milliseconds
BCrypt	654	10.88	91.9
SSHA256	7163	119.36	8.4

So 80 milliseconds per operation is not that much, right? Well, that depends on how long the operation itself takes.

Operation Duration in Seconds	Operations per Hour (BCrypt)	Operations per Hour (SSHA256)	Difference %
0.1	18760	33210	+77%
0.25	10529	13932	+32%
1	3297	3570	+8%
5	707	719	+1.67%
15	239	240	+0.5%

The difference is noticeable when the operation takes less time. So if you expect a very high amount of concurrency in operations where hashing takes place (most commonly any place where login operations are involved), you might want to consider changing your hashing algorithm.

Rounding Numbers

The Round Numbers setting is used to select how to round numbers when performing calculations.

The rounding methods Half away from zero and Half to the nearest even number indicate how rounding is performed in the case of a tie (for example, 2.5).

This table presents the results of rounding the input to one digit with the given method of rounding numbers:

Input Number	Half Away from Zero (default)	Half to the Nearest Even Number
5.5	6	6
2.5	3	2
1.6	2	2
1.1	1	1
1.0	1	1
-1.0	-1	-1
-1.1	-1	-1
-1.6	-2	-2
-2.5	-3	-2
-5.5	-6	-6

Multiple Sessions per User

If this option is enabled, users can sign in multiple times through different clients (for example, desktop browser and tablet). Otherwise, an existing session for a user is signed out when the user signs in somewhere else.

Default: Yes

Foreign Key Constraints

If this option is enabled, database foreign key constraints will be used. An attempt to commit a dangling reference will throw a runtime exception.

Default: depends on the version of Mendix used to create the app:

• Yes for apps created with Mendix versions 10.6.0 and above
• No for apps created with Mendix versions below 10.6

Languages Tab

For more information about using different languages in your app, see Language Menu.

Default Language

The Default language indicates the language that is used when a user has not chosen a language. The default language is also used as a fall-back language when a certain text is not translated to another language.

Languages

This is the list of languages in which your application will be available for users.

For each language, you can configure whether to check that all mandatory texts have a value. The default language is always checked. If a language is not checked and certain texts are not translated in Studio Pro, the default language is used as fall-back language. This means that you can run your application even though you have only partially translated your interface into a new language.

Certificates Tab

Certificates are used to connect to web services over HTTPS when the following requirements are met:

• The server uses a self-signed certificate authority, and/or
• A client certificate (certificate with a private key) is required

These certificates can be imported into Studio Pro using the Import button. Certificate authority files usually have a .crt extension, and client certificates usually have a .p12 or .pfx extension. After importing, use View details to acquire more information concerning the certificate.

Client certificates added here will be used whenever a server accepts a client certificate. If you upload more than one client certificate, one of them will be chosen based on the requirements of the server. If you need more control over client certificates, you should not upload the certificates here, but use the Runtime customization ClientCertificates, ClientCertificatePasswords, and ClientCertificateUsages settings.

Theme Tab

UI Resources Package

The look and feel of a Mendix application is governed by the UI resources package. This package supplies the app with all the required theme information accompanied by matching page templates and building blocks. The module which is designated as the UI resources package is governed by the UI resources package setting. Generally, this is automatically updated when a new UI resources package is imported. However, with this setting, the desired module can also be set manually.

⚠ Theme ZIP File

Older apps may still use a theme ZIP file as the basis for their theme. In this situation, the Theme ZIP file setting can be used to switch between any ZIP files found in the theme folder.

Switching from a ZIP file to a UI resources package is straightforward:

1. Firstly, replace the contents of the theme folder with the contents of the desired ZIP file.

2. Then, use the UI resources package setting described above to select a module. Ideally, this module should only contain UI documents, such as page templates and building blocks. This will allow you to export and import the module to other apps without worrying about reference errors.

3. Lastly, set the Theme ZIP file setting to None.

Marking as a UI Resources Module

Modules that contain theme styling should be marked as UI resources modules. To do so, right-click the Module {name} in the App Explorer, then click Mark as UI resources module. This will give the modules a green icon, which makes it easy to distinguish theme modules from other modules, and also influences the order in which styling will be applied from those modules:

Ordering UI Resource Modules

When a module contains styling (SCSS/CSS), be sure it is added to the compiled CSS file in the correct order relative to other files. For example, if a theme module should overwrite styling that is defined in Atlas_Core, it is important that the theme module is added after Atlas_Core.

You can set an explicit order in the theme settings (App Settings > Theme). This contains a list of all modules that are marked as UI resource modules, and allows you to set the explicit order in which they are added to the CSS file. Note that the lower a module is ordered in the list, the higher its precedence. For example, an app that uses a company theme module could be ordered as follows:

Workflows Tab

User Entity

User entity defines the entity which is used in target-users-using. If you assign a user task using an XPath, you can use attributes of this entity. If you are using a microflow, the entity defines the return type the microflows expects. For more information, see the Targeted Users Section section in User Task.

Optimization

Allows you to configure the maximum number of workflow and microflow threads that can be executed simultaneously by the Runtime. This is an advanced setting that gives developers control over app performance. Change these settings when you face performance issues on executing workflow instances or workflow-initiated microflows. The two values indicate the amount of threads that process the queues containing workflow instances or workflow-initiated microflows, for more information see Workflow Instance Threads and Microflow Threads sections below. App performance can be tracked (from Mendix 9.19 and above) using the following Task Queue metrics:

• mx.runtime.stats.taskqueue.queue-wait-time – the amount of time a task has to wait for execution
• mx.runtime.stats.taskqueue.queue-active-threads – the actual amount of threads executing tasks from the queue
• mx.runtime.stats.taskqueue.task-execution-time – time needed to execute a task from the queue

These metrics have a tag-named queue which has the following values relevant to workflow execution:

• System.MendixWorkflows-WorkflowExecution – a queue for workflow instance execution
• System.MendixWorkflows-DefaultTaskExecution – a queue for workflow-initiated microflows execution

If the waiting time of the queue increases and active threads in the queue reach the current maximum, it is advised to increase the maximum in settings.

Workflow Instance Threads

Defines the maximum number of threads that can process active workflow instances simultaneously. This setting does not relate to the amount of workflow instances that are active in the system.

Microflow Threads

Defines the maximum number of workflow-initiated microflows that the Runtime executes simultaneously. Workflow-initiated microflows are microflows defined as event handlers or microflow call activities defined in workflows. This setting has no influence on microflows executed by pages or other parts of the system.

Event Handlers

An event handler allows you to specify a microflow which is triggered when the subscribed event (or events) occur. Each event handler can subscribe to multiple events and there can be multiple event handlers. An event is triggered when the workflow or its activity goes through transitions which warrant the event. This setting is app-wide; you can override it by setting workflow-specific event handlers in workflow properties.

An event handler has the following configuration:

• Name – describes the event handler
• Documentation – provides more information regarding the usage of the event handler
• When – allows you to select the workflow event types, for which the handler should be triggered
• Microflow – allows you to select a microflow that should be triggered for each of the above selected workflow event types

You can use the data from the event handler microflow to build audit trails or for logging purposes. For example, you can define an event handler that only collects data from user task events.

For more information on workflow events, see Workflow Events.

⚠ Events (Deprecated)

Events allow you to set a microflow for workflow and user task state changes in your app.

Security settings of workflows and user tasks allow you to access workflow or user task data only if you have Admin rights or if the workflow/user task is targeted to you. Data from events allows you to build a dashboard or audit trails. For example, it can be useful for a manager to see progress of an employee onboarding process.

Workflow State Change

A microflow selected for this setting will start every time a workflow changes its state, for example, when the workflow is completed or has failed. This setting is app-wide; you can override it by setting a workflow-specific microflow in workflow properties.

User Task State Change

A microflow selected for this setting will start every time a user task changes its state, for example, when a user task is completed or paused. This setting is app-wide; you can override it by setting a workflow-specific microflow in workflow properties.

Dependencies Tab

This tab can be used to view the managed dependencies in your app in one place and to manage the dependencies in the userlib directory. It contains three tabbed sections.

Overview

This shows all the direct managed dependencies in your app listed by group and artifact. It shows which versions of the dependencies you have and which modules they are coming from. If your app reports multiple versions of the same group and artifact then the highest version is used, so having multiple versions of a dependency is not necessarily a problem.

Managed Dependency Exclusions

This shows all the managed dependencies in your app listed by package name. This overview includes both direct and transitive dependencies. If you have conflicts between different dependencies, you can uncheck here any files which you want to exclude. Ensure you leave at least one dependency which supports any calls made by your app or its dependencies.

Userlib Exclusions

This shows the libraries from the userlib directory and allows you to exclude them from deployment. Use this, for example, if there is an add-on module that ships with a different version of a library that is already in your ‘userlib’ folder.

Solution Tab

Settings on the Solution tab allow you to configure application distribution as an adaptable solution.

If you want to distribute your app as an adaptable solution package and allow upgrading it from the implementer’s side, you need to Enable solution adaptation on this tab. The title of your app in the App Explorer will change to Solution and the solution version will be displayed after the app name.

A distributable app must have a Solution version that you can set on this tab.

If you are implementing a solution, Based on setting shows the version of the solution package your app is currently based on.

Miscellaneous Tab

These settings determine the behavior of Studio Pro for this app. The settings apply to everyone that is working on this app.

Bundle Widgets When Running Locally

When deploying to the cloud, custom widgets are bundled to optimize client-server communication. When deploying locally, this step is skipped to accelerate startup duration. In some cases, this may obfuscate errors triggered by faulty custom widgets.

If this option is set, custom widgets will also be bundled locally. This mimics the production deployment, eliminating risk at the cost of start-up time.

Suggest Lower-Case Variable Names in Microflows

When enabled, the names that Studio Pro suggests in microflows will start with a lower-case letter instead of an upper-case letter.

Activity Default Colors

This table allows you to select a default color for each microflow activity type that is available in your app. The selected color will be used as the background color for all microflow activities of that type in your app. It is possible to override this default value for individual activities in the microflow editor. If you change the default color for an activity type, and there are activities of that type present in the app that have an individual background color specified, a dialog will be shown that allows you to apply the new default color to these activities as well.

Use Data Grid 2, Combo Box, and Image Widgets for Content Generation

If this setting is enabled, modern widgets like Data Grid 2, Combo Box, and Image will be used when generating overview pages or the content of data views. Existing generated content remains as is.

See the list below for detailed information on which widgets are generated in various circumstances:

• A Data Grid 2 module is generated instead of a Data Grid 1 module
• A combo box is generated instead of a combination of dropdown, reference selector, and input reference set selector widgets
• An image widget is generated instead of a static image widget and a dynamic image widget