Alfresco Troubleshooting: JMX Settings

The alfresco-global.properties file is a central place for Alfresco configuration and extension.  This properties file is created automatically during the Alfresco wizard installation.

While the use of a single central file for configurations simplifies management of Alfresco, any changes to settings made to the alfresco-global.properties file require that the server be restarted before the changes become effective.  In most cases, the global properties file is changed infrequently, so having to do a restart is not that much of a problem.

But if changes to the alfresco-global.properties file need to be made frequently, especially in a critical production system, it isn't desirable to have to restart the server whenever a configuration change is needed.

To enable configuration updates while the server is still running, Alfresco provides JMX as an alternative method for being able to change configuration settings on a system that is running.  Using a JMX client like JConsole, you can edit any configuration setting, and those changes then are persisted into the database and override any setting in the alfresco-global.properties file.

Note that JMX settings stored in the database take precedent over the settings found in the alfresco-global.properties file and that the alfresco-global.properties file does not get updated after a parameter is changed by JMX. 

What this means is that JMX is the ultimate source of the current settings and any other settings found in alfresco-global.properties. Note that configuration files may not be accurate because they have been overridden or outdated by JMX.  This is why very often when a troubleshooting case is submitted to Alfresco Support the first request from the Alfresco support team is to see a dump of your JMX system settings.

Instructions for how to download the JMX settings dump differ depending on which version of Alfresco you are running:

• Alfresco 4.0.x
• Alfresco 4.1.x
• Alfresco 4.2.x
• Alfresco 5.x

In earlier versions of Alfresco, JConsole was automatically included as part of a complete Alfresco stack install.  It was located in the java/bin directory of the Alfresco home area.  In Alfresco 5.2.x, you will need to download JConsole or other JMX tool.

Detailed instructions for how to access Alfresco via JMX can be found here, and a useful blog post about how to troubleshoot JMX setup issues can be found here.

The standard URL for accessing JMX on Alfresco is:

service:jmx:rmi:///jndi/rmi://<hostname>:50500/alfresco/jmxrmi

Default credentials to access Alfresco JMX are:

userid: controlRole
password: change_asap

One project for troubleshooting Alfresco is the GitHub project called Alfresco Support Tools. This project includes a number of useful tools for troubleshooting Alfresco systems.  The tools are available from the Enterprise Alfresco Admin Console.  After installing the AMP from this project, the following options become available, as shown below.

One feature of the Alfresco Support Tools project called JMX Settings.  This option shows a list of the parameters that have been overridden with JMX settings.
An example screenshot is shown below.

How can I reset the Batch Instance Identifier (ID) value in Ephesoft?

Sometimes, for an Ephesoft deployment, it is advantageous to reset the Batch Instance Identifier (ID) or BI#. This might also be required because there is a "feature", some would say a bug, in MariaDB where the sequence value will reset to '1' when there are no batches in the queue and the DB is bounced.

First, we should determine the current BI# using the following command:

            select ID from BATCH_INSTANCE;

NOTE: It will be the highest value returned.

Remember the Batch Instance Identifier is displayed in Hexadecimal format when viewed in the Ephesoft interface. However, we will use an integer when updating the BI# at the DB level and Ephesoft will convert it to a Hexa Decimal value.  In this first example, we will set the BI# to '40001'. Ephesoft will display this as 'BI9C41'.

           alter table BATCH_INSTANCE auto_increment = 40001;

You can check the value using the previous select statement after you submit your next batch.

If you want to start with a specific Hexadecimal value, say A100, you will need to first convert it to a decimal. In this case, the decimal value '41216' would be used.

            alter table BATCH_INSTANCE auto_increment = 41216;

NOTE: To verify that the change has occurred you will need to process a new Ephesoft batch.