Instance Directory Service

The Instance Directory is installed on a server and consists of a locally stored XML data file containing the instance information. This information is exposed through a network-wide discoverable Web Service, governed by a Windows Service. Since the Instance Directory serves all Case Manager applications on the network with instance information, there should only be one Instance Directory installed on a network. Applications will connect to the first Instance Directory to respond and disregard the rest. Multiple Instance Directories can consequently produce unpredictable and confusing behavior.

Installation

The Instance Directory Service installation file (setup.exe) can be found in the CaseManagerInstanceDirectoryService folder in CaseManagerServerApps. When running this setup file you will be prompted for an installation location. The default location is the CaseManagerInstanceDirectory. The setup installs:

• The Instance Directory Service application files
• A Windows Service called Case Manager Instance Directory
• The XML storage file: CaseManagerInstanceDirectory.xml
• A configuration file: CaseManagerInstanceDirectoryService.exe.config

Network Configuration

tip

More on Network configuration can be found in our Technical Overview

A discoverable web service is published and used by all Case Manager applications on the network to access instance information. Upon start-up of the web service, the current machine's IP address is detected and used to publish the web service. The default port for the Web Service is TCP port 3737. Web-Service Discovery requires an additional port: UDP port 3702. These ports should be opened on the server's firewall for incoming connections. Although direct access to the web service would, in general, not be required, it can be accessed via the following address to verify that it is running:

http://<ipaddress>:<port>/CaseManager/InstanceDirectory/Service

note

Older versions of the Instance Directory may still use the URL http://<ipaddress>:<port>/VoyagerNetz/InstanceDirectory/Service

It's important to note that discovery will only work on local networks. It makes use of a one-hop broadcasted UDP packet which will be blocked from traversing networks. Virtual Private Networks (VPNs) also block this communication. If your environment operates on such a network, you may have to use an alternative.

warning

The Instance Directory does not rely on any database and is, therefore, extremely lightweight and easy to install. The Instance Directory data is stored in a local XML file which is located in the installation folder of the service. To secure access to the data this location (CaseManagerInstanceDirectory) should not be shared on the network; it should only be accessible through the Web Service.

Starting/Stopping the service

The Case Manager Instance Directory Windows Service is automatically started during installation, and on start-up of the server. It can be accessed through “Services” in Windows Control Panel. The Services view shows all the installed Windows Services listed. Browse to the service named Case Manager Instance Directory. On right-clicking, you will be able to start or stop the service.

note

The installed Windows Services can also be viewed in the "Services" tab of the Windows Task Manager. However, if you have trouble starting/stopping the service from the Task Manager, rather open the "Service" settings directly.

Event Log

For the purpose of troubleshooting, events (such as errors that might occur in the Instance Directory Service) are logged in the Event Logs of Windows with log name CaseManager and source name InstanceDirectory.

note

Older versions of the Instance Directory logged event in the Windows Application Log with source name VN-InstanceDirectory.

Configuration

Web Service

The CaseManagerInstanceDirectoryService.exe.config configuration file (in the folder where the Instance Directory was installed), can be altered if you experience problems with publishing the web service. By default, when the Instance Directory starts up, it detects the address of the server it is running on and publishes the web service on that address (that is, the address the client applications will use to communicate with the Instance Directory). If there are multiple network interfaces on the server and the incorrect network is detected during this process, you can set up the Instance Directory to publish the web service on a specific address:

1. Open the CaseManagerInstanceDirectoryService.exe.config file in a text editor. The file is in an XML format.
2. Locate the AutoDetectNetwork setting and change the True to False:

   <setting name="AutoDetectNetwork" serializeAs="String">
       <value>True</value>
   </setting>
3. Locate the FixedIPAddress setting and change the value to the desired IP address (in this example, 10.0.1.12):

   <setting name="FixedIPAddress" serializeAs="String">
       <value>10.0.1.12</value>
   </setting>
4. Optional If you need to publish the web service on a different port, you can change the PortNumber setting. Remember to allow communication on this port through your firewall.

   <setting name="PortNumber" serializeAs="String">
       <value>4000</value>
   </setting>
5. Restart the Case Manager Instance Directory service.

Reset Password

The CaseManagerInstanceDirectory.xml file contains the instance information served to the client applications. It also includes an encrypted password to make changes to the Instance Directory. In general, the password is set and used in the Instance Directory Utility. Should you have lost the password for the Instance Directory, it can be reset to the default password by removing the following line from the file, and restarting the service.

<Security PasswordHash="{SOMECHARACTERS}==" />

For this reason, it is important that this location is not shared on the network and only accessible to administrative users with access to server.

Troubleshooting

Problem	Tests & Possible Solutions
Forgot Instance Directory Utility password	Reset the password Open the Instance Directory Utility and use the default password to log in and set a new password.
Directory not detected	Make sure the Instance Directory is installed and service is running. Check the configuration of the Instance Directory service to ensure that auto detect network is true or that the correct address is set. Check that UDP port 3702 and TCP port 3737 (or the port that was set in the configuration file) is open on the server. Open the web service URL in the browser (on the server and then on the client) to identify if a network problem exists. Open the Instance Directory Utility on the client machine to see if the directory is detected.
No instances detected	Open Instance Directory Utility and verify that visible instances are available.
Instance information incorrect	Open Instance Directory Utility and verify that only one Instance Directory exists on the current local network. It might be that the Local Instance Directory is not updated and out-of-date information is used to initialize the application. Verify that you can connect to the Instance Directory and that the application does not specify that the update should be skipped.
The Instance Directory service stops immediately after being started	Look at the Event Logs for the Instance Directory Service to see if an error message is logged.