GroupWise Admin API: Automating Administrative Tasks
Articles and Tips: article
Senior Software Engineer
Novell Collaborative Services
LINDA MATHESON
Technical Writer
Software Delivery Specialists, L.L.C.
01 Mar 1998
Introduction
The GroupWise 5.x Administrative Objects API was designed to reduce the time an administrator spends on daily tasks by providing an object-oriented approach to maintaining a GroupWise system. The Admin API supports OLE Automation, the industry standard for interfacing applications. You can write applications using any programming environment that supports OLE Automation, such as Visual Basic, Delphi, C++, and Java.
Because the Admin API uses objects and relationships that are already familiar to GroupWise administrators, the Admin API makes it easier to implement third-party applications and allows rapid application development. This can increase productivity for third-party developers and lower the total cost of ownership for GroupWise by automating repetitive tasks.
In this article, we will discuss some differences between the Admin API and the Object API, how the Admin API can reduce time spent on administrative tasks, and then show how to use the Admin API by building a sample program using part of the specification. The sample code is written in Visual Basic and only a few objects will be used in the sample program. The full Admin API specification is athttp://www.novell.com/products/groupwise/html/adm.html. The full GroupWise SDK is athttp://developer.novell.com/cgi-bin/devnet.
Two notable differences between the Admin API and the Object API are the way he Admin API handles information to update Novell Directory Services (NDS) and/or GroupWise, and the way the Admin API handles collections.
The Admin API Commit Model. When a property of any object changes, the Object API immediately writes the information to the database. For example, if an Object API program needs to change a set of properties on an object, each changed property is committed to the database individually. The Admin API uses a Commit model in writing object changes to NDS and GroupWise. A program can change the properties of an object as often as needed, but the changes aren't written to NDS or GroupWise until the program calls the Commit method. All the changed properties are then written to NDS or GroupWise simultaneously.
Admin API Collections. With just a few exceptions, the collections in the Admin API are all considered "large" collections and have an iterator object associated with them. This allows you to step through each object in the collection individually. The Admin API also supports the For Each construct in Visual Basic by providing enumerators for each collection as well.
An iterator has four methods:
Reset( ) sets the iterator's internal pointer back to the first object in the collection.
Next( ) returns the next object in the collection.
Skip( ) takes a long integer parameter that specifies the number of entries to skip.
Clone( ) creates a new independent instance of the iterator. The clone starts at the same position as the original iterator.
Using Admin API
The Admin API saves time by automating many routine tasks:
Distribution list membership searches. If an employee is not receiving e-mail sent to the corporate distribution lists, it is necessary to search the parent and all its child distribution lists to pinpoint the employee in the database. This exhaustive and time-consuming task can be eliminated with an Admin API program that searches the lists automatically.
Ensuring new User IDs are unique. Admin API has a built-in method to verify that an ID is unique prior to adding it to the system.
Maintaining the GroupWise Address Book. An application can allow a user to make changes to the Address Book by filling out a dialog box. A program that integrates with the GroupWise client using the C3PO spec, the Object API and the Admin API, updates GroupWise and NDS automatically. The information is sent to an MIS mailbox with a C3PO looking for those messages. The C3PO opens the new messages, uses the Object API to read the updated data, and uses the Admin API to write the data into the Address Book automatically.
Importing a database and adding users to a GroupWise system. The following sample program will illustrate this.
Like the Object API, the binaries for the Admin API are installed when the GroupWise Win32 client is installed. Applications using the Admin API must have Novell 32-bit NetWare client loaded. If a 32-bit client isn't available, the application appears to register but will not operate properly.
The current version of the Admin API cannot create systems, domains, or post offices. In order to create these objects, the GroupWise snap-in must be run with NetWare Administrator. Once the systems, domains, and post offices have been added, you can use the Admin API to perform tasks such as adding users, resources, and distribution lists. The first step in using the Admin API is to tell OLE to load the Admin API by calling CreateObject.
Set objAdminSystem = CreateObject ("NovellGroupWareAdmin")
This loads the Admin API and returns an instance of a System object. The System object needs to be assigned to a variable of type object, or variant. Next, connect to a GroupWise system by using the Connect( ) method on the system object that was returned by CreateObject.
objAdminSystem.Connect (txtPath)
The Connect( ) method takes one parameter, which is a string containing the full path to the Domain database you wish to connect to. Connect( ) is only successful if there is a domain database at the path specified, and if the user currently logged into the NetWare 32-bit client has the rights to administer the GroupWise system and associated NDS tree.
Alternatively, you can connect to a system by calling ConnectByDN( ), which allows you to specify a system by distinguished name. This method has an optional parameter allowing you to specify the NDS tree containing the distinguished name. This method lets you connect to a system on a storage device that may not be mapped to a drive letter.
Sample Illustration. Our sample program, written in VB, will focus on adding users to a GroupWise Post Office and to NDS using the following objects: System, Domains, Domain, PostOffices, PostOffice Users, User.
After calling Connect( ), there are several properties and methods available on the System object. We use just a few of these in our application. First, we want to display the name of the system we have connected to, as well as a description of the system and the name of the last person who modified it. We are going to obtain this information from the System object and set it in frmMain. We also want to ensure that users are prompted to authenticate to any unauthenticated NDS resources accessed in our program. The code to get these properties is in Sub Main( ) of our VB project:
'Read and display the system name
txtSysName.Caption = objAdminSystem.Name
'Read and display the system description
txtSysDesc.Caption = objAdminSystem.Description
'Read and display who last modified the system
txtLastModifiedBy.Caption = objAdminSystem.LastModifiedBy
'Set the NWLogin property
objAdminSystem.NWLogin = TRUE
Navigating the Admin API. Navigating down to a specific post office and adding users can be done in three ways. The first method gets the Users property from the System object. This will be a collection of all the users in all the domains in the system. You can then add users to any Post Office, after you fill in the optional parameters for PostOffice and Domain.
The second method gets the PostOffice property from the System object. This will be a collection of all the PostOffice objects associated with the System object. From here, you can select the PostOffice object you want to add users to, get its Users property, and add users. When adding users in this method you will need to fill in the optional parameters for Domain.
The third method gets the Domains property from the System object. This will be a collection of all the Domain objects in the system. From here, you can select the Domain object you want to work with, obtain its PostOffices property, find the PostOffice object you want to work with, get its Users property and start adding users. When using method, you don't need to fill in the Domain or PostOffice parameters.
The Admin API is designed to allow a program to add users to any post office from any Users collection. This means that given any Users collection obtained anywhere in the system, you can add users to any post office in the system provided you know the domain and post office you wish to use. In Sub Main( ) of our Visual Basic project, we enumerate the domains in the system and populate a combo box called cbDomains in frmMain.
'Declare Domains and Domain objects
Dim objDomains as Object
Dim objDomain as Object
'Get the domains collection from the system object
Set objDomains = objAdminSystem.Domains
'Use VB's For Each construct to enumerate the domains and add each one to
'the cbDomains combo box
For Each objDomain in objDomains
fMainform.cbDomains.AddItem (objDomain.Name)
Next
If your GroupWise system has only one domain, or if you want to use the default, you can use ConnectedDomain to obtain the domain object. After cbDomains has been populated, use the ConnectedDomain property to get a Domain object for the currently connected domain. With this object, we can set the default selection in cbDomains.
'Get the ConnectedDomain
Set objDomain = objAdminSystem.ConnectedDomain
'Set the current domain in cbDomains
fMainForm.cbDomains.Text = objDomain.Name
We can now populate a combo box with Post Office names (cbPOs) from the PostOffices collection in objDomain.
'Declare POs and PO objects
Dim objPOs as Object
Dim objPO as Object
'Get the Post Offices collection
Set objPOs = objDomain.PostOffices
'Enumerate the Post Offices on objPOs and populate cbPOs.
For Each objPO in objPOs
fMainForm.cbPOs.AddItem (objPO.Name)
Next
After this code has executed in Main( ), fMainForm is displayed and the user can select a new domain to work with by clicking on a domain name in cbDomains. cbDomains_Click ( ) contains code to determine which domain was selected and re-populate the Post Offices combo box. The user can also select a post office by clicking on a Post Office Name in cbPOs. The code to handle this is in cbPOs_Click ( ) in our project. After determining which Post Office was selected, cbPOs_Click( ) obtains the Users property and populates a list box with the name of each user.
Private Sub cbPOs_Click()
Dim objUsers As Object
Dim objUser As Object
Dim objPO As Object
For Each objPO In objPostOffices
If cbPOs.Text = objPO.Name Then
Set objCurPO = objPO
End If
Next
Set objUsers = objCurPO.Users
For Each objUser In objUsers
UserList.AddItem (objUser.Name)
Next
End Sub
Once we select the desired post office, we can add users to the Users collection. The code to read the database is outside the scope of this article. The code to add an individual user from information entered into a dialog box can be easily extended to be called as the program iterates over the list of records read from the database.
Adding a New User. The Users object has four different methods to add a User to a Users collection. Two of these are overloaded versions of Add, and two are overloaded versions of AddExistingUser. Users.Add adds a user to NDS and to GroupWise. Password will be for both NDS and GroupWise. Parameters in [ ] are optional. Notice that the first Users.Add takes strings for the PO and Domain parameters, while the second takes a PostOffice object and a Domain object, instead of strings.
User.Add( string UserName,
string SurName,
string DN,
[string Password,]
[string PO,] If Users is obtained from Domain, PO is required.
[string Dom,] If Users is obtained from system, PO and Dom are required.
[string MailboxID] )
User.Add( string UserName,
string SurName,
string DN,
[string Password,]
[PostOffice PO,] If Users is obtained from Domain, PO is required.
[Domain Dom,] If Users is obtained from system, PO and Dom are required.
[string MailboxID] )
Users.AddExistingUser adds an existing NDS user to GroupWise. The password will be for GroupWise only. Again, the first AddExistingUser accepts strings for the PO and Domain parameter, while the second accepts objects for these parameters.
Users.AddExistingUser (string UserName,
string DN,
[string Password],
[string PO,] If Users is obtained from Domain, PO is required.
[string Dom,] If Users is obtained from system, PO and Dom are required.
[string MailboxID])
Users.AddExistingUser (string UserName,
string DN,
[string Password],
[PostOffice PO,] If Users is obtained from Domain, PO is required.
[Domain Dom,] If Users is obtained from system, PO and Dom are required.
[string MailboxID])
In each case of the Users.Add and Users.AddExistingUser, a User object representing the new user is returned. Now we can add a user to the post office. Our enterprise has a policy that no two users can have the same UserName anywhere in the enterprise, so we will have to check the entered UserName for uniqueness with System.IsUserNameUnique( ). We will code our example as if we are adding users that don't already exist in NDS. That means we will use Users.Add instead of Users.AddExistingUser. Also, since we obtained our Users collection via a Domain and PostOffice object, we can omit the parameters for PO and Dom.
We will omit MailboxID in our example. In this case the Admin API will assign a mailbox ID for us. Since we are using OLE automation, we can simply skip passing this parameter completely. The automation controller code in VB will allocate and pass an empty parameter for us at run time.
While Users.Add accepts enough data to create a new user, most MIS departments require more data to fill out a user's Address Book entry. In our code we set these additional properties on the User object after creating it with Users.Add. Form frmAddUser has fields to accept the information we'll need to create a user and set the additional properties. Finally, we need to update the user's properties in NDS by calling User.Commit( ).
If User.Commit( ) isn't called, the changes we make to the User object will be lost when the object goes out of scope and is freed by VB. The code that handles the add is in AddBtn_Click ( ) for frmAddUser. We have placed objAdminSystem, objDomain, objPostOffice and objUsers in global space in our project so we can access them from frmAddUser.
Private Sub AddBtn_Click ()
Dim objUser as Object
Dim boolIsUnique as Boolean
'Check for a unique user name
boolIsUnique = objAdminSystem.IsUserNameUnique ()
'If the user name is unique, add the new user
if boolIsUnique = TRUE then
Set objUser = Users.Add (txtUserName,
txtSurName,
txtDN,
txtPWord)
'Set additional properties
objUser.GivenName = txtGiven
objUser.Title = txtTitle
objUser.Department = txtDept
objUser.PhoneNumber = txtPhone
objUser.FaxNumber = txtFAX
Commit the changes
objUser.Commit
End if
End Sub
Conclusion
The Admin API makes it simpler to eliminate many daily GroupWise administrative tasks. Modeling a problem and programming a solution is easier because the Admin API uses objects and relationships familiar to GroupWise administrators. It also supports OLE automation, enabling many programming environments. By using large collections and the Commit ( ) model, the Admin API will also enhance your programing performance.
* 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.