Application Connections

Case Manager applications retrieve the connection details to the appropriate database from the Instance Directory. This gives an administrator centralized control. If, for example, there is a change in database server or path, the change of instance details in the Instance Directory will propagate to all workstations.

tip

Read the How does it work? section of the Overview, for a description of the steps in establishing the database connection.

Once the database connection is established, it will also verify that the application version is compatible with the selected instance (database) version.

Policies

Applications support a number of initialization policies that define the application behavior in establishing the database connection. An application has a default policy (behavior) which can be overridden by making use of Command-line arguments. Each of the policies specifies the following behavior:

• Update: The process by which the local copy of the instance information is updated from the Instance Directory Service.
• Selection: How the appropriate instance is selected from the available instances.
• Fail-over: The behavior when connection to the selected instance fails.

Available Policies

The following application policies (also referred to as Database Connection Factory Initialization Policies) are available:

AlwaysChoice

The AlwaysChoice policy will always give the user the option to choose the appropriate instance when more than one is visible in the directory (when only one is available, that instance will be auto-selected). Upon start-up, the application will first update the local instance directory information to ensure the most recent instance information is available locally, and it will give the user the option to select another instance if it fails to initialize. Applications that use this policy by default are the Case Manager Configuration Utility and the Case Manager Wall Dashboard.

ChoiceWhenNotExist

Applications making use of the ChoiceWhenNotExist policy will update the local instance directory information upon start-up, after which the default instance (or a specific instance as specified by a command-line argument) will be loaded. If the specified instance does not exist or the instance fails to load, the user will be presented with a choice of the available instances. Applications that make use of the ChoiceWhenNotExist policy are the Bulk Action Utility and the Content Manager.

FailWhenNotExist

The FailWhenNotExist policy operates similarly to the ChoiceWhenNotExist policy in that the local instance directory information is updated upon start-up and the default instance or a specified instance is used. The user, however, is never presented with a choice: the application fails when the instance does not exist or if it fails to load. For scheduled and automated processes this is generally the best policy to use. Applications that operate on the FailWhenNotExist policy are the Daily Maintenance Runner, the Process Runner, the SMS Merger, and the Windows Services for the Time- and Queue Servers.

PreviousChoice

The PreviousChoice policy will use the last successful configuration (instance) to initialize the connection of the application. After the update of the local instance directory information, the application will communicate to the user an option to reconfigure with a time-out of 5 seconds. If the user chooses to reconfigure, an option of all available instances is presented. Otherwise, the previous configuration is used. If the application fails to initialize with the relevant instance, a choice is also presented. The Time- and Queue Server Console Applications make use of the PreviousChoice policy.

RestartWhenChanged

Similar to the ChoiceWhenNotExist policy, the RestartWhenChanged policy makes use of the default instance (or a specific instance as specified by a command-line argument) and presents a choice of instances upon failure. The difference lies in the update of the local instance directory information. If the local instance directory information is available (that is, from a previous update), the initialization will take place concurrently with the update of the local information. If the updated information differs from the instance information used during the initialization, the application is restarted. This policy is only supported in applications that support restart (which depends on the implementation of the application). The Case Manager Windows Application makes use of this policy.

DirectDatabase

DirectDatabase is not strictly a policy as instance information is not used. It provides a mechanism of specifying the database connection details directly without making use of instances or the Instance Directory. The local instance directory information is not updated and the application will fail if the database connection initialization fails.

The Default Instance

The Default Instance is the name of the instance to be used by default and is stored in the Local Instance Directory per user (and per machine). Applications that make use of policies such as RestartWhenChanged, ChoiceWhenNotExist and FailWhenNotExist can make use of the Default Instance to initialize the application without prompting the user for the choice of instance.

The Default Instance is updated when the database connection details are changed in one of these applications. For example, when “Configure Database Connection Settings” is selected on the login form of Case Manager, the user is prompted to select a new instance to connect to. The instance will be stored as the Default Instance and will affect all applications dependent on the Default Instance.

Application Command-line arguments

All applications integrated with the Instance Directory support command-line arguments to override the default behavior in relation to the initialization process. This is especially handy when automated applications are scheduled. The following command-line options are defined in all Instance Directory integrated applications:

Help

More information on the supported command-line arguments can be found by running the application with the -help argument. This will guide the user on which options are available. The help option will override all other options and application behavior and will only display the help.

Output

The -output argument is used to specify how initialization error messages should be displayed. The available options are:

• Console: All error messages are displayed in the console from where the application was started. This option can be used when error messages are redirected to file. For example:

  application.exe –output=Console > error.log
• Application: Error messages are displayed through the application. If the application is a windows application, an error message box would be used.

Policies

The application behavior, in terms of the policies discussed in the Policies section in this document, can be specified in the application by making use of the –policy option. For example:

application.exe -policy=AlwaysChoice

Furthermore, for policies that support specified instances, the following two options may be used:

• DefaultInstance forces the application to make use of the default instance of the current user on the current workstation.
• Instance allows you to specify the instance to use by name. for example:

  application.exe -policy=FailWhenNotExist -instance=”Test database”

Direct Database

When an application should specify the database details directly without making use of the Instance Directory, the DirectDatabase option may be used to specify the following four parameters in a semicolon-separated list:

• DataSource specifies the server name or address.
• Port specifies the port that should be used. The default value is 3050.
• Path specifies the directory on the server where the database resides.
• Database specifies the name of the database file. For example:

application.exe –Direct="DataSource=127.0.0.1;Port=3050;Path=C:\;Database=CaseManager.fdb"

Overriding policy behavior

It is possible to make use of the policies as discussed so far without updating the local instance directory information and without the fail-over process, by simply adding these options:

• -NoUpdate will not update the Instance Directory.
• -NoFailOver will fail the application when a problem occurs during initialization.

Windows Services

For server applications, such as the Time Server and the Queue Server, we make use of technology that allows you to run the server either as a console application, or as Windows Service installation. The only Instance Directory-related command-line arguments that are supported are -instance and -help. For these service, there are a number of additional command-line arguments to support the installation processes.

Installed services are linked to specified instance names which form part of the name of the Windows Service. This makes it easy to identify the running service and process. The instance name also forms part of the event source name (Windows Event Log) to track event messages for the specific running service. Due to the tight link between the running Windows Service and the Case Manager instance name, it is not possible to run these services on the Default Instance or a Direct Database connection.

User Login Command-line arguments

Case Manager applications also support command-line arguments to specify user login details. This is especially useful when scheduling applications to run without user intervention: such as the Daily Maintenance Runner. More information on these arguments in the User Management section.

Process Runner

The Process Runner is designed to run instance processes as a schedulable program. The only process currently supported by the Process Runner is the Backup process (BackupInstance). As the application is integrated with the Instance Directory, all the command-line arguments discussed above (except the login-related arguments) apply. In addition to that, the arguments should specify the process and the arguments related to the process.

To view help on the Backup process, run the Process Runner with the following arguments: -process=BackupInstance –help

The following three arguments, as mentioned in the help, can be specified for the BackupInstance process:

• BackupDirectory: the directory where the backup file should be stored.
• LogDirectory: the directory where the backup log should be stored.
• GarbageCollection: true or false, whether or not garbage collection should be done.

tip

When specifying a path as a command-line argument, and the path contains spaces, encapsulate the entire argument in quotation marks. For example:

CaseManagerProcessRunner.exe -process=BackupInstance "-BackupDirectory=C:\Path With Spaces\"

Instance Directory Alternatives

The Instance Directory makes use of WS-Discovery to detect where a running web service (in our case, the Instance Directory Service) is running on a local network. The Instance Directory Service can only be detected from a workstation on the same local network. Even when connecting on the same VPN you may have trouble automatically detecting the Instance Directory. For these cases we recommend one of two alternatives:

Server Name

If the server name (where the Instance Directory Service is running) is CaseManagerServer, client applications will be able to connect to that Instance Directory without discovery.

Registry Setup

You can also explicitly specify the address of the Instance Directory by adding a specific record to the Windows Registry on each of the workstations. A script (.reg) in the CaseManagerTools folder can be edited to specify the correct server location and executed on each of the workstations.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\CaseManager\InstanceDirectory\Local\1.1]
"DirectInstanceDirectoryUri"="server address here"

When this line is added, the behavior on that machine will be overridden to never try to detect the Instance Directory Service, but instead directly try to connect to the specific address. Note that this requires additional setup on each of the workstations, and will also need to be updated if ever the network location of the Instance Directory Service changes.

Troubleshooting

Problem	Tests & Possible Solutions
Cannot connect to instance directory	Ensure the Instance Directory Service is running on the server Verify that the Network Configuration is correct, and try to access the Instance Directory URL from a browser on the workstation. The workstation should be on the same local network (not VPN) as the Instance Directory Service. Otherwise, consider an alternative to discovery The Instance Directory should be published on the correct network adapter. If the server has multiple network adapters the incorrect one may be selected during startup. You can view the Event Logs to see the address the service is published on. If this is incorrect you may have to configure the service to publish on a specified fixed address.
No instances available	Open the Instance Directory Utility and check that the instance is set up and visible When opening the utility, make sure only one Instance Directory is detected on the network. If there are multiple you need to uninstall the incorrect one.
Incorrect version	If the database/instance version is indicated to be older than the application version, you may need to upgrade the database to the correct version. If the application version is older than the instance/database version, your application needs to be upgraded: Verify the version of the ClickOnce installation files in the CaseManagerApps folder If your application is not automatically updated, it may be that it was originally not installed via the correct network path. Uninstall the application, browse to the installation files in the CaseManagerApps folder via the network, and reinstall the application
Application fails to open after selecting instance	Extensions often are the cause of this problem. From the tools menu on the login screen select Safe Mode and log in again. This will disregard all extensions. If the login is successful, there is a faulty (or old) extension causing this problem. You can determine which extension is causing the problem by individually disabling the extensions in the Configuration Tools