Database integration

Aware IM requires database software to function correctly. At the moment Aware IM is compatible with the Apache Derby, MySQL, Microsoft SQL Server/Azure, Oracle, PostgreSQL and Maria DB databases¹⁾. MySQL, Maria DB, Oracle, PostgreSQL and MS SQL Server databases are not included in the Aware IM installation.

Apache Derby is included in Aware IM and does not require any additional integration.

Integrating Aware IM with MySQL database

If you do not have MySQL database software you can download one free of charge from the MySQL web site at https://dev.mysql.com/downloads. Run MySQL installation program and follow the instructions (see MySQL Installation Guide for details). We recommend that you install MySQL as a Windows service. Once the installation has been completed make sure that MySQL is running and perform the integration steps described below.

1. Start the Aware IM Control Panel
2. Select the Settings/Database menu item and select MySQL as the database engine
3. Enter credentials of the MySQL account. Note that the account you specify here must have root user privileges, otherwise Aware IM will not work
4. Specify MySQL server name and the port number where MySQL listens to requests (if these are different from the default values)
5. Click OK and restart Aware IM

If you installed Aware IM as Windows service you can perform database integration manually without using the Aware IM Control Panel. To do this:

1. Delete the default AwareIM/bin/BASServer.props file which contains default database settings
2. Rename the file BASServerMySQL.props to BASServer.props
3. Use any text editor to change server name, port and root user credentials to the following lines in the BASServer.props file:

DriverURL=jdbc:mysql://localhost/BASDB?user=root&password=blah
DriverTestURL=jdbc:mysql://localhost/BASDBTEST?user=root&password=blah
BootstrapURL=jdbc:mysql://localhost/?user=root&password=blah

If you do not have MS SQL Server database software you can download the free version (SQL Server Express) from the Microsoft web site. Make sure that MS SQL Server or SQL Server Express is running and perform the integration steps described below.

<note important>Support for the full version of MS SQL Server database is optional in Aware IM. Before integrating this database with Aware IM make sure that this option is available in your Aware IM edition.</note>

1. Make sure that your MS SQL Server database is configured to use TCP/IP protocol – please refer to the MS SQL Server manual for details.
2. Start the Aware IM Control Panel
3. Select the Settings/Database menu item and select SQL Server as the database engine
4. Enter credentials of the SQL Server account.
5. Specify SQL server name and the port number where SQL Server listens to requests (if these are different from the default values)
6. Click OK and restart Aware IM

If you installed Aware IM as Windows service you can perform database integration manually without using the Aware IM Control Panel. To do this:

1. Delete the default AwareIM/bin/BASServer.props file which contains default database settings
2. Rename the file BASServerMSDE.props to BASServer.props
3. Use any text editor to modify the following lines in the BASServer.props file located in the BIN directory of your Aware IM installation:

DriverURL=jdbc:sqlserver://localhost:1433;user=sa;password=password;databaseName=BASDB
DriverTestURL=jdbc:sqlserver://localhost:1433;databaseName=BASDBTEST;user=sa;password=password;
BootstrapURL=jdbc:sqlserver://localhost:1433;user=sa;password=password;
DriverClassName=com.microsoft.sqlserver.jdbc.SQLServerDriver
DatabaseComponent=com.bas.basserver.persistence.dbplugins.MSSQLServerInterface

Change values for user and password properties in the first three lines above to provide the credentials of your MS SQL Server account.

If you are running a specific instance of the SQL Server configure this instance to listen on a particular TCP/IP port and specify this port in the URL above

If Aware IM does not start it could be for reasons described in the following table (which also suggests what to do):

IMPORTANT: Support for Oracle database is optional in Aware IM. Before integrating this database with Aware IM make sure that this option is available in your Aware IM edition.

You need to install Oracle database prior to using Aware IM as it is not included in the Aware IM installation. Before you can start using Aware IM with the Oracle database make sure you do the following:

1. Aware IM manages two databases named BASDB and BASDBTES. The databases must be created manually before using Oracle with Aware IM. Aware IM will NOT create the databases automatically. It is enough to create empty databases without creating any tables – Aware IM will create all the required tables automatically on the first startup.
2. Perform the steps to setup Aware IM connection with the Oracle database using the Aware IM Control Panel in a similar way as for MySQL or SQL Server databases described above. Or if Aware IM is installed as a service, perform manual integration in a similar fashion as described for MySQL and SQL Server databases.

Integration with these databases is very similar to the one described for MySQL or SQL Server databases. When integrating using the Aware IM Control Panel, make sure that you select the corresponding database engine and enter the required values for the database server. If integrating manually, make sure that you rename the appropriate BASServer.props file and change the lines in these files that control database connection.