Skip to main content
Version: 6.0

Instance Directory Utility

A locally ClickOnce published utility is provided to set up and administer the Instance Directory. The utility can also detect multiple Instance Directories on a local network (which can cause some trouble in the application behavior), and provides instance-related processes such as backup and restore, database user verification, and Case Manager version upgrades. This document will provide the user with an understanding of how the Instance Directory Utility functions and provide the necessary knowledge to operate this utility.

Installing the application​

The Instance Directory Utility is installed as a ClickOnce application found in the CaseManagerApps folder. ClickOnce application should ably be installed (that is, running the setup.exe) directly from the network location (the CaseManagerApps folder) and not copied to the workstation before installation. This ensures that when an update is added to the CaseManagerApps folder, the installed application will automatically update. Also, remember to first install the CaseManagerVerifyPrerequisites application, if you have not already done so.

Opening the Instance Directory Utility​

When the Instance Directory Utility opens it detects the running instance directory on the network. This process differs from the Instance Directory connections of other applications, in that Instance Directory Utility will detect all running Instance Directory Services, as opposed to just detecting the first to be found.

Instance Directory Detection

The aim of this form is to select the Instance Directory to set up. It shows the following:

  • The progress bar at the top shows when the detection process is running. You can cancel the process by clicking the cancel button. After the process completed you can click the refresh button to rerun the detection process.
  • The Discovered Instance Directories shows all the running Instance Directory Services found on the local network. You may select the address from this control and click Configure to set up the selected Instance Directory.
  • You also have alternatives to the detected Instance Directories:
    • Saved Instance Directory Location is available only if a specific address is set in the registry on the current computer. Clicking Configure on this option will set up the Instance Directory running at this address.
    • Use application without Instance Directory makes limited functionality provided by Instance Directory Utility available without a connection to an Instance Directory Service. You need to explicitly specify the database connection details, and will have access the backup and restore processes, and the upgrade process.
  • If you do not wish to continue with setting up the Instance Directory, you may simply click the Close button.
warning

This Instance Directory Discovery form shows all the running Instance Directories accessible from the current location. It is very important that you only see one listed. If there are multiple detected, application may connect to Case Manager databases based on the information from any Instance Directory, resulting in unpredictable behavior and loss of centralized control.

Utility Overview​

After selecting to configure an Instance Directory, you will see the main utility that shows all the currently available instances. The toolbar button are grouped into three sections:

  • Security: Login and password actions (on the left)
  • Basic instance operations: basic operations to create, edit, or delete instances (on the left)
  • Instance Actions: actions that can be executed on the selected instance - such as backup, restore, or upgrade (on the right)

Instance Directory Utility

Security​

The Case Manager Instance Directory Utility implements basic security to control modification of the instance data. The visible instance information can be viewed by anyone, but can only be changed when logged in. This security is not related in any way to general Case Manager security and only allows changes to the Instance Directory. When you first open the application, you will therefore only see the visible instances. To see the invisible instances, and to make changes to the instance information you need to log in.

  • Log in Button The locked button shows that you currently not logged in. Clicking this button will prompt you for the password to log in.
  • Log out Button The unlocked button shows that you are currently logged in. Clicking this button will log you out.

Default password for the Instance Directory is badpassword. When you log in you will be asked to change the password.

You can change the password by clicking the Edit Security Settings Button Edit Security Settings button.

tip

If you have lost the password of the Instance Directory, it can be reset by a user with access to the server.

Instance Visibility​

The Instance Directory allows you to turn the visibility on or off for a specific instance. This means that instances can be hidden from users accessing Case Manager applications. Visibility is indicated by the circle icon on the instance in the utility:

  • Visible Instance A blue circle shows that the instance is visible.
  • Invisible Instance A grey circle shows that the instance is not visible to client applications. You can set the visibility of the selected instance by either the Edit Instance action, or by making use of the toggle instance visibility button: Toggle Instance Visibility Button

Add instance​

You can add a new instance to the Instance Directory by clicking the Add Instance button on the toolbar. You will need to choose a unique instance name by which the client applications will access the database. You will not be able to edit the instance name after it has been created.

Create a new instance

Here you can specify the location of the Case Manager database associated with this instance:

  • Server Name specifies the network address client application will use to communicate with the database server.
  • Database Directory is the folder where the database file (.fdb) is located; typically CaseManagerDatabases
  • Database Filename is the name of the database file (.fdb).
  • Port specifies the port number that the Firebird Database Server is running on the server. By default, this is 3050.

Test Database Connection​

The Add and Edit forms have a Test Database Connection button which verifies if the entered database details points to a Case Manager database. The version number of the database at this location will be shown if a database is found.

Delete instance​

A selected instance can be removed from the Instance Directory. This instance will no longer be available to connect to by client applications, and will not be available in the Instance Directory anymore.

Edit instance​

You can edit an instance either by clicking the Edit instance button on the toolbar, or by double-clicking the instance. The instance form (as with Adding an instance) allows you to edit all of the instance information except for the name of the instance. Since client applications may make use of this name, explicitly, to connect to an instance, editing of the name is not allowed.

Actions​

Backup​

The Backup Database function allows you to back up the currently selected database instance. Database backup files are stored with a .fbk file extension at the specified location. During the backup process you can create/view a log of information about the data backup process:

  • Logging to *screen shows the log on the backup form. Note that this can make the backup process significantly slower - especially for larger databases.
  • Logging to file requires a folder path where the log file can be saved. Typically, the log file is saved to the same directory as the backup file. Database backups can be done with garbage collection on or off. Garbage collection removes old recorded versions that aren’t needed anymore. This works like a sweep and can be done manually or automatically by turning garbage collection on or off during the backup process. It can, however, increase the time it takes for the backup to complete.

Restore​

The Restore Database function allows you to restore a current database with past backups that were created (.fbk files). As with the Backup Process, the restore log can also be viewed/created. Similar to the backup process:

  • Logging to screen shows the log on the restore form, and can also make the process significantly slower.
  • Logging to file requires a folder location where the restore log can be saved.

Verify Database Users​

The Firebird database engine needs to be aware of the database users Case Manager uses to access data. This process should be executed once for the database engine installation to verify these users. That is, you do not have to run this process per database. Especially on a first installation of the server where you may not already have an available database, you may receive an error running this process. Instead, please run the CaseManagerVerifyDatabaseUsers console application found in the CaseManagerServerApps folder. Note that this application cannot be run from a client workstation: it needs to run on the same computer that the Firebird Database Engine was installed on. During this process (when running either the action in the Instance Directory Utility, or the CaseManagerVerifyDatabaseUsers console application) you will be required to enter the Firebird System Administrator (SYSDBA) password that was set up during the installation of the Firebird server.

tip

If the Verify Database Users action in the Instance Directory Utility fails, rather run the CaseManagerVerifyDatabaseUsers application found in the CaseManagerServerApps folder.

Upgrade Database​

The Upgrade Database action allows you to upgrade the database of the selected instance to a new version of Case Manager. More on this the Upgrading a database section of this document.

Upgrading a database​

During an upgrade of Case Manager, application files are copied into the CaseManagerApps folder. With ClickOnce applications, such as the Instance Directory Utility, the new version of the application will be detected when opened and the updated version will be installed. The details required to upgrade the database to the new version is installed with the Instance Directory Utility, and accessed by the Upgrade Database action. At opening this, you will be asked whether you would like to make a backup of the database. If you have not already done so before starting this process, it is highly recommended.

tip

When upgrading a database to a new version:

  • Familiarize yourself with the changes that will be applied, and pay special attention to the warning communicated. This may include changes to extension, data, and requirements which need to be taken into consideration before upgrading.
  • Always make a backup of the database. If there is a problem during the upgrade, you can then restore the database to its state before the upgrade was started.
  • Make sure no users are using the Case Manager applications during the upgrade. It is also recommended to stop the Time Server and the Queue Server, and all scheduled tasks before running the upgrade

Version Selection​

The Upgrade Database action will present you with the available Case Manager versions to which you can upgrade. It's important to note that you can only upgrade and never downgrade to a previous version, unless the version you wish to downgrade to only differs in the very last number in the version number (called the Revision number).

Upgrade - Version Selection

  1. You can browse through the available versions and read the release notes and warnings for each. Typically, since you already updated the application files to the latest version, you will select the latest version to upgrade the database to. After selecting the version, you can click the Upgrade button to continue.
  2. A document with all the warnings and release notes for this upgrade is generated. You can confirm that you wish to continue, by clicking the Continue button. You also have the option to print this document.
  3. The Upgrade Process will start.
tip

If you wish to see the release notes and warnings for historic versions, you can access these by clicking on the Tools menu on the version selection form. This gives you the option to generate a release notes and warnings document for a specified from and to version. Historic Release Notes

Upgrade Process​

The upgrade process shows a progress bar with an indication of the upgrade statement currently executing. Some of these statements can run a long time on large databases. If no message is displayed, please leave the statement running and do not attempt to stop or restart the process. Once all the statements are executed, a message will indicate that the upgrade is complete. If you encounter a problem (an error message) with the upgrade, please contact one of our consultants. Also, please communicate the version and statement number mentioned in the error message to the consultant.