GWPABASR.EXE (GroupWise Personal Address Book Advanced Search and Replace)

Rob Rawson, Novell Consulting

Command Line Switches: /AUTO = run unattended using default parameters

The program relies on a text file structured like a Windows INI file, called an SRI file (for Search Replace Instructions). The default location for the file is in the Windows user directory, usually C:\WINDOWS or C:\WINNT.

A sample SRI file:

;Parsing rules for GroupWise Personal Address Book Search and Replace

[FRB1]

;first param is how to identify the format. One of:

; STARTS=

; ENDS=

; CONTAINS=

;

; NOTE: ALL LITERALS IN VARIABLE DEFINITIONS ARE ENCLOSED IN LEFT SINGLE QUOTES

ENDS=/"@b1gw.nongw

;next section describes variables, any name except reserved words are OK, no repeats

*INITIAL=.`/I=` to `/`

*INIT2= `/I=` to `/`.

GIVEN=`/G=` to `/`

SURNAME=`/S=` to `/`

DISTRICT=`/O=` to `/`

;next section describes translated value

EMAILADDR=internet:%GIVEN%%INITIAL%.%SURNAME%@%DISTRICT%.frb.org

DISPLAYNAME=%GIVEN%%INIT2% %SURNAME%

[FRB2]

ENDS=us"@b1gw.nongw

;next section describes variables, any name except reserved words are OK, no repeats

*INITIAL=.`/I=` to `/`

*INIT2= `/I=` to `/`.

GIVEN=`/G=` to `/`

SURNAME=`/S=` to `/`

DISTRICT=`/O=` to `/`

;next section describes translated value

EMAILADDR=internet:%GIVEN%%INITIAL%.%SURNAME%@%DISTRICT%.frb.org

DISPLAYNAME=%GIVEN%%INIT2% %SURNAME%

[SMTP]

ENDS=@internet"@b1gw.nongw

ADDR=`"` to `@internet"`

NAME=`"` to `@`

HOST=`@` to `@internet"`

EMAILADDR=internet:%ADDR%

DISPLAYNAME=%NAME% at %HOST%

Each section ([FRB1], [FRB2], [SMTP]) is just an arbitrary name used to describe the section. You can have as many sections as you need, limited only by memory. There are five reserved words: STARTS, ENDS, CONTAINS, and EMAILADDRESS and DISPLAYNAME.

Each section must have either a STARTS, ENDS or CONTAINS. STARTS means that this pattern is recognized by an eMail address that STARTS with that pattern, ENDS means it ENDS with that pattern, and CONTAINS means it CONTAINS that pattern somewhere in the middle. Each section should have one and only one of these three.

Any entries found which are not one of the five reserved keywords are considered search variables. They indicate what to look for and are formatted in one of these forms:

NAME=`xx` to `yy` // where xx=what characters to start at and yy=what characters to end at

NAME=START to `yy`

NAME=`xx` to END

VERY IMPORTANT NOTE: the character strings are surrounded by a LEFT SINGLE QUOTE. That is the only delimiter allowed here for literals.

The characters specified will not be included in the variable, only the contents between them. If you want the characters to appear in the name you can re-include them in the output macro (EMAILADDRESS and/or DISPLAYNAME).

OPTIONAL VARIABLES: Any variable name in the *.SRI file which starts with an asterisk is optional, meaning if it is not found, instead of considering it a parsing error, nothing is substituted. For example:

*INITIAL = `/I` to `/`

is an optional variable.

PREFIX/SUFFIX on variable definitions: Any characters before the first left single quote are prefixed to the variable value, any characters after the last left single quote are suffixed to the variable value. For example:

*INITIAL = .`/I` to `/`

if you feed in this the address:

b1gw.nongw."/I=D/G=Keith/S=Woodard/O=BOS/P=frb/A=telemail/C=us"

Your output in the macro for INITIAL will be: .D

Each section also must have an EMAILADDRESS macro, which is the pattern for the new eMail address. Use the variable names above as you would in a DOS batch file to substitute into the string. You may also have a DISPLAYNAME= macro. You can specify the format of the output display name based on a template just like the eMail address. However this functionality is only invoked in the single case that the existing display name of the group member would make for an illegal GroupWise display name for a new user.

If you run the application in interactive mode (by default, no command line parameters) you will see three buttons. One will bring up a dialog to allow you to change the SRI file in case you have multiple ones. The Go! button will start the modifications to the address book, however before clicking Go! you must select which personal address books you wish to modify. You may select more than one.

Once the Go! button is pressed, the application will begin scanning through the address book and make changes. It is possible to interrupt the program by pressing the exit button, however you will be partially changed. If you start again you will start from the begining, however that should work fine, since you'll ignore any entries that have already been changed.

There is a check box provided to allow you to approve each change one by one.

In /AUTO mode, the program will operate completely hands-off. It will select all personal address books and use the default file name of GWPABASR.SRI in the Windows user directory (usually C:\WINDOWS or C:\WINNT). You will not be able to stop the program until it completes, and it will exit automatically when completed.

Personal Groups migrated from GroupWise 4

GroupWise 4 did not support personal user objects in the address book, although it did provide the ability to create personal mailing lists. Many users created personal lists of a single item to work around this shortcoming. This presented somewhat of a problem in the design of this tool.

The algorithm to deal with this situation is as follows:

1) Users are processed first before any groups

2) Check groups member lists, if a member of the group is not in the address book, it adds it as a user. If the name of the user to be created would be illegal under GroupWise 5, the DISPLAYNAME macro is used to format the name. This prevents eMail addresses from being displayed as the user name in the address book.

3) If there is only one member in the group, the group name is deleted (the new user object will have the same name as the group did previously)

4) If there are more than one member in the group, the group is modified to delete the GroupWise 4 address book entry and instead point to the newly created address book entry (from step 2).

It should be noted that when groups are migrated from GroupWise 4 to GroupWise 5, the format of the name of users within the group is still in GroupWise 4 format. This may cause you to need to add additional entries in the SRI file in order to recognize those groups.

Technical Details:

This 32 bit program was developed in Delphi 3, using the publically available GroupWise Object API. The GroupWise portion of the program represented about 10% of the work, the lion's share of effort went into the parsing engine. It has not been tested with every permutation of options that could be put in the SRI file, so there may be holes where the code does not currently work properly. Contact consulting@novell.com to provide feedback on this utility.