1.6 Stubbing Server

Retain has the ability to use the Stubbing capabilities of GroupWise. Stubbing was designed as a way to reduce disk space usage in a time when the cost of disk space was at a premium. This is less of an issue today.

1.6.1 Stubbing Server Overview

The Stubbing server has two abilities:

  1. Enabling Retain Archive search Performing Retain Searches Within The GroupWise Client from the GroupWise desktop client.

  2. Removing items Configure Stubbing To Remove Messages from GroupWise and Leave Only Stubs from GroupWise and leaving stub pointers to the data in the Retain Archive. This functionality CANNOT be reversed. We do not recommend enabling this functionality.

How Retain Interacts With GroupWise Stubbing

When GroupWise is set up for stubbing and the Stubbing Server is configured in Retain, the archive job that runs will archive all the items and place in their stead in the GroupWise mailbox a "stub". Since the actual message gets placed into the Retain system, GroupWise replaces the original message with a stub that points to the message residing in Retain. A user's GroupWise mailbox will look the same - the user will see a list of messages; however, the icon is different.

When a user clicks on a stubbed message, the GroupWise POA will send a request to the Retain Stubbing Server for the item. Retain sends the item to the POA and the client displays it; however, this does NOT place the message back into GroupWise. When the user closes the message, the stub is all that remains.

Why Stubbing Is Good

  • Save Disk space. Mail can be removed from the system without being deleted.

  • Users have easy access to items stored in Retain.

  • Transparent access, no need to login to Retain for common tasks.

  • The "Restore" feature in Retain can be enabled. However, it does not actually restore the message into GroupWise. It only restores the stub if the stub is missing (user deleted it).

Why Stubbing May Not Work for a System

  • Stubbing CANNOT be reversed. Once a message is stubbed, it cannot be returned to the same position in the system.

  • Stub items are NOT COMPATIBLE with third party APIs. These applications view the stubs as posted items only, with no text or attachments. Mobile, Web, IMAP, and POP3 clients will only see posted empty items, not actual contents.

  • User training for stubbed items may be necessary due to decreased access speed.

  • No method for protecting stubs from deletion in the GroupWise client (re-creation is difficult and complicated).

  • Non-mail items should not be stubbed (calendar and appointment items behave erratically when rescheduled).

Determine the correct option for your system. If you wish to enable Stubbing, you need to install and configure the Stubbing Server as well. If you wish to only stub large items in your mail server, you may set a size threshold. Any item larger than the specified size will be stubbed. If this option is not set, all messages will be stubbed regardless of size.

1.6.2 Prerequisites

  • You must be using GroupWise 8.0HP1 or greater.

  • The GroupWise module must be configured. This means that a Trusted App Key exists for Retain to use already.

  • Confirm that stubbing is disabled in all the GroupWise profiles:

1.6.3 Stubbing Install

If you did not install the Stubbing Server during the initial install of the Retain Server you can install it now.

Run the installer and click through to the point where the installer detects what you have installed.

Choose "2) Upgrade current installation of Retain and add new components."

Then tell the installer to Upgrade Retain, preserving configuration. The installer will stop tomcat, install the Stubbing server and restart tomcat.

1.6.4 Stubbing Configuration


Update Trusted Application Key

  1. Go to the Retain Trusted App Key and enable "Allow access to archive service"

  2. Set the Archive Service Address to the Retain server IP Address or hostname

  3. Set the port to 48080 (the Retain tomcat port)

Now you have to decide if you are going to use stubbing on a particular Post Office or System wide.

Archive Service System Setting

If you are enabling stubbing across the entire system you will need to override the Archive Service Trusted Application setting in System Preferences.

Go to System | System Preferences.

Under Settings and Archive Service Trusted Application, enable the Override and select the Trusted Application Key that Retain is using.

Archive Service Post Office Settings

If you are just stubbing one, some but not all Post Offices you will need to override the Archive Service Trusted Application setting for each Post Office.

Go to the Post Office that will be stubbed.

Under Settings and Archive Service Trusted Application, enable the Override and select the Trusted Application Key that Retain is using.

1.6.5 Retain Stubbing Server Page

In Retain, open the Stubbing Server page from the left-navigation bar.

Core Settings tab

Check the box next to "Enable Stubbing Server"

You may restrict the IP addresses POA connections will be accepted from. Use commas to separate multiple addresses.

Logging tab

Set the logging level to Diagnostic (Trace)

Connection tab

If you have installed the stubbing server on a separate server you will need to specify the location of the Retain server so that it can connect.

The connection to the Retain Server is very important. This must be set to the address of the Retain Server, and is automatically filled out for you. Verify that the Retain Server is located at the specified address and is accessible. Generally you may leave this section default as the Stub Server should be installed local to the Retain Server. If your Retain Server IP address is assigned by DHCP, which we do not recommend, change the Host Name to the DNS name or localhost (

Press "Save Changes" and the Bootstrap tab will appear.

Bootstrap tab

Click on "Download File" to save the bootstrap file.

1.6.6 Configure Stubbing Server

Browse to http://<Retain_Stubbing_Server_Address>/RetainStubServer or http://<Retain_Stubbing_Server_Address>:48080/RetainStubServer and upload the bootstrap.

When the Configuration is complete, press Continue.

1.6.7 Stubbing Server Administrative Console

Path: http://stubbing-server-IP-or-DNS/RetainStubServer

Log in to the console with the admin user.

You will then see the Stubbing Server Configuration tab page, which looks much like the Worker page.

Configuration Tab

Path: Retain Stubbing Server Manager > Configuration Tab

Server Connection Tab

This tab will show you if the Stubbing server was able to connect to the Retain Server.

Path: Retain Stubbing Server Manager > Server Connection Tab

Status Tab

This tab provides statistics about what has been happening with the Stubbing server.

Path: Retain Stubbing Server Manager > Status Tab

Scheduler Tab

This tab is mainly used by support.

Path: Retain Stubbing Server Manager > Scheduler Tab

Scheduler Advanced Information Tab

This tab is mainly used by support.

Path: Retain Stubbing Server Manager > Scheduler Tab

1.6.8 Performing Retain Searches Within The GroupWise Client

Once GroupWise and the Stubbing server is configured to this point, it is possible to use the Retain Stubbing Server to allow GroupWise to search the Retain archive from the GroupWise client.

GroupWise client only performs whole-word searches. For example, searching for "wel" will only return messages with the word "wel" in them. Retain performs begins-with searches "wel*" and will return "wel", "well", "welcome" and so on.

NOTE:GroupWise client is hard-coded to search only up to 5 years in an archive search.


Setup Stubbing Server as above. However, do NOT enable stubbing in the Retain Profile.

In the GroupWise client click on the search magnifying glass icon. Under the Find tab you'll see an External Archive for the user that is the Retain archive.

In Online mode, click the checkbox to enable the External Archive search.

In Caching mode, you will also have to set Look in to Online data.

Now a search will search not only the GroupWise mailbox but also the Retain mailbox. The Retain ones will show the empty circle stubbing icon for the messages it has.

1.6.9 Configure Stubbing To Remove Messages from GroupWise and Leave Only Stubs

Enabling Stubbing in the Profile will cause Retain to automatically delete items from GroupWise and replace them with a stub pointer to the Retain Archives. This will have effects, for example, you will be able to see the header data in GroupWise but not the message bodies or attachments, on viewing the items in anything other then the desktop client.

Once you start stubbing in the profile you cannot reverse it. We do not recommend this use of stubbing.

Once GroupWise and the Stubbing Server have been configured as above, you need to enable stubbing in the Profile.

Retain will show a popup warning of the effects of stubbing.

WARNING:GroupWise will delete messages from the post office after they have been archived in Retain. Only use this option if you understand the implications to data integrity.

The next job that runs will delete items from GroupWise and replace them with stubs that point to the Retain Archives. Users will not be able to see anything other then the header data (Subject, to, from, date, &etc.) in WebAcc, or mobile clients. User will be able to read the whole message only in the desktop GroupWise client.

You would want to set the Date Range to Scan to "All Items in Mailbox" because what would be the point of stubbing only new messages.

Set up the Job

You can set up the job to use the Stubbing profile and select the Mailboxes to a particular Post Office or a particular User.

When the worker successfully dredges each item in the mailbox the item will be deleted and stubs placed.

GroupWise Client

In the GroupWise Client, messages that have been stubbed will be marked with an open circle icon. Opening messages may take a moment as the data is retrieved from Retain.

But in web access and third-party applications, you'll see nothing: