Novell is now a part of Micro Focus

Cluster Enabling The GroupWise API Gateway

Novell Cool Solutions: Feature
By Stuart Park

Digg This - Slashdot This

Posted: 21 Jul 2005


Some time ago we embarked on a VoIP (Voice over IP) project that ties into our email system, being GroupWise 6, at the software end we chose Topcall as our preferred solution. Part of this project involved setting up the GroupWise API Gateway (GWAPI) as the link from Topcall to GroupWise and back.

We run our GroupWise environment in a NetWare cluster and were therefore looking to cluster enable the GWAPI to gain the benefits that Cluster Services provide. A search through the Novell TIDs produced this hit:

Being told it cannot be done means we will try and make it happen. This document is a result of research and testing into making this possible, it also includes settings that are needed for a specific Topcall install.


First set up a clustered GroupWise domain as the GWAPI ties in with the domain directory structure. This document doesn't cover the setting up of a clustered domain; see Novell's documentation for this.

For this document the following names and directory paths have been used:

Vitrual server CLQANDOMAIN
Domain name QAGWDOMAIN

Files, Utilities & Links

GW41API2 - GWAPI install


GW55API.PDF - GWAPI documentation

GWAPI online documentation

Stuffkey utility

GWAPI NLM Installation

Make sure the volume is mounted and the cluster resource is online.

Copy the GWAPI install files to the clustered volume:


Run the PINSTALL.NLM from the console:


Once loaded the default screen will look as follows:

Complete the screen with the necessary directory paths. The Shared NLM and Load Script directories have been made the same to save on NetWare search paths.

If errors occur recheck the directory paths are correct on the install screen and by browsing the file system. Once successful check the contents of:


This should now contain some files and directories that were not present before.

Next the GWAPI will need to be set up and configured. This in theory should be performed through NWAdmin however I'd rather configure what I can with ConsoleOne then finish with NWAdmin what ConsoleOne doesn't allow.


Once installed replace the following files with the files included in the patch:


ConsoleOne Configuration

Load ConsoleOne (with GroupWise snapins) and connect to the Domain where the GWAPI will be installed. Browse to the Domain object through the DS view (not the GroupWise view).

Create GWAPI

Right-click the Domain object, select, New > Object?
Select, GroupWise Gateway and hit OK.

Select Gateway, click OK and complete the details required:

  • Choose a name for the Gateway
  • The Gateway Home Directory should be what was set during the install, the default is API
  • Select, API as Gateway Type
  • Make sure 4.x is selected for the version, regardless of the main GroupWise system, for example, this is being installed into a GroupWise 6 system
  • Select, Define additional properties

Identification Settings

The Identification options should reflect some of the options chosen in the previous set up screen. Description, Alias Type, etc maybe added if wished.

Gateway Time Settings

The Gateway Time Settings have been left as defaults, down to user preferences.

Log Settings

It is highly recommended to set up logging. Given the cluster volume contains ample space I would recommend saving logs into the API directory (a LOGS directory will have to be created first). Also the Log File Age and Log Disk Space may need to be increased to capture a greater period of logs.

Optional Gateway Settings

Within the Optional Gateway Settings make sure the following are set. These settings are specific to the Topcall interface, set as necessary.

Directory Sync/Exchange None
Convert Status to Message No
Outbound Status Level Full
Enable Recovery Yes
Correlation Enabled Yes
Correlation Age 31

Other Settings

Other properties within the GWAPI that can be set, but are not required are:

  • Gateway Administrators
  • Gateway Aliases
  • SSL

Select OK the save the changes made.

NWAdmin Configuration

There are two options screen that do not feature within ConsoleOne, for these NWAdmin will need to be used. Launch NWAdmin (with GroupWise snapins) and browse to the GWAPI object from the DS view.

Required Parameters Settings

Within the details of the GWAPI select Required Parameters. In the Root Directory boxes enter the following path (note that a UNC path will not work, only a path from the volume):


Set the Addressing Format to Component (Not GroupWise), this is another specific Topcall setting.

Output Conversions Settings

Under Output Conversions confirm the Output Character Set is ASCII Text, this should be set by default.

Select OK to confirm these settings. The GWAPI configuration should now be complete.

Stuffkey Configuration

One problem with the GWAPI is the fact it prompts the user for conformation when trying to unload. To introduce this into a cluster environment the process will have to be fully automated. Novell's Stuffkey utility can be used to automatically force characters onto the System Console to answer prompts.

Copy the STUFFKEY.NLM to the cluster volume:


Create a file for the Stuffkey utility to use, this will run the necessary commands and respond to the prompts that the GWAPI will produce. The file will looks as follows:

# Auto unload GWAPI
<screen=System Console>
unload address space = qagwdom ngwapi<cr>
# Wait for 2 seconds
<2000 pause>
unload address space = qagwdom ngwlib<cr>
# Wait for 1 seconds
<1000 pause>

Save this file into the following location:


Cluster Script Configuration

Load Script

The following is the original cluster script to load the MTA, the lines in blue are added to load the GWAPI. Note the MTA and GWAPI loads into the same address space.

nss /poolactivate=QANDOMAIN
mount DOMAIN VOLID=252
add secondary ipaddress

search add domain:\system
search add domain:\qaapi
load address space = qagwdom domain:\system\gwmta @qagwdoma.mta
load address space = qagwdom domain:\qagwdom\wpgate\api\ngwapi @ngwapi.prm
protection restart qagwdom

Unload Script

domain:\stuffkey\stuffkey domain:\stuffkey\uldgwapi.txt
delay 6

unload address space = qagwdom
del secondary ipaddress
nss /pooldeactivate=QANDOMAIN /overridetype=question

Complete Configuration

Offline and online the cluster resource, it should load as follows:

The System Console showing the MTA and GWAPI loading without errors:

Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions.

© Copyright Micro Focus or one of its affiliates