GroupWise 2014: Using The REST API To Convert Mailboxes

Once Upon A Time … a well-known GroupWise guy discovered and explained to us how to convert GroupWise objects – his name: Tay Kratzer. The original title of his paper was Converting a GroupWise User Mailbox To A GroupWise Resource Mailbox. Tay Kratzer worked for Novell for several years; was author of some GroupWise books and later developed the backup software GWAVA Reload.

Tay used ConsoleOne for processing the transformation, but in a tricky and specific way. This was a long time ago and GroupWise 2014 no longer uses ConsoleOne.  However there are requests to convert mailboxes – but without C1! This article will explain how to convert mailboxes in GroupWise 2014 (and newer) environments.

Using Resource Mailboxes

Resources are a long-time feature of GroupWise and are limited mailboxes used generally for booking places and resources; for example conference rooms and display projectors.  Groupwise 2012 SP2 introduced the additional class of role based resources.  A role resource represents a position in an organisation that can be reassigned from one owner to the next.

As owners change, the role resource mailbox retains all information associated with the role.  Unlike general resources and place resources, role resources are included in ‘Reply to all’ actions and so function much more like a standard user mailbox.  Role resources are configured by selecting the Resource Type of Role on the Resource configuration dialog page.

Examples of roles could be ‘Receptionist’, ‘Security’, ‘Sales Support’, or ‘Helpdesk’.  Organisations will have differing fixed roles of this type.

Prior to GW2012 SP2 these roles would probably be configured as standard user mailboxes, but when the owner leaves there could be a lot of vital information held in the mailbox that needs to be retained.  The GroupWise administrator has a number of native options:

1. Archive the mailbox, but GroupWise archives have limitations and only easily accessible by the owner.
2. GroupWise 2014 introduced the Inactive User licence. However this does not allow the mailbox to receive or send messages, as you might expect from the name.
3. Convert the mailbox into a Role resource.  This provides (transferrable) ownership (which I like) and all the content is retained as well as proxy rights and rule processing. Messages can be sent and received by the role resource, and all these steps can be done with simple mouse clicks because you can live in this foreign mailbox using the proxy feature.
   Another positive benefit of converting a role from a user into a resource is that there is no license fee associated with a resource mailbox.  However of course you do have to have a user mailbox as the owner.

GroupWise 2014 and the REST API

With GroupWise 2014 administration has changed – GroupWise is maintained through its new web based user interface – the GroupWise Administration Console. Via this gui a service is triggered to configure and maintain your whole GroupWise environment. It’s called the gwadminservice which runs by the side of MTAs (message transfer agent), POAs (post office agent) or GWIAs (GroupWise internet agent).

The gwadminservice listens on port 9710 to fulfil instructions to change, create or delete GroupWise objects. All these activities are performed via a new interface, the GroupWise Administration API. The GroupWise Administration API provides GroupWise developers access to events and actions that occur at the GroupWise Administration console. The GroupWise Administration API uses Representational State Transfer (REST) architectural principles. If you access your server via https://server_address:9710/gwadmin-service/ you will get some more explanation and examples. If you need a good tutorial and description then continue with GroupWise SDK: Administration REST API Guide which is available at the Micro Focus (Novell) web site.

In Open Horizons Magazine Issue 28, 1/2015, Robin Redgrave discussed building a million user GroupWise system using the REST API. This is a good example to get an impression of how powerful this interface is. Another excellent article has been written by Tommy Mikkelsen in 2014. I do not spend too much time playing around with the REST API - I just want to convert mailbox types.

Principle of Conversion

There is no command or preconfigured process to convert a user mailbox into a resource mailbox and vice versa. Tay Kratzer documented a procedure where in several steps a user can be transformed into a resource. Using ConsoleOne in a tricky and specific way is the key element in his procedure.  I highly recommend you follow ALL his steps in the right order if you have to do it for GroupWise 2012 and older versions.  Otherwise you will probably delete an important mailbox.

The next few lines will explain the background to Tay’s and my procedure. For each mailbox (user, resource) a user database exists in the post office OFUSER directory. Usually a user database is named userFID.db – FID means File IDentifier.  A FID is unique for each mailbox within one post office. It is not possible for two mailboxes to have the same FID on a post office. Usually a FID consists of three characters.

 

My screenshots are based on a test server which has been used at an Open Horizons Summit in Budapest. (So if you recognize some names you know they attended our Summit in Budapest!)

My GroupWise Administration Console shows this information:

Tay’s procedure was :

1. Find the corresponding FID
2. Rename the respective XYZ user database
3. Check if the post office agent recognises it
4. Delete that user
5. Create a resource
6. Assign the file id XYZ to this resource using some weird ConsoleOne behaviour and
7. Rename the XYZ user database back to its original name

Tay’s trick was to use ConsoleOne with and without GroupWise snapins. But now we are not able to use ConsoleOne.  Instead we have to use a new feature of the GroupWise 2014 REST API.  Fortunately this step is even faster and simpler.

Here are the new steps:

1. Find the corresponding FID
2. Rename the respective XYZ user database,
3. Check if the post office agent recognises it
4. Delete that user
5. Create a resource with FID XYZ
6. Rename the XYZ user database back to its original name

Our advantage is that we can create a user or resource with a file id which can be defined directly by ourselves. We do not have to play tricks with administration tools.

The Day Before

If you have to convert a user into a resource then make sure that:

• The user is not the owner of any resources. (If so then move resource ownership to other users)
• They must not be the administrator of GroupWise distribution lists.
• They must not be the administrator of post offices, domains or your system (GW2014 feature)
• They must not be the librarian in your GroupWise DMS (document management system).

Because a resource is a different type of mailbox you will change some behaviour.  Check if:

• All the rules fit the behaviour of a resource instead of a user (Reply rules, …).
• Membership of distribution lists is still reasonable.

Converting a user – an example

I will convert a user in my GroupWise environment. In my screenshots before there was a user aeinstein, Albert Einstein; his file ID is 5da. Therefore his user database is user5da.db.  I log in as aeinstein and search for all items (fig 4).  I want to record how many items are stored in this mailbox and compare it to the counter after conversion.

The FID for aeinstein is 5da so just rename Einstein’s user database by:

#  mv user5da.db user.5da.bak

My POA has to recognise that a user database is missing. Sometimes it helps to restart the POA (but do not restart your POA during key business hours) - I log in again with account aeinstein and expect error C05D. Do not continue without a C05D!

Now it hurts I know – but delete the account aeinstein. If you try to login again with aeinstein you will receive “User ID aeinstein not found”.

Now use the REST API to create a resource with FID 5da. There are several ways to start and process REST API calls.  My GroupWise system runs on Linux so curl scripts are the easiest way, because curl is already part of Linux.

The generic command is as shown below.  Just replace the parameters with your details.

curl -k --user admin:password https://server:9710/gwadmin-service/domains/dom/postoffices/po/resources -H “Content-Type: application/json” –X POST -d ’{“name”: “resource1”, “fileId”: “abc”,”owner”: “owner1”}’

In my example I enter this command.

curl -k --user admin https://172.16.2.254:9710/gwadmin-service/domains/do1/postoffices/po1/resources -H “Content-Type: application/json” -X POST -d ‘{“name”:”resource1”, “fileId”: “5da”,”owner”: “admin”}’

Resource1 should contain all data from aeinstein. Admin is the owner of resource1 and should be able able to access Einstein’s information. But if I try to access now it will cause an error because I still have to rename the original database to its original name.
When this final step has been completed – the resource mailbox is accessible by the owner admin. If admin tries to check how many items this mailbox contains it will count 31 items. This is the same number from when we did the first check.

The Day After

I have transformed user mailbox aeinstein into a resource mailbox resource1.  Are there any side effects to deal with afterwards?

All shares survive! If there are any shared folders, address books or calendars they will keep on working. None of the rights should be lost. The (new) owner of the resource has the ability to add, delete and configure these shares and add new ones.

The owner of the resource is able to access the resource’s archive. Just proxy into the resource and then access the archive, but remember that the owner needs access to the archive path of the resource!

Maybe the user who has been converted was proxied by other users? These proxy rights will still exist. But if you changed the original name into a new one then you have to search for the new name before you can proxy.

In my example I changed the name from aeinstein into resource1. In this case I have to select the new name. If I had kept the same name during the conversion then proxy access would not be influenced in any way.

Conclusion

I have used Tay Kratzer’s procedure many times and if you follow his steps precisely you will not fail. After the release of GroupWise 2014 and my experiences with the new GroupWise Administration Console I was initially a little embarrassed if customers made this request.

But now it is even easier with the REST API. I have converted users several times without problems. I have even converted resources back to users because users have returned to their business.

Now I am happy again because I can fulfil requests without any tricky administration. In addition I have seen the power of the REST API and how simple it is to use.

 

This article was first published in OHM Issue 30, 3/2015, p23-25.