Permessa IM License Auditor for Lotus Sametime FAQ

Frequently Asked Questions

• General Questions

• What is the Permessa IM License Auditor and what does it do?

  The Permessa IM License Auditor™ is a software utility designed for a single purpose -- to provide fast, accurate counts of the IBM Lotus Sametime users across an entire enterprise or for selected servers.  You can calculate true accurate license counts for known users, active users and more.  The report also displays counts by client application and version number for detailed license tracking.  This information is based on the actual usage information gathered from the Lotus Sametime servers.  By using the generated audit reports, you will be able to ensure that you have the appropriate number of Sametime licenses corresponding to the number of users who actively use it.

  
• How can I get more help?

  Basic product usage information is provided with the "Help About" page of the IMAudit.NSF database. In addition to this FAQ, you can contact the Permessa Customer Support via email.

• My license is about to expire – what should I do?

  Unless you have a permanent product license, your Permessa IM License Auditor license may be subject to periodic expiration and renewal. If your license expires, then further data collection will not be possible until a new license is obtained.

  

  Permessa is currently offering an unlimited number of free 45-day license renewals for Permessa IM License Auditor. To renew your license, simply go to the trial page and submit a license request. A new license key will be emailed to you within minutes. To update the license key select the Configuration icon and open the License Information section. Replace the License Code field and then press Save & Close. You can now rerun your data collection.

• Configuration Questions

• What are the required prerequisites?

  The preferred installation host for Permessa IM License Auditor is an IBM Lotus Notes client, but the software can also be scheduled to run the data collection agent on a Lotus Sametime server.

  The administrator who runs Permessa IM License Auditor needs to have privileges to read the STLOG.NSF files for all Sametime servers of interest. The administrator must also have the ability to read the Lotus Domino Directory files to identify all users. There are no settings that have to be changed on the Sametime servers.

  In order to install and run the product, the administrator needs to have permissions to detach the Data Collection executable onto the local file system. If there are serious problems raised during data collection, Permessa IM License Auditor will attempt to send an email, based on the NOTES.INI settings.

  Permessa IM License Auditor supports Microsoft Windows operating systems and Lotus Notes versions 6.5.5 or higher. Collection from Sametime servers version 3.1, 6.5.1, 7.x and 8.x is supported.

  In order to run the data collection program, you need to configure your Notes client to bypass the login password prompt. Refer to the detailed instructions under: How do I set the login password bypass needed for data collection? -- further below in this FAQ.

• How do I get started and what is involved?

  Install and run the software manually on your IBM Lotus Notes client. After a few minutes of configuration, you will perform the following steps in order:

  1. Automatically discover the Lotus Sametime servers in your environment.
  2. Automatically discover the Sametime users in your environment.
  3. Collect all pertinent STLOG.NSF information from all Sametime servers.
  4. When the collection is finished, generate the audit report.

  In many cases, an entire week's worth of data will be collected and analyzed in less than an hour.

• How do I install Permessa IM License Auditor?

  Installation is simple.  Place the IMAudit.NSF file into the IBM Lotus Domino data folder. Open the database in your Lotus Notes Client and sign it with your Domino ID. Read the "Help – About this Application" section and click on the provided link to perform local installation of the data collection executable. After installation, add the license code and setup the Domino Directory source and you are ready to go.

• How do I apply the license code?

  The license code is a single key that is provided by Permessa in the email with the download instructions. Apply the key in the License Information section exposed by the main panel Configuration button, which is located on the left side of the screen. You will have to read and consent to the End User License Agreement before being permitted to Save & Close this configuration document.

  
• How do I indicate which IBM Domino Directory servers to use?

  In order to discover Lotus Sametime servers and users, you must indentify one or more Domino Directory servers. You do this by specifying a Domino server and its associated directory database (usually "names.nsf"). Each is placed in a separate configuration setting. If you have a cascaded Directory, specify each server and directory database, as a matched pair in their respective properties, separated by semi-colons. These properties are located in the Domino Directory Date Source section of the Configuration. For example, the set MAIL1 (names.nsf) and ST80 (names.nsf) as the source of all Domino Directory information, set your configuration as shown below.

  
• What if my IBM Lotus Domino Directory authentication uses Active Directory?

  If your Lotus Sametime environment is using Microsoft Active Directory instead of a Domino Names and Address Book (e.g. names.nsf) for authentication and name lookup, you will need to adjust the default configuration of Permessa IM License Auditor as shown below. The reason for this is that the IM log files list users using the format of the authentication system.

  

  Add the name of the Domain Controller for each segment of your Active Directory and a temporary file folder location where this information will be stored locally. In this mode, the retrieval of user information is handled by different buttons in the Auto Discovery view.

  

  Press "Export Directory to CSV" periodically (weekly, for example) to refresh this information in the local file system – in large environments this could take several minutes. After the export operation completes, press "Load Users from CSV" to populate the Permessa IM License Auditor, prior to performing a new round of data collection.

  WARNING: Do not attempt to perform "Load Users from CSV" while the "Export Directory to CSV" is running or user information may be lost.

• How do I display more diagnostic information?

  Generally, all operations will generate only the minimum amount of information necessary to report problems and monitor runtime status. If you need additional diagnostic information, set the Detail Logging field in the Log File section of the Configuration, as shown below:

  
• How do I refresh the list of IBM Lotus Sametime servers or users?

  Permessa IM License Auditor makes it easy to re-check the Lotus Domino Directory for new Sametime servers and new users. From the "Auto Discovery" view, press the "Auto Discover Users and Servers" button.

  

  This will run an update in the background, reconciling any differences. The status of the operation is shown in the status bar of your Lotus Notes client. For accurate results, please wait until the refresh operation completes before initiating a new data collection.

  New Sametime server and user documents will be added as necessary. Note that if a Sametime server or user has disappeared from the current list then the prior documents are not removed automatically. Nonexistent Sametime servers will lead to non-fatal collection errors. Remove these stale documents manually from the "Configured Servers" view. Logged access to Sametime by users who are no longer found in the Domino Directory will be recorded as activity by "unknown" users.

  Note: If your Domino environment uses Active Directory for authentication, then you will have two buttons, Export Users to CSV and Import Users to CSV, instead of a single one. The result is the same, but you must run the export to completion before starting the import.

  
• How do I set the login password bypass needed for data collection?  My system appears to be hung?

  The data collection program, IFM.EXE, is an IBM Lotus Domino-enabled application that is not able to visibly prompt for a user password when it starts. It will appear to hang unless Domino is configured locally to reuse the Lotus Notes client login session, as shown in the configuration panel below. This panel is generally found as File > Security > User Security and is documented in your Notes client help file as "Using your password with other Notes-based programs". If you choose not to set this Domino configuration parameter, you will need to manually run the data collection from a CMD prompt instead of using the user interface. The explicit instructions needed to do this are included in the error log generated.

  

• Operational Questions

• What is the general workflow of a data collection?

  After completing the initial configuration, the administrator should periodically (e.g. once a week) refresh the IBM Lotus Sametime information from the Lotus Domino Directory and launch a new data collection. Generate the audit report after the collection completes. The audit report will account for all previously gathered information. It is recommended to regularly remove all prior collected usage information (e.g. once per month) to avoid overcounting activity. Press the "Purge User Data" button in the Audit Results view to purge previously collected data.

  

  Data collection is initiated and monitored from the "Data Collection" view. Press the "Collect Data" button to initiate the collection agent. The agent launches IFM.EXE, which reads through the configuration and begins reading the STLOG information from each Sametime Server. Several collection status documents are displayed in that view to show the progress while the collection runs. The status bar of the Lotus Notes client will clearly show when the agent is running. Depending on the size of your environment, the amount of data that has changed since the last collection and the network bandwidth available, this process could run for a while.

  
• How can I tell the status of a running collection or when it is finished?

  Once the IFM data collection starts, one or more interim collection report documents will be shown in the view. Press F9 to periodically refresh this view if you wish to watch the intermediate status in real-time. The "Dispatcher" document summarizes the entire collection.

  

  As the collection runs and this view is refreshed, the latest detail status information is shown. The [Dispatcher] summarizes the overall collection progress and each server has its own individual status line. There are different running and error status indicators shown.

  

  To investigate details for problems encountered, double click on a document to open it.

  

  Even if there are errors encountered during collection, IFM will usually be able to perform a partial collection from available IBM Lotus Sametime servers. It is not recommended to generate an audit report based on an imperfect data collection. Instead, repair the underlying problems noted and perform the data collection again.

• I started data collection, but the view remains blank. What should I do?

  If the Data Collection view shows no progress documents added – even after waiting one minute and refreshing the view with the F9 key – it is likely that the Data Collection never started at all.  Most often this failure occurs because the data collector process (IFM.EXE) could not be located, failed to start due to permission problems, did not have write access to the database or was instructed by a configuration setting to write its data elsewhere.

  If the software cannot write a status document, it will attempt to send an email about the problem.  Check your email for additional explanation and consider re-running the data collector installation to reinitialize the settings (by pressing the installation button in the Help -> About this Application document).

• Why do I receive email when collection problems occur?

  There are several circumstances where the IFM data collection will attempt to get your attention by sending email. This will generally be the case for issues related to the configuration, such as an upcoming expiration of a product license or the failure to launch the data collection process.

  Very serious collection errors will usually produce one email for each failed server. The configuration record for each server can be set to not generate such email.

• The data collection generated errors – what should I do?

  Data collection errors may be of a transient nature, such as a failure to finish an operation before a timeout, or it may be related to access permissions. Open up any of the documents displaying errors to learn more about the problem. Once you correct the problems you can restart the collection.

  

• Data Interpretation Questions

• What does a typical Audit Report look like?

  Each time a data collection phases completes, an audit report can be manually generated by pressing the "Generate a New Audit Report" button in the Audit Results view. A typical report looks like this:

  

  The users are listed in several categories, based on whether they were actively using IBM Lotus Sametime during the analysis period or are currently listed in the Directory. The top Sametime application types are also categorized based on the unique client versions found.

  An itemized list of Sametime servers is shown, along with the last time the data was successfully collected. For each defined Directory server, the last refresh of the user information is listed.

• What is an "Active/Inactive" or "Known" user?

  An "Active" user is one that connected to IBM Lotus Sametime during the analysis period. An "Inactive" user is defined as a user that is configured to use Sametime, but did not connect to any of the configured Sametime servers on the days that have been analyzed. A user is "known" if there is a current record of that user in the Directory.

• Do these values correspond to the IBM Lotus Sametime licensing terms?

  Correlating the active user counts with the legal definitions contained in your Sametime license agreement may require additional configuration information and analysis. Please contact your IBM sales representative or Permessa Customer Support for assistance.

  The audit report distinguishes between "Basic" and "Advanced" usage, based on the client application type or whether the client accessed advanced features such as an e-meeting. For each user, all IM usage and clients are considered.  If all use is known to be using only "Embedded IM Clients" and no meetings were attended, then the user adds to the "Number of Known Basic Users" count.  Otherwise, the user adds to the "Number of Known Advanced Users" count. The sum of both is the "Number of Known Active Users". These relationships are illustrated in the Venn Diagram below.

  
• What are client application types?

  Most of the IBM Lotus Sametime clients, such as the client embedded in Lotus Notes, the standalone client, or other applications using the Sametime API to login and obtain services are captured in the Sametime log. Many of these application types are documented at http://www-01.ibm.com/support/docview.wss?rs=477&uid=swg21114318.

  Permessa IM License Auditor automatically maps and subtitutes the client codes for a human readable format.

• How do I learn which users are using particular IBM Lotus Sametime clients?

  Although Permessa IM License Auditor records all usage detail to ensure the accuracy of the overall Sametime activity metrics, information about individual users or servers – such as which users have been using older Sametime clients, or how many active users are accessing an individual server – is not reported by this product.

  This detailed information and much more is available using Permessa IM Control! Investigator. Please contact Permessa Customer Support for details.

• How can I correct the Company Name field shown in the Audit Report?

  The Company Name shown in the final audit reports is derived from the self-identified name embedded into the product license key. If you want to change the company name, you must submit another online license request with the corrected company name.

  Note: The company name will be displayed in upper case and some special charcters may get truncated.

• Why are all users marked as "Unknown Active"?

  For environments that use LDAP representation of user names in the STLOG, the default correlation with the IBM Lotus Domino Directory may not work properly due to an alternate representation of the authenticated user names (to a DN form with comma separators, such as uid=Joe User, ou=Marketing, o=BigBiz). In this case, open the Configured Servers view and press the button to choose the alternate user correlation algorithm. This is a one-time change.

  After correcting the correlation algorithm, use the Auto Discovery view to first remove previous user data and then re-populate that information correctly. From the Data Collection view, collect all data again. Audit reports subsequently generated will now match the LDAP version of the user name and the "Known Active" should now be accurate.

• How is meeting usage reported?

  Users that attend IBM Lotus Sametime meetings and n-way chats are recorded differently than those that communicate using normal Community Logins (such as a typical IM conversation). The difference depends on whether the attendees of the meeting are authenticated users or anonymous ones. In most cases, all anonymous users collapse onto a single generic user account and a detailed breakdown is unavailable. Permessa IM License Auditor reports meeting usage by distinct individuals with the Application Type named `Known Meeting Users'. Detailed reporting about individual meetings, the number of attendees, etc. is available in the Permessa IM Control! Investigator product.

• Why does the total number of active users seem too small?

  The accuracy of the audit results will depend on (a) providing adequate access to the entire IBM Lotus Sametime environment and (b) collecting all the data without errors. Usually the reason for a small active user counts is that some Sametime servers were not discovered due to missing Lotus Domino Directory information and hence never had their usage data collected. The second major cause of an apparent underreporting of active users will be due to data collection failures. Review the last collection status shown in the "Data Collection" view, correct any errors found, re-initiate data collection and generate a new audit report.

• Why does the total number of active users seem too large?

  In very rare cases, usage may get potentially over reported in IBM Lotus Sametime environments that have a frequently changing user base and when data gets collected for too long. In this case, users who used Sametime months ago but no longer work for the company will still be counted as active users.

  To prevent this from happening, simply remove the historical data by pressing the “Purge User Data” button in the Audit Results view before performing the next user population and data collection.

  Note: If your Sametime servers routinely retain STLOG information spanning more than one month, then even collecting data one time can produce an overly large active user count. In this case, go to the Configured Servers view, select all servers and press the “Set Date” button. You will be prompted for a new start collection date – express a date approximately 30 days prior in the form MM/DD/YYYY. After the prior collected data has been purged, the new data collection ignore records earlier than this new analysis start date.