IBM Support

How to Install IBM System Dashboard for Enterprise Content Management V5.0 and Integrate it with Content Manager Enterprise Edition V8.5

Question & Answer


Question

What are the steps necessary to install the IBM System Dashboard for Enterprise Content Management V5.0 (Dashboard) and integrate it with Content Manager Enterprise Edition V8.5 (CM) in order to capture and collect required license usage statistics?

Cause

  • IBM System Dashboard for Enterprise Content Management V5.0 does not provide the required IlmtReporter.conf file
  • IlmtReporter.conf is provided in IBM System Dashboard V5.0 fix pack 1
  • Additional, amplifying information regarding license usage statistics collection is also provided within this tech note

Answer

Notes:

  • The following values are "default" values used in a sample Content Manager Enterprise Edition V8.5 system
  • Please note that the relative values may be different in your own environment
  • Please adjust the values below as needed so that you use the correct values in the process below:
    • CM installation path is C:\Program Files (x86)\IBM\db2cmv8 for Windows or /opt/IBM/db2cmv8/ for UNIX, and any subdirectories or files under this path are referred to relative to this starting directory
    • WebSphere Application Server (WAS) installation path is C:\Program Files (x86)\IBM\WebSphere\ for Windows or /opt/IBM/WebSphere for UNIX, and any subdirectories or files under this path are referred to relative to this starting directory
    • IBM System Dashboard V5.0 installation path is C:\Program Files\IBM\FileNet\Dashboard for Windows or /opt/IBM/FileNet/Dashboard for UNIX, and any subdirectories or files under this path are referred to relative to this starting directory
    • CM library server represents the server on which the Content Manager Enterprise Edition library server component was installed
    • In the commands listed below, substitute your actual host name for any IP address or host name used in the examples (including the term "HOSTNAME"). The examples use values taken from a test system, and need to be modified as needed to match your environment's host reference.
  • The term "Windows" refers to a supported version of Microsoft Windows Server
  • The term "UNIX" refers to a supported version of AIX, Linux, or Solaris

  1. Apply Content Manager Enterprise Edition V8.5 fix pack 4 to the environment in order to include stability and performance improvements which are included with fix pack 4. The fix packs can be downloaded from IBM Fix Central.
  2. The Content Manager Enterprise Edition V8.5 software bundle should ship with the package
    "IBM System Dashboard V5.0 for Enterprise Content Management Multiplatform Multilingual (CIQ59ML)" -- install this package on your CM library server
  3. If the Dashboard installation fails with a "IBM JRE missing or cannot be found" message, update the library server's system PATH environment variable to include the path for the CM Java "bin" directory (for example, "C:\Program Files (x86)\IBM\db2cmv8\java\jre\bin" if running on Windows or "/opt/IBM/db2cmv8/java/jre/bin" if running on AIX, Linux, or Solaris)
    1. After updating the PATH variable, restart the server to ensure that the environment variable is picked up
    2. Run the Dashboard installation package again
    3. If you continue to receive the JRE error message, please contact IBM Support before proceeding with the rest of this note's process
  4. Next, use the IBM Support Portal to download the Dashboard V5.0 fix pack 1
    1. Enter "FileNet Product Family Support (general)" in the "Product Finder" field, then click on the product match that appears in the drop-down list with the same name
    2. Click the "Downloads (fixes & PTFs)" option
    3. In the "Product drop-down" list, select FileNet System Manager
    4. In the "Version fix level" drop-down list, select 5.0.0
    5. In the "Filter by operating system" drop-down list, select the appropriate operating system for your CM library server
    6. Click the Continue button
    7. Select the fix pack 1 option, which is listed as "fix pack: 5.0.0.1-P8SD-FP001 5.0.0.1-P8SD-FP001" (either click on the file link, or select that option by clicking in the selection box to the left of that option, then click the Continue button)
    8. When prompted, sign in using your IBM ID and password
    9. When prompted, accept the license terms by clicking the "I agree" button
    10. Download the files presented on the next screen to the CM library server (5.0.0.1-P8SD-FP001.zip and readme_5001_P8SD_FP001.htm)
  5. Using the instructions contained in the readme_5001_P8SD_FP001.htm file, install this fix pack to update the originally installed IBM System Dashboard V5.0 package above to fix pack 1
  6. After installing Dashboard V5.0 fix pack 1, there should now be a IlmtReporter.conf file in the Dashboard installation directory (for example, C:\Program Files\IBM\FileNet\Dashboard for Windows or /opt/IBM/FileNet/Dashboard if on AIX, Linux, or Solaris), as described in the CM V8.5 Knowledge Center article found here
  7. As outlined in the CM V8.5 article referenced above, set up and configure the IBM System Usage Reporter for Content Manager Enterprise Edition:
    1. Make a copy of the IlmtReporter.conf file found in the Dashboard installation path (default path is C:\Program Files\IBM\FileNet\Dashboard for Windows, or /opt/IBM/FileNet/Dashboard for UNIX)
    2. Open the IlmtReporter.conf file in Notepad (Windows) or vi (UNIX)
    3. Next, browse to the following path on the library server: default is C:\Program Files (x86)\ibm\db2cmv8\properties\version for Windows or /opt/IBM/db2cmv8/properties/version for UNIX
    4. Locate the file named "Content_Manager_Library_Server_UVU-8.5.0.swtag" and open it in Notepad (Windows) or vi (UNIX)
    5. In the IlmtReporter.conf, you should see this section:
      PRODUCT_GUID=
      PRODUCT_NAME=
      PRODUCT_VERSION=
    6. In the Content_Manager_Library_Server_UVU-8.5.0.swtag, you should see something very similar to:
      <Product InventoryTagVersion="1.0">
      <ProductName>Content Manager Library Server UVU</ProductName>
      <ProductVersion>8.5.0</ProductVersion>
      <SWGFMIDX>HCMLSU850</SWGFMIDX>
      <ProductReleaseID>b27c1c8a88314a9b9069c99a0535f41b</ProductReleaseID>
      </Product>
    7. Using the data found in the swtag file, populate the IlmtReporter.conf section mentioned above, as seen in the example below:
      PRODUCT_GUID=b27c1c8a88314a9b9069c99a0535f41b
      PRODUCT_NAME=Content Manager Library Server UVU
      PRODUCT_VERSION=8.5.0
    8. Save the file, and exit the text editor, leaving all other entries unchanged.
  8. Now that Dashboard is installed, and the IlmtReporter.conf file is properly configured, you need to run the collector batch file with the -t option to generate a database (DB) file/directory structure, as seen in the example below (this example was taken on a test library server running on Microsoft Windows -- the host name or IP address used will be different for your library server, and the referenced directory path may be different):
    C:\PROGRA~1\IBM\FileNet\Dashboard>ilmtcollector -t IlmtReporter.conf 192.168.1.220 32775
  9. The output of the command above will look something like this:
    IBM LMT Collector (Build-Number=pch511.128)
    Warning: Can't open the database.
    Warning: Creating new database in: jdbc:derby:.\ilmt_data.db
    Database created.
    Creating tables...
    Created tables.
    Connected to Listener #0 [192.168.1.220:32775]
    --> Processing Listener #0, 192.168.1.220, 32775
    Waiting up to 30 seconds for connection...
    Connected.
    Test completed.
    IlmtCollector Done.
  10. Once the command above successfully processes, you should see the ilmt_data.db folder in the Dashboard directory. This is required in order to run the data collection later on.
  11. Next, you will need to apply a test fix for FileNet System Manager in order to prevent the collector number from incrementing each time it is run (this test fix prevents the Dashboard Derby DB created above from continuing to add new collector number rows every single time that the collector is run).
    1. Make a backup copy of the original ilmtcollector.jar file found in the Dashboard installation directory (or simply rename the original copy)
    2. Replace the original version with the ilmtcollector.jar file found here:
      ilmtcollector.jarilmtcollector.jar
  12. If you are running on Windows Server with DB2 10.5, you also need to ensure that DB2 administrator ID (db2admin) and CM administrator ID (icmadmin) have full DB2 administrative authority.
    1. Amplifying information is found in the following article.
    2. The information contained in this article pertains to DB2 9.7 and later, including DB2 V10.1 and DB2 V10.5.
    3. In addition to what is called for in the article above, you also need to follow these steps:
      1. Connect to the library server database as the Windows operating system administrator ID (not the DB2 or CM administrator ID!)

        NOTE: "administrator" is the default Windows OS level administrative ID -- the ID may be different in your environment

        db2 connect to icmnlsdb user administrator
      2. Grant the DB2 dbadm authority to the DB2 administrator ID for the CM library server database:
        db2 grant dbadm on database to user db2admin
      3. Grant the DB2 dbadm authority to the CM administrator ID for the CM library server database:
        db2 grant dbadm on database to user icmadmin
      4. Commit the changes:
        db2 commit
      5. Terminate the DB2 connection to the library server database:
        db2 terminate
      6. Restart the Windows server

        NOTE: Without performing the above changes, the DB2 task scheduler will fail to run the CM stored procedure that pulls data from the library server database's ICMSTSTATSTAGING table and places it into resident memory on the library server while waiting for the collector and reporter commands to be run (the collector will first copy the usage data from memory into the Dashboard Derby database, and then the reporter will generate the output .csv usage reports based on the contents of the Derby DB)

  13. Now that the library server system is patched and ready, open the CM system administration client and log in as ICMADMIN (or its equivalent in your environment).
  14. Expand Library Server Parameters.
  15. Click on Configurations.
  16. Right-click on "Library Server Configuration" in the right pane, then select "Properties" from the context menu.
  17. Click on the tab labeled "License."
    1. The default values are a Start time of 00:00 (midnight) with a Frequency of 24 hours.
    2. If you wish to test functionality, or to have the license usage collected more frequently, adjust the values as desired.

      NOTE: Scheduling the DB2 task to run during normal business hours can cause issues accessing the library server database for CM users (including ICMADMIN) because the DB2 task places a temporary lock on the ICMSTSTATSTAGING table while collecting data.

If you wish to test the system to ensure that the CM license usage statistics collection and reporting are functional, follow these steps:

  1. The following test can only generate output data if:
    1. CM users (including ICMADMIN) have logged into and out of the CM system using any client, and:
    2. The DB2 task mentioned in the setup instructions above has already run, meaning that the current system time is AFTER the scheduled time for the DB2 task as seen in the CM library server configuration within the CM system administration client

      Notes:

      If no users accessed CM BEFORE the scheduled DB2 task is run, there will be no data in the ICMSTSTATSTAGING table to be collected, and the results will be empty.

      When ilmtcollector runs, it will collate the rows from the ICMSTSTATSTAGING table into entries per user ID. This means that the resulting count of processed records will not match the row count of the ICMSTSTATSTAGING table, and that number will typically be much lower than the actual row count. This is normal behavior.

  2. Check to confirm whether any usage data is already in the library server database's ICMSTSTATSTAGING table (substitute database name, ID, and password as needed to match your environment's values):
    1. Connect to the library server database with the CM administrator ID:
      connect to icmnlsdb user icmadmin using password
    2. Get a count of rows in the ICMSTSTATSTAGING table:
      select count(*) from icmadmin.icmststatstaging
    3. If you are not in a production environment, or you are working with the production system outside of normal business hours, you can optionally select the full table contents using the query below
      (note that the following command may take time and resources from the environment if the table contains many rows of data!):
      select * from icmadmin.icmststatstaging
    4. Sample results from a test CM 8.5 environment are listed here as an example of what the output might resemble:
      db2 => connect to icmnlsdb user icmadmin
      Enter current password for icmadmin:

      Database Connection Information

      Database server = DB2/NT64 10.5.1
      SQL authorization ID = ICMADMIN
      Local database alias = ICMNLSDB

      db2 => select * from icmadmin.icmststatstaging

      UNUM ACCESSTIME ACCESSCOUNT
      ----------- -------------------- -----------
      7 1440514333 25
      7 1440517163 1
      2 1440776505 18
      2 1442336393 17
      2 1442340777 76
      2 1442348712 67
      2 1442352064 101
      2 1442410959 21
      2 1442411424 21
      2 1443017259 19
      2 1443021598 22

      11 record(s) selected.

      NOTE: A more heavily used CM environment may have thousands of rows collected per day, if not more, which is why getting a simple row count is recommended.

  3. After confirming that the library server database actually has user license data, open a command prompt on the library server.
  4. Switch into the FileNet Dashboard installation path (the default is C:\Program Files\IBM\FileNet\Dashboard for Windows or /opt/IBM/FileNet/Dashboard for UNIX).
  5. Run the collector to collect the usage data currently stored in resident memory on the library server (this data was copied from the ICMSTSTATSTAGING table into memory the last time that the CM DB2 stored procedure task, ICMLSSUSAGESTAT, ran), and move it into the Dashboard Derby DB:
    IlmtCollector -u IlmtReporter.conf HOSTNAME 32775
  6. Now that the CM usage statistics data is permanently stored in the Dashboard Derby database, run the reporter command to generate an output file (.csv formatted) containing usage data for the specified date range (note that the name and location of the generated .csv file will be specified in the reporter's output):
    IlmtReporter IlmtReporter.conf -s 08/06/2013 -e 08/07/2015 HOSTNAME
  7. Verify that an output .csv file was generated with the name and in the path specified in the output of the reporter command above, then open the output file in an appropriate editor to view the data, if desired.
  8. At this point, you can then let the system operate as normal. Statistics should be captured as required, and when a report is desired, you can run the collector and reporter commands referenced above.

    NOTE: Depending upon when you run the two commands above, as compared to the schedule set in the library server configuration parameters, there may still be data in the library server database's ICMSTSTATSTAGING table that is within the date range you specified when running the collector and reporter. For this reason, you may want to limit your date range's end date to a day ago (or whichever value would pick up the data already in Derby DB based on your library server license schedule settings).

  9. Here are some additional notes that may prove helpful when testing:
    1. Set the library server license usage statistics schedule to a shorter interval during testing in a non-production environment (for example, every 15 minutes). This will allow you to test without having to wait too long to verify that statistics are captured after testing with a suitable CM client.
    2. All it takes to generate a new row in the ICMSTSTATSTAGING table is to log into any CM client with any authorized CM user ID, run a simple query, then log out of your client (don't just close clients such as eClient, as this may not actually call an ICMLOGOFF stored procedure call against the library server immediately).
    3. If you use the CM Client for Windows for your testing, you can just exit the client, and the logoff call is automatically made.
    4. You can verify that your logoff actions are captured by simply getting before and after row counts of the ICMSTSTATSTAGING table as mentioned above (or a full select * from ICMSTSTATSTAGING if you are not working in a production system). Your ICMLOGOFF stored procedure calls should add new rows to the table.
    5. After capturing some usage statistics within the table, you'll have to wait for the current library server statistics DB2 task to run as scheduled.
    6. If you have the library server statistics DB2 task scheduled to capture usage data every 15 minutes, for example, you'll have to wait up to 15 minutes after performing client activities for the data to be copied from the ICMSTSTATSTAGING table into memory (you can just run select count(*) from icmadmin.icmststatstaging periodically -- the count will drop to zero after the scheduled task runs if no other client actions are taken while waiting).
    7. Once you get a row count of zero on the ICMSTSTATSTAGING table, run the collector and then the reporter as described above, and you should see that the output file increases over time (assuming you always use the same start date, but you extend the end date to a later date than what was used in the last run, if statistics are only captured daily).

[{"Product":{"code":"SSAHQR","label":"IBM Z System Automation"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"Library Server","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.5.0.4;8.5.0.3;8.5.0.2;8.5.0.1;8.5","Edition":"","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Document Information

Modified date:
08 October 2019

UID

swg21970696

Page Feedback