Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Management Console (3.7)
  3. Upgrading the Management Console

  4. Upgrading to MMC with an External Database

Upgrading to MMC with an External Database

Enterprise

*MMC Version 3.4.2 and Later*

Overview

In the Mule Management Console, the process for persisting MMC data on external databases has been greatly simplified. The configuration files employed for data persistence have changed, so if you are upgrading from an older version of MMC before version 3.4.2, you need to migrate your data persistence configuration to the new and simpler configuration files.

Note that you do not need to migrate your database configuration if you are using MMC’s default internal databases for data persistence. You are only required to migrate your database configuration if you are persisting MMC environment or tracking data to an external database.

If your current installation of MMC uses LDAP for managing users, you also need to migrate your LDAP configuration. See Upgrading to MMC with LDAP for details.

Assumptions

You have MMC 3.4.1 or earlier installed and configured to persist its environment and/or transaction data to an external database, and are about to upgrade MMC to its latest version.

Persisting Environment Data

In MMC versions 3.4.1 and earlier, the configuration for persisting environment data on an external database is stored in the following files:

  • <MMC_HOME>/WEB-INF/classes/META-INF/mmc.properties

  • <MMC_HOME>/WEB-INF/classes/META-INF/jackrabbit-repo.xml

These files store connection parameters to the external database such as username, password, etc. You need to adapt these parameters to the new config files, so ensure that you keep a copy of these files before removing your current MMC installation.

Also, for safety, back up your current MMC installation’s mmc-data directory, which is under the root directory of your Web application server.

After you downloaded and expanded the .war file for your new MMC, your new MMC home directory (the root directory of the expanded .war) and locate the following directory: <MMC_HOME>/WEB-INF/classes/META-INF/databases. This directory stores configuration files for database persistence. These files are named in the format: <type of data>-<database name>.properties, where:

  • type of data = mmc for environment data, or tracking-persistence for transaction data

  • database name = name of the database server to use, for example postgres

For example, the file mmc-oracle.properties stores properties for connecting to an Oracle database that stores environment data; the file tracking-persistence-postgres.properties stores properties for connecting to a Postgres database that stores tracking data, etc.

These files define the parameters for connecting to the database: driver, user, password, host, port, and others.

To migrate the configuration for persisting environment data, complete these steps:

  1. In the new MMC install, locate the relevant mmc-<database>.properties file according to the database you wish to connect to, and open it for editing.

  2. In old your old MMC installation, open the file mmc.properties to extract the relevant parameters and values.

  3. Using the parameters and values from the old mmc.properties file, modify the relevant mmc-<database>.properties file in the new MMC install, migrating the values to the new config format according to the table below.

    Parameter name in old MMC version Parameter name in new MMC versions Notes

    datasource.username

    env.username

    datasource.password

    env.password

    datasource.url

    env.host

    From the value of datasource.url, extract the host where your database server resides, and assign it as the value of env.host in the database config file in your new MMC.

    For example, if your database resides at host dbserver, from datasource.url=jdbc:mysql://dbserver/mmc_persistency_status extract dbserver to env.host=dbserver in the new config file.

    datasource.url

    env.port

    From the value of datasource.url, extract the port on which your database server is listening, and assign it as the value of env.port in the database config file in your new MMC.

    For example, if your database resides at host dbserver port 9155, from datasource.url=jdbc:mysql://dbserver:9155/mmc_persistency_status extract 9155 to env.port=9155 in the new config file.

    Note that if the port number is not present in the URL, it probably means that the default port for the database server is being used, for example 1521 for Oracle, 3306 for MySQL, etc.

    datasource.url

    env.servicename (Oracle only.)

    From the value of datasource.url, extract the Oracle service name for your connection, and assign it as the value of env.servicename in the database config file in your new MMC install.

    For example, if the value of datasource.url in the old MMC installation is jdbc\:oracle\:thin\:MMC_STATUS/mmc123@dbserver\:1521\:xe, then the service name is xe. Assign it in the new config file with the parameter env.servicename=xe.

  4. In the jackrabbit-repo.xml file from your old MMC installation, locate the definitions of the workspace name and the default workspace name. You can find them in the following section:

    <Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="mmcworkspace"/>
    <!--
        workspace configuration template:
        used to create the initial workspace if there's no workspace yet
    -->
    <Workspace name="mmcworkspace">

    In the example above, both the workspace name and the default workspace name are mmcworskpace.

  5. In the MMC install, go to the <MMC_HOME>/WEB-INF/classes/META-INF/jackrabbit directory, then locate the jackrabbit-repo file relevant for your database, for example jackrabbit-repo-postgres.xml if persisting data on Postgres. Open the file for editing.

  6. Find the workspace name declaration in the new jackrabbit-repo file, and ensure that the workspace name and the default workspace name coincide between the old and new versions of MMC.

  7. Check that the values of all schemaObjectPrefix declarations in the jackrabbit-repo file for the new MMC installation follow the values declared in the jackrabbit-repo file of your old MMC installation. For example, if your old MMC jackrabbit-repo file contains the following:

    <Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="mmcworkspace"/>
    <!--
        workspace configuration template:
        used to create the initial workspace if there's no workspace yet
    -->
    <Workspace name="mmcworkspace">

    and the relevant declaration in the new jackrabbit-repo file reads:

    <Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="mmcworkspace"/>
    <!--
        workspace configuration template:
        used to create the initial workspace if there's no workspace yet
    -->
    <Workspace name="mmcworkspace">

  8. Modify the new jackrabbit-repo file to read exactly as the old jackrabbit-repo file – in this case, in the new install change the value of schemaObjectPrefix to ws1_. Be sure to repeat this operation for all schemaObjectPrefix declarations in the files.

  9. Save and close the new jackrabbit-repo file.

  10. In your MMC install, locate the file <MMC_HOME>/WEB-INF/web.xml and open it for editing.

  11. In the web.xml file, locate the section shown below.

    <context-param>
<param-name>spring.profiles.active</param-name>
<param-value>tracking-h2,env-derby</param-value>
</context-param>

  12. Replace the string env-derby with env-<database_name>. For example, if persisting data on postgres, replace it with env-postgres.

  13. After completing the above steps, you can remove your old MMC installation by deleting its home directory in the root directory of your Web app server. However, it is recommended that you keep the backup copies of the old database configuration files until you ensure that your new MMC connects properly to the database.

If needed, ensure that you have copied the Quartz drivers from your older version of the MMC WAR file to the new MMC WAR file. A WAR file is a zip file that you can open with a zip file tool such as 7-Zip in Windows or the Mac’s built in Archive Utility. In the current MMC distribution, the war file is in this tree: 
mmc-distribution-mule-console-bundle-3.7.0
  mmc-3.7.0
    apache-tomcat-7.0.52
      webapps
        mmc-3.7.0.war

The Quartz drivers reside in the unzipped WAR file’s WEB-INF > classes > quartz folder.

After you have completed configuration, start your new MMC.

Persisting Transaction Data

In MMC versions 3.4.1 and earlier, the configuration for persisting transaction data (Business Events) on an external database is stored in the following files:

  • <MMC_HOME>/WEB-INF/classes/META-INF/persistence.xml

  • <MMC_HOME>/WEB-INF/classes/mmc-persistence.properties (if present on your installation)

  • <MMC_HOME>/WEB-INF/classes/META-INF/applicationContext-tracking.xml

These files store connection parameters to the external database such as username, password, etc. You need to adapt these parameters to the new config files, so ensure that you keep a copy of these files before removing your current MMC installation.

Also, for safety, back up your current MMC installation’s mmc-data directory, which is under the root directory of your Web application server.

After you downloaded and expanded the .war file for your new MMC, enter your new MMC home directory and locate the following directory: <MMC_HOME/WEB-INF/classes/META-INF/databases. This directory stores configuration files for database persistence. These files are named in the format: <type of data>-<database name>.properties, where:

  • type of data = mmc for environment data, or tracking-persistence for transaction data

  • database name = name of the database server to use, for example postgres

For example, the file mmc-oracle.properties stores properties for connecting to an Oracle database that stores environment data; the file tracking-persistence-postgres.properties stores properties for connecting to a Postgres database that stores tracking data, etc.

These files define the parameters for connecting to the database: driver, user, password, host, port, and others.

Migrate Persisting Tracking Data

To migrate the configuration for persisting tracking data, complete these steps:

  1. In your old MMC installation, open the file applicationContext-tracking.xml, then locate the bean dataSource, shown below.

    <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
    <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver" />
    <property name="url" value="jdbc:oracle:thin:@127.0.0.1:1521:xe" />
    <property name="username" value="TRACKER" />
    <property name="password" value="tracker" />
</bean>

  2. Migrate the values in the code above to the database config files in your new MMC.

    Depending on the configuration in your old MMC installation, some of the values displayed in the code above may actually reside in persistence.xml or mmc-persistence.properties.

  3. In your new MMC, locate the relevant tracking-persistence-<database>.properties file according to the database you wish to connect to, and open it for editing.

    Using the parameters and values from your old MMC installation, modify the relevant mmc-<database>.properties file in your new MMC install. Migrate the values to the new config format according to the table below.

    Parameter name in old MMC versions Parameter name in new MMC versions Notes

    username

    mmc.tracking.db.username

    password

    mmc.tracking.db.password

    url

    mmc.tracking.db.host

    From the value of url, extract the host where your database server resides, and assign it as the value of mmc.tracking.db.host in the database config file in the new installation.

    For example, if your database resides at host dbserver, from datasource.url=jdbc:mysql://dbserver/mmc_persistency_status extract dbserver to mmc.tracking.db.host=dbserver in the new config file.

    url

    mmc.tracking.db.port

    From the value of url, extract the port on which your database server is listening, and assign it as the value of mmc.tracking.db.port in the database config file in the new installation.

    For example, if your database resides at host dbserver port 9155, from datasource.url=jdbc:mysql://dbserver:9155/mmc_persistency_status extract 9155 to mmc.tracking.db.port=9155 in the new config file.

    Note that if the port number is not present in the URL, it probably means that the default port for the database server is being used, for example 1521 for Oracle, 3306 for MySQL, etc.

    url

    mmc.tracking.db.servicename

    From the value of url, extract the Oracle service name for your connection, and assign it as the value of mmc.tracking.db.servicename in the database config file in the new installation.

    For example, if the value of url in your old MMC installation is jdbc:oracle:thin:MMC_STATUS/mmc123@dbserver:1521:xe, then the service name is xe. Assign it in the new config file with the parameter env.servicename=xe.

  4. In the new MMC install, locate the file <MMC_HOME>/WEB-INF/web.xml and open it for editing.

  5. In the web.xml file, locate the section shown below.

    <context-param>
<param-name>spring.profiles.active</param-name>
<param-value>tracking-h2,env-derby</param-value>
</context-param>

  6. Replace the string tracking-h2 with tracking-<database_name>. For example, if persisting data on postgres, replace it with tracking-postgres.

  7. After completing the above steps, you can remove your old MMC installation by deleting its home directory in the root directory of your Web app server. However, it is recommended that you keep the backup copies of the old database configuration files until you ensure that your new MMC connects properly to the database.

    The exact configuration details in your old MMC installation may vary. Before deleting your old MMC installation, make complete backups of all relevant config files. Bear in mind that aside from the database connection parameters listed in this page, a custom configuration may contain additional parameters not listed here, which you also need to migrate to the new configuration.

  8. After you complete the configuration, start your new MMC.

See Also