Microsoft KB Archive/254353

= XFOR: GroupWise Architecture (Part 3): API Gateway =

Article ID: 254353

Article Last Modified on 10/12/2007

-

APPLIES TO


 * Microsoft Exchange 2000 Server Standard Edition
 * Microsoft Exchange Server 5.5 Standard Edition

-



This article was previously published under Q254353



SUMMARY
This is the third in a three-part series of Microsoft Knowledge Base articles that describe Novell GroupWise. This article describes the API Gateway in sufficient detail that Microsoft support professionals can understand basic concepts and perform basic troubleshooting. The GroupWise API Gateway is a required component for communicating with GroupWise when you are using the Microsoft Exchange Connector for Novell GroupWise.

235362 GroupWise Architecture (Part 1): Domain and Post Office Architecture

Introduction

GroupWise Domain Architecture

Domain Hierarchy

Directory Structure and Replication

Domain Directory Structure

GroupWise Post Office Architecture

Post Office Directory Structure

Message Store Architecture

254346 GroupWise Architecture (Part 2): Message Flow and Glossary

GroupWise Message Flow

Basic Message Flow Concepts

Delivery to a Local Recipient

Delivery to a Different Post Office, Same Domain

Delivery to a Post Office in a Different Domain

Troubleshooting GroupWise Message Flow

Glossary

254353 GroupWise Architecture (Part 3): API Gateway

Introduction to the GroupWise API Gateway

How It Works in Brief

API Gateway Directory Structure

Message Flow

Mail Message from GroupWise to Foreign System (Outbound)

Mail Message from Foreign System to GroupWise (Inbound)

Message Flow for Directory Operations

API Header File Format

Troubleshooting the API Gateway



MORE INFORMATION
The GroupWise API Gateway provides a way for third-party developers to create applications that communicate with the GroupWise message transfer service. The API Gateway is equivalent to the Lotus cc:Mail IMPORT/EXPORT utilities, or the Microsoft Mail FFAPI Gateway. It is roughly equivalent to the Exchange Developer Kit, which allows you to make connectors to Exchange Server; however, it is not so feature rich. The third-party gateway prepares an ASCII file that contains keywords that instruct the API Gateway to perform certain functions. These functions include mail, appointments, tasks, busy searches, and directory operations such as add, delete, modify, and list. The file is submitted to the API Gateway by means of an input directory, which the API Gateway is constantly polling. When the gateway sees the file, it parses it, and performs whatever operation is requested. Outbound messages function the same way in reverse: the API Gateway takes a native GroupWise message, formats it as an API message, and drops it in an output directory. The third-party gateway polls the output directory, and operates on any messages that are dropped there.

API Gateway Directory Structure
The following diagram describes the API Gateway directory structure. This directory structure represents only the most pertinent files and directories. \WPDOMAIN                       Root directory for the domain \WPGATE                      Root directory for all local gateways \API                      Root directory for the API Gateway Api.nlm               Gateway executable for NetWare NLM Gwcorr.dc             Dictionary file for correlation database Gwcorr.db             Correlation database to correlate message and statuses between systems \API_IN                API message input queue \API_OUT               API message output queue \ATT_IN                Attachments input queue \ATT_OUT               Attachments output queue \GWHOLD                Holding directory for delayed messages \GWPROD                Dead messages queue for inbound messages \WPCSIN                MTA input priority queues \<0 - 7>        \WPCSOUT                MTA output priority queues \APIxxx             API input priority queues for outbound messages \PROBLEM            Dead messages queue for outbound messages \NNN.PRC               Process working directory. NNN = process number (for example, OOO, OO1, OO2, and so on) \GWWORK             Gateway work directory MmddLOG.nnn      Gateway logs Proc             Gateway process lock file (gateway is started) Set              Gateway settings file (for some UI settings) Stat             Statistics file for gateway operations Acct             Accounting file \CMD                Command directory for correlating work between multiple instances of the gateway For additional information about the GroupWise API Gateway directory structure, see the Novell online documentation for the API Gateway Guide: Troubleshooting.

Message Flow
Being able to track how a message moves through the API Gateway is nearly always the only way to determine what went wrong when messages "disappear" without a trace. The following scenarios of outbound, inbound, and directory message flow should provide enough detail to troubleshoot the vast majority of cases where problems arise.

Mail Message from GroupWise to Foreign System (Outbound)
In this scenario, a normal priority message is sent from UserA on PostOffice1 to UserZ in a foreign messaging system named "Foreign." The Post Office Agent (POA) and the message transfer agent (MTA) are both configured for TCP/IP links.  UserA sends a high priority message to a foreign user either by selecting their name from an address book, or by entering a one-off address similar to the following:

API:UserZ/Foreign

 The GroupWise client transmits the message to the POA for PostOffice1. The POA performs local message delivery as described in the "Delivery to a Local Recipient" section, steps 2 through 4 located in Article Q254346 listed earlier. The POA writes a copy of the message to the local Postoff\Wpcsin\2 directory while the POA communicates with the MTA. This file remains in the Wpcsin\2 directory until the MTA has successfully received the message. The MTA receives the messages from the POA by means of TCP/IP, and writes the file directly to the Wpdomain\Wpgate\Api\Wpcsout\Api3d1\2 directory. If the MTA is unable to write the file to that directory, the message is held in the Wpdomain\Mslocal\Mshold\Api3d1\2 directory until a later polling cycle. When the MTA successfully delivers the message to the Wpdomain\Wpgate\Api\Wpcsout\Api3d1\2 directory, the MTA generates a "Transferred" status, which is sent back to the originating post office where the POA updates the original message record with a "Transferred" status for the message. "Transferred" merely means that the MTA was able to successfully pass the message to the API Gateway. It does not mean the API Gateway successfully delivered the message.</li> The API Gateway scans the Wpdomain\Wpgate\Api\Wpcsout\Api3d1\2 directory, picks up the file, and begins to process it. While the API Gateway is processing the file, it may cache the file very briefly in the Wpdomain\Wpgate\Api\000.prc\Gwwork directory.</li> As part of normal processing, the API Gateway writes the globally unique GroupWise message ID of this message in the gateway correlation table (Gwcorr.db) along with the associated API message ID, which it randomly generates. This message ID correlation serves as a method for the system to associate returning statuses or replies with the original message.</li> When the API Gateway is finished converting the outbound message from a GroupWise format to an API format, it copies any attachment files to the Wpdomain\Wpgate\Api\Att_out directory first, and then the API header file to the Wpdomain\Wpgate\Api\Api_out directory. If the header file was written to Api_out first, the associated attachment files might not be in the Att_out directory before the foreign gateway picks up and processes the API header file.</li> The foreign gateway polls the Api_out directory, sees the message, and begins to process it. When it has successfully processed the message, it deletes the attachments from the Att_out directory and the header file from the Api_out directory.</li> The foreign system may or may not generate a "Delivered" status. Either way, the API Gateway has successfully processed the message after it is written to the Api_out directory.</li></ol>

>

Mail Message from Foreign System to GroupWise (Inbound)
In the following example, UserZ in foreign system, "Foreign," sends a high priority message to UserA on PostOffice1. The MTA and POA are configured for TCP/IP links.
 * 1) UserZ sends a high priority message to UserA. However the foreign system does it, the foreign system ultimately delivers the message to the foreign gateway that communicates directly with the API Gateway.
 * 2) The foreign gateway converts the message from the foreign system's message format into an API message format. When finished, it first copies any associated attachments to the Wpdomain\Wpgate\Api\Att_in directory, and then copies the API header file to the Wpdomain\Wpgate\Api\Api_in directory. After the foreign system has successfully copied the files to the Att_in and Api_in directories, the foreign system is finished. The rest is up to GroupWise.
 * 3) The API Gateway polls the Api_in directory, picks up, and begins to process the API header file. The API header file may reference one or more attachments in the Att_in directory.
 * 4) The API Gateway converts the API message to a native GroupWise message, updates the gateway correlation database (Gwcorr.db), and drops the message in the Wpdomain\Wpgate\Api\Wpcsin\2 directory ("2" because this is a high priority message).
 * 5) The MTA polls the Wpdomain\Wpgate\Api\Wpcsin\2 directory, picks up the message, and makes a routing decision based on the recipient addresses. In this case, it transmits the message directly to the POA for PostOffice1.
 * 6) The POA for PostOffice1 performs local message delivery as described in the "Delivery to a Local Recipient" section, steps 2 through 5.
 * 7) The POA generates a "Delivered" status, which it transmits to the MTA.
 * 8) The MTA delivers the "Delivered" status to the Wpdomain\Wpgate\Api\Wpcsout\Api3d1\3 directory ("3" because this is a high priority status).
 * 9) The API Gateway polls the Wpdomain\Wpgate\Api\Wpcsout\Api3d1\3, picks up the status, and then checks "Outbound Status Level" setting in "Optional Gateway Settings" for the API Gateway. If the Outbound Status Level is set to "Delivered" or higher, the status is converted to an API message, and then delivered to the Api_out directory.
 * 10) The foreign gateway polls the Api_out directory, picks up the message, and then processes it accordingly.

Message Flow for Directory Operations
The API Gateway performs all directory operations directly without routing directory updates or requests to the MTA. So message flow is simple:
 * If the foreign gateway submits an API header file with the keyword -GET-DIRECTORY-, the API Gateway first checks the Directory Synchronization/Exchange setting in Optional Gateway Settings for the API Gateway. If Directory Synchronization/Exchange is set to "Synchronization" or "Both," the API Gateway fetches a full list of all users in the GroupWise system. If Directory Synchronization/Exchange is set to "None," the API Gateway ignores the request.
 * If the foreign gateway submits an API header file with the keywords DS-USER, DS-RESOURCE, or DS-GROUP, with the sub-keywords OPERATION=List, the API Gateway first checks the Directory Synchronization/Exchange setting in Optional Gateway Settings for the API Gateway. If Directory Synchronization/Exchange is set to "Synchronization" or "Both," the API Gateway fetches the requested filtered list of all users in the GroupWise system. If Directory Synchronization/Exchange is set to "None," the API Gateway ignores the request.
 * If the foreign gateway submits an API header file with the keywords DS-USER, DS-RESOURCE, or DS-GROUP, with the sub-keywords OPERATION=Add, OPERATION=Delete, OPERATION=Modify, or OPERATION=Rename, the API Gateway first checks the Directory Synchronization/Exchange setting in Optional Gateway Settings for the API Gateway. If Directory Synchronization/Exchange is set to "Exchange" or "Both," the API Gateway performs the requested operations on the GroupWise directory. If Directory Synchronization/Exchange is set to "None," the API Gateway ignores the request.

API Header File Format
API Header files must be of a very specific format, with a very specific set of keywords. Novell's documentation of this gateway is excellent, and you are encouraged to peruse the online documentation for the API Gateway at the following Novell Web sites:

Introduction to Keywords and API Files:

http://www.novell.com/groupwise/administration/gw55/us/api00005.html

Keyword Reference:

http://www.novell.com/groupwise/administration/gw55/us/api00006.html

Troubleshooting the API Gateway
If you understand that the API Gateway is a simple "data-in, data-out" gateway that operates against structured API text files, troubleshooting can be quite simple. <ol> Set logging on the API Gateway to "Verbose." The "Normal" logging setting yields too little information, and the "Diagnostic" logging setting yields too much, and is of little value. Log files are found, by default, in the Wpdomain\Wpgate\Api\000.prc\Gwwork directory.</li> Identify whether the problem is with the API Gateway, the GroupWise MTA, or the foreign gateway. You can easily determine this by seeing where messages end up. <ul> If message flow halts with a message in the Api_in directory, make sure that the API Gateway is running. The API Gateway processes all files that it finds in the Api_in directory. If the files are formatted properly, it either performs the requested directory operation, or converts the message to a native GroupWise format, and submits the message to the MTA in the Wpdomain\Wpgate\Api\Wpcsin\<n> directory. If the files are malformed, or the API Gateway can't read them, the API Gateway moves the files to the Wpdomain\Wpgate\Api\Gwprob directory.</li> If message flow halts with a message in the Api_out directory, make sure that the foreign gateway is running. If the message is in the Api_out directory, GroupWise has completed all processing as it should, and can properly be absolved of wrong-doing at this point.</li> If message flow halts with a message in the Wpdomain\Wpgate\Api\Wpcsin\<n> directory, make sure that the MTA is running. Also, make sure that the MTA is looking in the right location. Verify the UNC Path setting for the gateway on the Information tab of the API Gateway properties in NetWare Administrator. Also, verify that the MTA knows about the API Gateway and whatever it is connecting to by viewing link settings in the Link Configuration Utility (NetWare Administrator | Tools | GroupWise Utilities | Link Configuration Utility).</li> If messages just seem to "vanish", troubleshoot message flow by successively stopping and starting each delivery agent along the path. <ol style="list-style-type: lower-alpha;"> For example, to test Inbound message flow, stop the API Gateway, and send a message from the foreign system. Does the message arrive at the Api_in directory? If so, proceed to the next step. If not, the problem is in the foreign messaging system.</li> Stop the MTA, and then start the API Gateway. Does the message get moved to the Wpdomain\Wpgate\Api\Wpcsin\<n> folder? If so, proceed to the next step. If not, did the message end up in the Api\Gwprob directory? If so, the message was malformed or unreadable. Stop the API Gateway, resend the message, and examine the API header file. Also, consult the API Gateway logs, and examine the "bad" file in the Gwprob directory.</li> Stop the adjacent delivery agent. This is where troubleshooting message flow truly becomes a GroupWise problem. The possibilities and troubleshooting strategies at this point become very complex. Either solicit the assistance of Novell Support, or consult the Novell on-line documentation for further details.</li></ol> </li></ul> </li></ol>

For additional information, visit the following Novell Web sites:

Novell On-line Documentation: API Gateway Troubleshooting Guide:

http://www.novell.com/groupwise/administration/gw55/us/api00011.html

Novell On-line Documentation: API Gateway Error Messages:

http://www.novell.com/groupwise/administration/gw55/us/api0000a.html

Keywords: kbinfo KB254353

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.