Building GroupWise 5 Gateways Using the API
Articles and Tips: article
Software Engineer
Developer Support
01 Feb 1997
Outlines how to build GroupWise 5 gateways on a common code to address functionality that is similar to all foreign mail systems.
Introduction
The GroupWise architecture includes a rich set of external connectivity capabilities. At the core is common code to address functionality that is similar to all foreign mail systems.
These available gateways are built on that code and can be used either with GroupWise 5 or GroupWise 4.1 to connect to foreign messaging system like SMTP/MIME, ASYNC, cc:Mail, Lotus Notes, MHS, MS Mail,OV/VM, SNADS, and X.400.
In addition to that there is a flat file API access, to be able to send information from GroupWise to another system or application, and/or receive information from another source and hand it over to the GroupWise system.
The GroupWise API uses a keyword-based text file format for communication with non-Novell messaging systems and other applications, such as database programs or word processors.
For example an assembly line processing system can create a text file similar to the one shown below, indicating an alarm situation. If the text is placed in the appropriate directory, and the Message Transfer Agent (MTA) and the API Gateway are running, the message will appear in the user's mailbox and can be opened.
If one or both processes are not up and running, the message will be queued and delivered once the service is running again.
WPC-API=1.2; MSG-TYPE=Mail; TO=ACME.Production.RickLi; TO-TEXT=Maintanance; FROM=ACME.Production.Process; FROM-TEXT=Assembly Machine # 14; MSG-Priority= High; SUBJECT=ALARM - URGENT -; MSG-FILE=alarm_14.txt; -END-
A user can also send a message from GroupWise through the API Gateway as shown below. This generates a text file that the GroupWise API places in the directory structure used for outgoing messages.
A third-party application that polls this directory structure can then parse the file, convert it, and route it elsewhere.
WPC-API= 1.2; Header-CHAR= T50; Msg-Type= NOTE; From-Text= The Boss; From=ACME.HQ.amrich; To= GETWAYS.API(AX); Msg-ID= 00001984.8888.8888.888; To-Text= Agent X; Subject= We have to be smarter; Date-Sent= 12/8/95 10:25; Security= Top Secret; Send-Options= Notify-User; Status-Request= Delivered; Begin-Time= 12/8/95 12:00; End-Time= 12/24/95 8:00; Msg-Priority= High; -END-
See Keyword Reference for more information on Keywords
Imagine a situation where a user sends a GroupWise message to a database requesting certain data. An application would read the text file from the outgoing directory of the API Gateway, translate it to an SQL query, and send it to the database engine.
After retrieving the information, the application would build up a text file using valid key and addressing elements for your system, and place the requested data in the message body. The API Gateway picks up the file, converts it to a GroupWise message, and sends it to the user's mailbox.
System Requirements
The API Gateway supports DOS, OS/2, and NLM Platforms.
The API Gateway for DOS will operate on a dedicated system or message server station. The gateway software requires an 80286 based PC with a 20MB hard drive and 640 KB RAM with DOS 3.3 or higher. System performance improves when using an 80386 based PC with at least 2MB of RAM.
When gateway and messaging software operate on separate machines, the message server acts as a dedicated server. While the message server transfers the files to a domain, the gateway system actually sends the files.
When used as a combined gateway and message server, a system executes server requests, processes a gateway cycle, and returns to the server process. The system only interrupts the server process when the message header file contains gateway header information. After processing the gateway request, the system returns to its role as message server.
The GroupWise API Gateway for OS/2 supports multitasking or simultaneous multiple threads. Recommended system requirements when using API for OS/2 include an 80386 based PC with 120MB hard drive and 16MB of memory using DOS 5.0 (or higher) and OS/2 2.1 (or higher).
The GroupWise API Gateway for NLM requires:
80386 DX Processor or higher with 4MB of RAM and 40MB available hard disk space
a GroupWise 5.0 MTA (or GW4.1 Message Server)
Novell GroupWise Admin 4.1 or higher (NWAdmin for GroupWise 5)
Novell NetWare CLIB.NLM version 3.12 or higher
Novell NetWare 3.11 or higher
Security
The purpose of any API is to open a system and make it accessible. This makes security an issue when you run your GroupWise system and the GroupWise API Gateway. However, with a few precautions, you can secure your GroupWise system.
All files passing into and out of GroupWise through the GroupWise API Gateway must use the specific directory structure explained in "Directory Structure," below. We suggest that you limit access to these directories, making the security of your system dependent on the operating system where the API directories and files reside.
Ideally, applications that insert messages into the API input directories would have only write privileges to those directories. Similarly, the API output directories would be protected so that the GroupWise API Gateway would have write privileges, the third party gateway or application would have read/write privileges, and all others would be excluded from access to the directory.
Also, the keyword MSG TYPE=Admin allows the GroupWise API Gateway to perform functions, such as adding and deleting users, that normally could be done only from within Admin. You may want to set up the gateway so that directory service requests use a directory structure separate from all other types of messages. Doing so lets you put stricter limitations on directory service messages than on regular messages.
Keyword Reference
Keyword Ordering Requirements and Delimiters
A header file must begin with the keyword WPC API. WPC API must be the first seven characters or the gateway will not process the file. The default character set encoding (T.50) is assumed, unless a HEADER CHARkeyword field is encountered.
If used, HEADER CHAR must be on the second line, immediately after the WPC API keyword. The END keyword indicates the end of the API header information. The GroupWise API will not process any characters occurring after this keyword. Keywords between HEADER CHAR and END-have no ordering requirements.
You can place comments in the header file by inserting a pound sign (#) at the start of the line. For a multiple line comment, each line must begin with a pound sign.
If a keyword or sub keyword has variable data, an equal sign (=) must separate the keyword itself from the data. A line feed or carriage return/line feed combination delimits a line, and a semicolon delimits the data portion of all keyword fields. A second semicolon terminates a composite keyword.
If a semicolon must appear as part of the data, it should either be contained in double quotes ("") or immediately preceded by a backslash (\). If you need to include an unpaired double quote as part of your data (as in 36" in a yard), you must put a backslash in front of the unpaired quote.
Although it is suggested that lines in the header file not exceed 74 characters per line (including any keyword and delimiters), this is simply for ease of display and not a requirement of the API Gateway parser.
Keyword Groupings
The following table lists API keywords by functional groupings.
A more detailed Keyword Reference can be found on the complete API Gateway Documentation, which DeveloperNet members can find on the the SDK CD-ROM.
|
Keyword Type
|
Keywords
|
|
Header and miscellaneous keywords. These keywords mark the start and end of the file and definethe character set of the file. The # begins a comment line. |
WPC APIHEADER CHAR MSG TYPE # END |
|
Message body keywords specify the filename, format, and character encoding for the message body file. |
MSG ACTIONMSG CHARMSG FILE |
|
DirectoryServices keywords access functions of the GroupWise messaging system's directory services.These keywords are active only if the header filespecifies MSG TYPE=Admin. |
DS EXTERNAL POST OFFICEDS GROUPDS RESOURCEDS USER GET DIRECTORY |
|
Source keywords give details about the originator of the message. |
DATE SENTFROM FROM TEXT |
|
Destinationkeywords specify the recipients of a message. |
ALL TOALL TO CCFOLDER NAMETOTO BCTO CCTO CC TEXTTO TEXT |
|
Messageattribute keywords specify the attributes that control how a message is transported,delivered, and presented to the recipient. |
BEGIN TIMEDISTRIBUTE DATEEND TIMEEXPIRE AFTERMSG PRIORITYRESPOND BYSECURITYSUBJECT |
|
Attachment keywords specify and list the attributes of files that should be included as attachmentsto a message.Multiple attachment files can follow the ATTACH FILE keyword. |
ATTACH FILE |
|
Status keywords determine what status is delivered to the message's recipient or returned to the sender. |
ORIG MSG IDSTATUS REPORTMSG IDSTATUS REQUESTSET STATUSSEND OPTIONS |
|
Phone keywords give additional information specific to phone messages.These keywords are onlyvalid if MSG TYPE=PHONE. |
CALL ACTIONCALLER COMPANYCALLER NAMECALLER PHONE |
|
Appointmentkeywords give additional information specific to an appointment.They are only valid if MSG TYPE=APPT. |
LOCATION |
|
Task keywords give additional information exclusive to a task message.These keywords are onlyvalid if MSG TYPE=TASK |
TASK CATEGORYTASK PRIORITY |
|
Busy Searchkeywords are only valid if MSG TYPE=SEARCH |
BUSY FOR BUSY REPORT |
Directory Structure
When a GroupWise user sends a message to an API Gateway, GroupWise places the file in a directory where the MTA reads the header file and places the file in a directory for the API Gateway to process.
The gateway polls the directory, converts the file, and separates the header from the message file and the attachments. The header is placed in API_OUT directory and the message and attachments are placed in the ATT_OUT directory.
To send messages to an API Gateway the client should use the following addressing syntax:
domain.gateway_name.user
If an external system or application wants to create a message to be delivered to a Groupwise user it must create a formated file which contains valid keywords to identify the Groupwise delivery type and information.
This file has to be created in the API_IN directory, and addtional files containing the message body text ot attachement files have to be placed in the ATT_INdirectory.
The API Gateway routinely examines files contained in these directories, reads the header file, and transmits the information to the specified directory. The Message Transfer Agent then examines the header information and updates the user information in the databases.
The default API directory structure is shown below. Italicized names, such as HEADQ, represent user definable names.
HEADQ
WPGATE
API_NML
API_IN
API_OUT
ATT_IN
ATT_OUT
GWHOLD
GWPROB
Your directory structure might be different if you specify a Message Files Root when configuring the gateway. In that case, your directory structure might look like the following:
HEADQ
WPGATE . . . / . . . /YourName
API_NLM API_IN
GWHOLD API_OUT
ATT_IN
ATT_OUT
GWPROB
For more information on the API Gateway see the GroupWise 5 API Gateway Developer's Reference documentation, available on the DeveloperNet SDK CD-ROM.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.