Web service / SOAP server

Background

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:

[Settings]

MailClientSettings=SMTP:SoapServer@yourdomain.com:smtp.yoursmtp.com:25

The components of the string are as follows:

MailClientSettings - ini file name of the setting.
SMTP - shows that the web service will use SMTP for email transport.
SoapServer@yourdomain.com - this is the email address that will identify the web service as the sender of the email. On your mail server you can create this account and forward messages to the myTracker administrator. Then users can reply to messages and someone can pick them up and deal with the responses.
smtp.yoursmtp.com - the address of the smtp server you will use. This can also be an IP address (probably on your local sub-net).
25 - this is the SMTP port used on the designated server. Ususally this is port 25.

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

</Location>

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:
ClearModuleList

2.2 Microsoft IIS 5.0

Add a new virtual directory such as MyTracker.
Set the Local path to [InstallPath]/SOAPService.
Set the execute permission to Scripts and Executables.
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:

Start the server console.
Select SOAP server from the server menu. This brings up the SOAP servers dialog:
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.
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:

ServerName:=FB;;yourdomain.com:c:\BugsDb;UserName;CEL7Bem7Sno==

The components of the string are as follows:

ServerName - is the name myTracker uses for the server.
yourdomain.com - is the URL of the the server where the web service is running. Alternatively you can use the IP address of the web server machine(192.168.12.12).If the web service is on the same machine as the web server you should be able to use 127.0.0.1.
BugsDb - this points to the physical Firebird database. In this example the database was set-up as an alias in Firebird after it was created by the server console. You can also use the path to the database: C:\Data\BugsDb.fdb where C: refers to a drive on the machine where the web service is running.
UserName - this is a valid Firebird user name.
CEL7Bem7Sno== - this myTracker's encoding of the Firebird user's password. The web service will decode this to the actual password when it connects to the Firebird server. The only way to get this, is to let one of the myTracker modules create it. That is why it is easiest to create your connection string with Server console and copy the setting across.

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:

Start up the client console.
Select register server from the server menu.
For connecting to an Apache web server enter the following Server string:
ClientServerName=SOAP;;http://server/myTracker/ServerName;;
For connecting to an IIS web server enter the following Server string:
ClientServerName=SOAP;;http://server/mytrackerISAPI.dll/ServerName;;
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.

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:

ClientServerName - is the name the myTracker client console will use for the web service. This is the name that will be displayed when you select Connect to server from the server menu.
SOAP - this tells the client console that the connection is not direct with a database but with a SOAP server. The Client console will then internally use the appropriate logic to retrieve the relevant data.
http://server - is the URL of the the web server where the web service is running.
myTracker/ and mytrackerISAPI.dll/ - this lets the web server (Apache or IIS) know that you are connecting to a SOAP web service under their control. The web server will in turn pass the relevant parameters to the web service, who will then do the actual database querying and return the values.
ServerName - this is the myTracker server name as register on the web service. It is important to have the same name here as in the server.ini file in the SOAPservice directory of the web service. If not then the connection cannot be made.

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:

Start up the server console.
Select SOAP server from the server menu. This will bring up the SOAP servers screen.
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:

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.