XFOR: GroupWise Architecture (Part 3): API Gateway

Table of Contents

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

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

254353� GroupWise Architecture (Part 3): API Gateway

\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
				

1. 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
2. The GroupWise client transmits the message to the POA for PostOffice1.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. 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.
11. 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.

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.

• 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.

1. 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.
2. 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.
   • 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.
   • 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.
   • 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).
   • If messages just seem to "vanish", troubleshoot message flow by successively stopping and starting each delivery agent along the path.
     1. 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.
     2. 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.
     3. 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.