Web service / SOAP server


In the beginning there were no plans for any kind of remote access. But later I wanted to support bidirectional communication between customers and suppliers. The first idea was to make a web application, but that meant making two different applications - with duplicate logic and possibly out of sync functionality. Also, these so called lightweight applications, are not really light. For any reasonable GUI they generate a huge amount of network traffic. Every request must load not only the data, but also the complete presentation layer. So I decided to use a web service. The network traffic is minimized because only work data are transfered and they are packed and protected by password. SSL is not really needed, but you can use it.

The web service is installed as part of the normal install. The necessary files are placed in the SOAPService sub directory under the myTracker install path. It works as a LoadModule in Apache and an IISProcess in IIS.

Like the server and client console the settings of the Web service is driven by a server.ini file - in the SOAPService directory.

1. Set up Web service email

NB!: You have to set up the Web service email for notification to work.

Since we are working with a web service you should only install the email as an SMTP connection. It is unlikely that the Apache server where the SOAP server will, will make use of MAPI email.

To set the email settings for the web service you have to add the email configuration line to the server.ini file manually. The easiest way to do that is to enter the email settings that the web service will use in the server console. This will create the correct line in the server.ini file where you can copy it from. Open the server.ini file in the Server Console directory and copy the line MailClientSettings to the settings section of the server.ini file in the web service directory:


The components of the string are as follows:

2. Set up the web server

2.1 Apache web server 1.3.xx

At this point in time Apache 2 is not supported. To set-up the web service to run on Apache you must enter the following lines in the httpd.conf file (after the last AddModule directive):

LoadModule myTracker_module "[InstallPath]/SOAPService/myTracker.dll"
<Location /mytracker>
SetHandler myTracker-handler

Please note the quotes above. Replace [InstallPath] with the path to the myTracker directory on the server (use "/" instead of "\"). Restart the Apache server for this to take effect.

If you are having problems connecting to the web service, try to commenting out the following line:

2.2 Microsoft IIS 5.0

  1. Add a new virtual directory such as MyTracker.
  2. Set the Local path to [InstallPath]/SOAPService.
  3. Set the execute permission to Scripts and Executables.
  4. Set application protection to Low (IIS Process)

3. Set-up Web service to connect to database

The client console connects to the web service and the web service in turn connects to the database. This means that a server registration (connection) string is needed in the server.ini file of the web service.

What is the correct address?
For Apache http://server/myTracker
For IIS http://server/myTracker/MytrackerISAPI.dll
If you put it into your browser you should get something like this

The server console has the functionality to pass the correct database registration (connection) string to the web service - as follows:

  1. Start the server console.
  2. Select SOAP server from the server menu. This brings up the SOAP servers dialog:

  3. Enter the URL for the SOAP server and press the -> button. If the web service is not running you should get an error message, This is the easiest way to see if you have set-up the web service correctly and can connect to it.
  4. Press the + button. This will bring up the list of databases registered with the Server console - the same list that you get when you connect to a database in the Server console. Pick the database you want to run as a web service and press OK. This will connect to the SOAP server and pass the correct connection settings, which the SOAP server will store in the server.ini file in the SOAPservice directory.

Please note: To make sure that you do not get the wrong connection string in the SOAP server.ini file it is suggested that you install and use the server console from the same machine as the SOAP server to accomplish the above task. If you also use the Server console from another machine to administer the database then it is possible that that connection string does not work on the web service machine. If you are on the same machine, you know that the correct settings is stored by the SOAP server.

It is also a good idea to use this same Server concole to create the inital database. Then you can configure the Firebird server to use an alias to point to this database and you would not need to use a path in your connection strings.

The connection string to the database can be found in the [Servers] section of the server.ini file in the SOAPservice directory under the myTracker install path and looks like this:


The components of the string are as follows:

4. Connecting to the web service

Only the client console can connect to the web service. So the server registration of the client must be changed to point to the web service. The Server console does not connect to the web service, it connects to the Firebird SQL server directly. Using the Send project registration (from the View menu in the server console) will send the registration string for the same direct connection. So this option won't work. The registration string must be entered by hand.

To configure the Client console to connect to the web service, do the following:

  1. Start up the client console.
  2. Select register server from the server menu.
  3. For connecting to an Apache web server enter the following Server string:
  4. For connecting to an IIS web server enter the following Server string:
  5. If you connect to a proxy server then you will have to set up the proxy settings Proxy server setting tab in the Settings window after selecting Settings from the Server menu.

  6. To use the web service you connect as normal (Connect to server from the Server menu). Pick ClientServerName of the web service you have just entered and you are connect via the web service.

The components of the registration string are as follows:

You can also manually enter the server registration string in the server.ini file in the Client console directory. If you are deploying to many clients it is probably a better idea to have an "empty" basic server.ini file with the server and email settings configured and send it to the users to copy into their Client console directory. By basic we mean an ini file with the [Servers], [Database] and [Settings] sections pre-configured.

5. Restarting the Web service - Important!!

The web service communicates with the client by XML files. These are created in the SOAPservice directory. Some of these are only created when the web service is called by a client for the first time. If you make changes to the configuration of your myTracker system then these changes will not necessarily show in the clients connecting to the web service while they will show when connected directly to the Firebird server.

In order to make sure that your web service is properly updated after you have made changes with the server console, you have to restart the SOAP server. This is done as follows:

  1. Start up the server console.
  2. Select SOAP server from the server menu. This will bring up the SOAP servers screen.
  3. Press the -> button next to the SOAP server field. If a database name is shown in the list on the right hand side, it means there are clients connected to the SOAP server and that you have to restart the SOAP server to make sure the data shows correctly in the client. Your screen will look something like this:

  4. Press the Unload button. This will make sure that the static pages loaded by the SOAP server is updated the next time a client connects to it.

You can also achieve the refresh by restarting the web server (Apache or IIS)but that is not always feasible in a production environment.

It is a good idea to restart the SOAP server whenever you have made changes to your myTracker configuration with the server console. Items like users, user groups, stylesheets, queries etc etc are all loaded statically and need to be refreshed when you have made changes to the configuration.

See also:

FAQ: Why to use web service