ibm connections 5.0: custom community metrics reports

IBM Connections 5.0

Author: Paul GodbyBusiness Development & ISVsLast Updated: June 19, 2015Duration: 45 minutes

IBM Connections

Lab Manual

Creating a custom Metrics

Community report

COPYRIGHT IBM CORPORATION 2015. ALL RIGHTS RESERVED.

1

IBM Connections 5.0

Introduction:The Metrics application in IBM Connections provides a comprehensive set of quantitative and qualitative metrics that help measure the business value of IBM Connections in your organization.

IBM Connections uses IBM Cognos Business Intelligence to collect and maintain metrics, and to generatereports that users can view directly in IBM Connections. Metrics reports can be presented as tables or charts that you refine by selecting options such as the time period to report on, a particular application to focus on, or how to group users in the results.

IBM Connections provides metrics on two levels: Global and Community. A Global metrics report is generated every time that the user clicks it; however, the report data is updated on a daily basis. Refreshes are typically scheduled during off-peak hours to avoid degrading system performance.

Community metrics reports focus on a particular community. For example, the number of people who logged in to the Sales community last week. Community metrics are generated on demand and are then cached until a new report is requested. Requests are place into a queue and are processed in order. Aftercommunity owners submit requests, they can work in other areas of the application until the report is ready for viewing.

The IBM Connections administrator has implicit access to all metrics reports. Community owners can view metrics for their own community, but cannot view global metrics. Other users who require the information can be authorized to view global metrics; for example, managers might require access to metrics for business purposes even if they do not manage a community.

Description:In this lab, you will learn how to build a custom Metrics report for IBM Connections.

Objective:This lab will explain the following tasks:

• How to manage permissions and determine who can see and/or create new reports

• How to use Cognos Report Studio to build a new report

• How to configure IBM Connections to display the report


2

IBM Connections 5.0

Procedure:BEFORE YOU BEGIN

Step 1 Workshop: This lab exercise was originally created as part of the following workshop. At the end of this document you will find instructions and links for accessing the materials.

IBM Connections 5.0 Customization Workshop

Step 2 Prerequisites: You must complete the following labs before proceeding with this exercise:

There are no prerequisite labs.

Step 3 Prerequisites: You must complete the following additional steps / installation / configuration before proceeding with this exercise:

You must install Cognos as outlined in the Workshop Setup Guide.

Step 4 Solutions Files: This lab may require additional files. If you are asked to write code or configure an XML file, there may be snippets available for you to review or copy/paste text to/from your lab environment. These files are located at:

There are no solutions files for this lab.

Step 5 Important! Review the workshop setup document for instructions on configuring the SoftLayerdevice for this lab. You should also review the information about user accounts and permissions. The lab instructions will assume you are using the proper user account(s)!


3

IBM Connections 5.0

CREATE SAMPLE DATA

Before we can begin to work with Cognos Reports, you first must have a system with data.Otherwise, your reports wouldn't be very interesting! In this lab environment, you will use acustom command-line utility to populate IBM Connections with some test data.

Step 6 Before performing these steps, make sure your local workstation has an Oracle Java Runtime Environment (1.6+) installed. If necessary:

Download the latest Oracle JRE

Step 7 Visit the following URL and download the utility to your local workstation. If you are external to IBM, you will need a free IBM Greenhouse account.

IBM Internal: IBM Connections Demo Assistant

IBM External: IBM Connections Demo Assistant

Step 8 Extract the archive to a location on your local workstation.

Step 9 Using the information found in the links above, download the IBM Connections 5.0 Workshop data file and place it in the following location:

/icda/data/ic5_workshop_V2.xml

Step 10 Using a text editor, open the following file to perform some minor configuration:

/icda/icda.properties

Step 11 Update the following properties as follows. Then, save and close the file.

connections.url=https://<< Host Name >>

file.data.import=ic5_workshop_V2.xml

Note: If you are not using the IBM Connections SoftLayer device, you will need to create anew users file for your environment. See the greenwell_users.xml file for an example.


4

https://java.com/download

https://greenhouse.lotus.com/wikis/home?lang=en-us#!/wiki/ICS%20Demo%20Tools/page/IBM%20Connections%20Demo%20Assistant

https://w3-connections.ibm.com/wikis/home?lang=en#!/wiki/ICS%20Demo%20Tools/page/IBM%20Connections%20Demo%20Assistant

IBM Connections 5.0

Step 12 In a terminal/command window, populate IBM Connections with some test data with the following commands:

cd << extracted location >>/icda

java -jar icda.jar import

Step 13 When the application has finished creating content, you will be returned to the command prompt. You should now have some demo content for this exercise!

The following steps assume you are now working on the server through a VNC client.

REFRESH POWERCUBE DATA

By default, IBM Cognos Transformer refreshes each PowerCube with incremental updatesonce each day, and replaces the cube’s data for the current month once a week. These jobsare scheduled by default but you might need to modify the schedules to avoid conflicts withother activities.

Step 14 In a terminal window, enter the following commands to run the build-all script to make sure the metrics are loaded successfully and to generate an initial set of data.

cd /opt/IBM/Cognos/Transformer/metricsmodel

export LD_PRELOAD=/usr/lib/libfreebl3.so

./daily-refresh.sh

Step 15 You can safely ignore any error messages in regards to the LD_PRELOAD environment variable. In the output, you should see the message: daily refresh success

Step 16 While you are at it, go ahead and run the weekly rebuild script as well. In the same terminal window, enter the following commands:

./weekly-rebuild.sh


5

IBM Connections 5.0

Step 17 Once again, you can ignore any error messages in regards to LD_PRELOAD. In the script output, you should see the message: weekly rebuild success

Step 18 (Optional) You just ran the scripts individually to demonstrate that Metrics incremental data willget generated daily while monthly data gets generated weekly. You can, at any time, run both of these scripts with a single command to manually regenerate all of the data. In the same terminal window, enter the following commands to do a full rebuild:

./build-all.sh

Step 19 Close the terminal window and proceed to the next section.

CONFIGURE THE COMMUNITY-METRICS-RUN ROLE TO VIEW COMMUNITY METRICS

Community metrics are available to community owners. In this section, you will learn moreabout how to control who can see and run these types of reports.

Step 20 Navigate to the following URL and log in with the credentials provided:

https://<< Host Name >>/ibm/console

Field Value

User name wasadmin

Password iBMC0nn3ti0ns

Step 21 On the left, select Applications → Application Types → WebSphere enterprise applications

Step 22 On the right, click the link for Metrics

Step 23 Under the Detail Properties section, click the Security role to user/group mapping link.


6

IBM Connections 5.0

Step 24 On the next page, notice that the Special subjects is set to "All Authenticated in Application's Realm" for the "community-metrics-run" role. This means all Community owners have access to view Metrics in their respective Communities. To restrict this access, you would remove "All Authenticated..." and assign individual users or groups. For now, leave the default configuration and proceed with the exercise.

Step 25 Click Logout to exit the Integrated Solutions Console.

REVIEW THE DEFAULT COMMUNITY METRICS REPORTS

Before you start modifying and creating new Metrics reports, you should review what'salready available to get a sense of the types of data you can report on as well as the typesof reports that are available.

Metrics summarize how people are using IBM Connections. Metrics can be presented astables or charts that you refine by selecting options such as the time period to report on, aparticular application to focus on, and how to group users in the results.

Community metrics report on a particular community; for example, the number of peoplewho logged into the Sales community last week.

Note: Depending on what you have been doing on the server, the data in the screenshotsin this section may differ from what you see.

Step 26 In a web browser, navigate to URL:

http://<< Host Name >>/communities/service/html/ownedcommunities

Note: This URL is using HTTP and not HTTPS!

Step 27 Log in with the following credentials

Field Value

User name fadams

Password passw0rd


7

IBM Connections 5.0

Step 28 You should see a list of communities that you own. Click on the Lab – New Community Features community.

Step 29 After you enter the community, click on the Metrics link in the navigation menu.

Step 30 (FYI) In the past, at this point you would click an Update Metrics button to refresh the data. As of IBM Connections V4.5 CR2, this button has been removed. Community metrics are now only updated during the daily jobs that are run.

Step 31 Use the links on the left to review the available community metrics. Choose Participation.

Step 32 By default, you will see a line chart for the Number of visits. It's possible the dates listed may not include the current date. If so, choose "Last 7 days" from the View drop-down list.


8

IBM Connections 5.0

Step 33 Since this server was just provisioned, and you only loaded a small amount of demo data, this chart probably isn't very interesting. So, scroll down below the chart and locate the line for Number of new updates. Click Compare Apps.

Step 34 You should see a pie chart for the Number of unique contributors. Nice!

Step 35 Feel free to explore the other Community metrics. When finished, log out of IBM Connections and leave the current browser session running.


9

IBM Connections 5.0

CREATE A NEW METRICS REPORT

You can use IBM Cognos Report Studio to create new custom reports for Metrics.


http://<< Host Name >>:9085/cognos/servlet/dispatch/ext



Field Value

User name fadams

Password passw0rd

Step 38 On the upper right, in the IBM Cognos Connection, start the Cognos Report Studio by clicking the Launch drop-down menu and choosing Report Studio

Step 39 A new Select a package browser window will open. You will want to choose a package that allows you to query the PowerCube containing IBM Connections Metrics data. In this new window, click IBMConnectionsMetrics.


10

IBM Connections 5.0

Step 40 On the next page, click Metrics.

Step 41 IBM Cognos Report Studio should now launch! Click Create new to create a new report.

Step 42 In the New window, select Chart followed by OK.

Step 43 In the Insert Chart window, choose Column on the left. On the right, choose the Column with3-D effects (the second one from the left). When finished, click OK.


11

IBM Connections 5.0

Step 44 Your new report template will open. First, you should create a Default measure on the Y-axis. The Y-axis typically displays quantitative data, or something that can be “counted”. For example, it may describe sales figures, totals, or quantities of some type. In the Source window on the left, choose METRICS_TRX_CUBE → Measures. You will see a list of available measures.

Step 45 Click on EVENT_COUNT and drag this measure to the chart on the right where it says “Defaultmeasure (y-axis): Drop item here”. When finished, you will see “<EVENT_COUNT>” in the appropriate location on the chart.


12

IBM Connections 5.0

Step 46 Next, you will need to add some categories to the X-axis. The X-axis typically displays “things”. For example, various applications inside IBM Connections. In the Source window on the left, choose METRICS_TRX_CUBE → SOURCE → SOURCE → Members → SOURCE

Step 47 In this lab scenario, you pre-populated data for Bookmarks, Communities, and Forums. So, in the Source window, choose Blogs, Bookmarks, and Forums (CTRL-Click to select multiple items). Drag these items to the chart on the right where it says “Categories (x-axis): Drop item here”.

Step 48 When finished, you will see “<”BLOGS”><”BOOKMARKS”><”FORUMS”>” in the appropriate location on the chart.


13

IBM Connections 5.0

Step 49 You currently have a chart that will display a count of some type of data for the Blogs, Bookmarks, and Forums applications. Next, you will need to assign some type of data to the “count” Y-axis. In the Source window on the left, choose METRICS_TRX_CUBE → EVENT →EVENT → Members → EVENT

Step 50 In the Source window, choose CREATE, and DELETE (CTRL-Click to select multiple items). Drag these items to the chart on the right where it says “Series: Drop item here”.

Step 51 When finished, you will see “<”CREATE”><”DELETE”>” in the appropriate chart location.

Step 52 Now that you have created your chart and identified the data it will track, it's time to customize some of the other details of the report. To change the name of this new report, double-click where it says Double-click to edit text.


14

IBM Connections 5.0

Step 53 In the Text window, add a new title by entering “ESS Community”. When finished, click OK.

Step 54 Single-click this text box to select it in the page layout. This will show the properties for this particular item in the Properties window on the bottom left.

Step 55 In the Properties window, scroll down to the Positioning section. Double-click the white box to the right of the line item for Size & Overflow.

Step 56 In the Size & Overflow window, enter the following information and click OK. This will resize this text box so that it aligns better with the chart.

Step 57 In the chart, expand Axis titles. Single-click the default x-axis title (the one with text running horizontally). This will open details for this title in the properties window.

Step 58 In the Properties window, scroll to the General section and set the Default Title option to “No”.


15

IBM Connections 5.0

Step 59 In the Page Layout window, the x-axis text should have changed from “(Default Axis Title)” to “Double-click to edit text”. So, do just that. In the Text window that appears, enter “Connections Applications” and click OK.

Step 60 Using the same process as before, change the text for the y-axis to “Number of Events”

Step 61 The series is actually a smaller bar chart. Cool, huh? To change the text for the series, single-click the (Default Legend Title) to open the properties window.

Step 62 In the Properties window, scroll down to the General section and set the Default Title option to“No”. Double-click the legend title and enter “Event Types”


16

IBM Connections 5.0

Step 63 Finally, you can also change the labels for individual data items in the report. In the Categories(x-axis) section of the chart, single-click “BLOGS” to display the properties window.

Step 64 In the Properties window, you can set the label to anything you would want to display instead of “BLOGS”. For example, you might want to use proper case (so it doesn't look like shouting) and change the name to “Blogs”. Or, if Blogs are called something else in your environment, you could rename it here. You can also change the labels for event types in the series. For now, leave the default values.

Step 65 From the file menu, choose File → Save. In the Save As window, choose Public Folders on the left. On the right, choose a location of IBMConnectionsMetrics → Metrics → customReports. Name the report “ESSCommunity”

Step 66 When finished, click Save. You've created a new IBM Connections Community Metrics report! Pat yourself on the back.

Step 67 Next, you should test the report. From the file menu, choose Run → Run Report – HTML


17

IBM Connections 5.0

Step 68 View the results to compare “Create” vs “Delete” events for the selected applications! Notice that your new user friendly labels are also being used!

Step 69 Close this IBM Cognos Viewer tab in the web browser.

Step 70 When you launched Cognos Report Studio, it opened in a new browser window. Switch back to this other window to return to the IBM Cognos Report Studio.


18

IBM Connections 5.0

CONVERT THIS REPORT INTO A COMMUNITIES REPORT

A slicer is a filter that will return portions of a data set. In this particular case, you will apply aslicer to the custom report so that it will return data only for the specified Community.

Unlike global reports, which are run on-demand when requested by a Metrics administrator,Community reports are only refreshed once a day. You will need to add your custom reportto the jobs list so that it also gets refreshed on this daily schedule.

Step 71 You should be back in Cognos Report Studio and viewing your new custom report.

Step 72 Notice that there is a narrow menu that appears between the Page Layout window and the Source window titled “Page Explorer”. Click the second icon down to open up the Query Explorer window. In this window, choose Query1.

Step 73 After the Query Explorer opens, locate the Source window on the left. Select the Toolbox tab.


19

IBM Connections 5.0

Step 74 Inside the Toolbox window, double-click Slicer Member Set.

Step 75 In the Slicer Member Expression window, locate the Expression Definition section and paste the following expression. This expression will return the community by ID and will be applied toall calculations in the query.

filter([METRICS_TRX_CUBE].[COMMUNITY].[COMMUNITY].[COMMUNITY NAME] , [METRICS_TRX_CUBE].[COMMUNITY].[COMMUNITY].[COMMUNITY NAME].[COMMUNITY NAME - Category Code]=?dcommunityid?)

Step 76 Click OK. You should see your new slicer expression appear in the Slicer window (bottom right corner). You could continue to add slicers to further refine the data. In this lab, just continue with the exercise.

Step 77 Save the report.

Step 78 From the file menu, choose File → Exit to close the Cognos Report Studio.


20

IBM Connections 5.0

Step 79 Return to the original web browser window. You should now be back in the IBM Cognos dashboard with the Public Folders tab selected.

Step 80 For Community reports, you must add them to the jobs list so that they get refreshed during thedaily refresh task. You can do this by placing a copy of the report in the appropriate location. Choose IBMConnectionsMetrics → Metrics → customReports. You should see your custom report listed.

Step 81 On the left, place a checkmark beside your report named "ESSCommunity"

Step 82 In the toolbar on the upper right side of the page, click Copy.

Step 83 From the breadcrumb trail, click Metrics to move up one level in the directory structure.


21

IBM Connections 5.0

Step 84 Choose IBMConnectionsMetrics → Metrics → community → customizedTheme

Step 85 In the toolbar on the upper right side of the page, click Paste.

Step 86 You should see your new community report, ESSCommunity, listed in this folder.

Step 87 Log Off of the IBM Cognos Connection and leave the browser open.

ADD THE NEW COMMUNITY REPORT TO THE IBM CONNECTIONS METRICS USER INTERFACE

After you create a custom report, edit the reports-config.xml file and add a new entry for thecustom report. The entries in this file determine which reports appear in the list that displaysin the Metrics user interface.

Step 88 You must add the report to a configuration file to surface it in IBM Connections.

Step 89 The wsadmin tool is a command shell for the purpose of performing systems administration on all the artifacts in an IBM WebSphere Application Server (WAS) cell. In a terminal window, enter the following commands to start the wsadmin tool.

mkdir /config

cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin

./wsadmin.sh -lang jython -user wasadmin -password iBmC0nn3ti0ns


22

IBM Connections 5.0

Step 90 Next, store references to your IBM Connections configuration environment in a few variables. By storing these values in variables, you can easily reference them in subsequent wsadmin commands. In the wsadmin session, enter the following commands:

path = "/config"

cell = AdminControl.getCell()

Step 91 Now that your session is configured, check out the Metrics configuration file with the following commands:

execfile("metricsAdmin.py")

MetricsConfigService.checkOutConfig(path, cell)

Step 92 Leave the terminal window with your existing wsadmin session open.

Step 93 Edit the checked out configuration file named:

/config/reports-config.xml

Step 94 In this configuration file, you should see a section for Global reports and another section for Community reports.

Step 95 In the Communities section, you can add your own groupings and nest reports as required. You can accomplish this in two different ways:

1. Nest report entries inside each other to achieve the desired layout. Since the top-level entry is also a report, it will display a “default” report when clicked.

2. Create a category entry. Nest your report entries inside this category. In this scenario, the top-level entry will not display a “default” report when clicked.

Step 96 In this lab, you will use option 2 to create a category and nest your custom report(s) inside. Adda new category to the Community section of the configuration file by adding the following XML fragment:

<entry id="ESSCommunityCat" type="category" label="ESS.COMMUNITY.CATEGORY">

</entry>

Step 97 When finished, your XML should now look like the following:


23

IBM Connections 5.0

Step 98 Inside your new category entry, add a new nested entry describing your custom community report. Add your new report with the following XML fragment.

<entry id="ESSCommunity" type="report" label="ESS.REPORT.NAMES.ESSCOMMUNITY"><link>ESSCommunity</link>

</entry>

Step 99 When finished, your XML fragments should look as follows:

Step 100 The id for each entry must be unique. The label is a key that will be referenced later to pull in auser friendly display value from a strings properties file. Inside the link tag, you must enter the name of the report you created.

Step 101 Save and close the reports configuration XML file. Close the text editor.

Step 102 Return to the terminal window with your existing wsadmin session. Check in your changes with the wsadmin tool using the following command:

MetricsConfigService.checkInConfig(path, cell)

quit

Step 103 Close any terminal windows you opened in this lab. Proceed to the next section.

CREATE A STRINGS RESOURCE BUNDLE

In the previous section, you entered some keys in the reports XML configuration file. In thissection, you will map these keys to more user friendly strings that will appear in the IBMConnections user interface.

Step 104 Create a new properties file named

com.ibm.connections.metrics.ui.strings.ui.properties

Step 105 in location

/opt/IBM/Connections/data/shared/customization/strings

Step 106 In this new file, enter the following lines. If the file already exists, just append the lines. As youcan see, you will be providing key-value pairs for each of the entries you created in the report XML configuration file.

ESS.COMMUNITY.CATEGORY=ESS ReportsESS.REPORT.NAMES.ESSCOMMUNITY=ESS Events


24

IBM Connections 5.0

Step 107 Save the file but do not close it (yet!). You just created the default properties file. In a production environment, you will need to create additional properties files for each supported language. You can do this by creating a new strings file (in the same directory) with the language code appended to the name. In this example, you can create a new strings properties file for the English language by creating a new file named:

com.ibm.connections.metrics.ui.strings.ui_en.properties

Step 108 Save and close the file(s). Close the text editor.

Step 109 With most string customization processes in IBM Connections, you need to restart the affected application(s) for the changes to take effect. For Metrics, this isn't necessary.

REVIEW YOUR NEW COMMUNITY REPORT

Now that your custom report has been built and added to the IBM Connections userinterface, it's time to review the new data that will give you insights into your deployment.


http://<< Host Name >>/communities/service/html/ownedcommunities



Field Value

User name fadams

Password passw0rd

Step 112 You should see a list of communities that you own. Click on the Lab – New Community Features community.

Step 113 After you enter the community, click on the Metrics link in the navigation menu.


25

IBM Connections 5.0

Step 114 On the left, in the navigation menu, you should see your new category and your new community report! Notice that if you click on ESS Reports that no default report is loaded. It is just a category for grouping purposes and nothing more.

Step 115 Click on the ESS Events link to view your new report. Change the View drop-down list so that the report displays the "Last 7 days".

Step 116 You're done!


26

IBM Connections 5.0

Summary:

In this lab, you learned how to create a new custom report for IBM Connections Metrics.You also learned how to add custom reports to the Global Metrics application. Finally, youlearned how to provide custom strings for you labels for the user interface.

Next Steps:Access FREE education on the IBM Collaboration Solutions portfolio of products today!

1. Visit the IBM Greenhouse and create a free account.

Link → http://greenhouse.lotus.com/

2. Visit the IBM Collaboration Solutions Ecosystem Development Community

Link → https://greenhouse.lotus.com/communities/community/icsecod

3. Learn new skills and share these links with your friends and colleagues!


27

https://greenhouse.lotus.com/communities/community/icsecod

http://greenhouse.lotus.com/

ibm connections 5.0: custom community metrics reports

Software

ibm connections administrator

community metrics reports

global metrics report

custom metrics report

metrics application

qualitative metrics

particular community

community owners