Note
	You can skip this section unless you need to install a sensor for a "multi-user" tool such as CVS or Jira.

Up to now, these instructions have been oriented toward "single user" development tools and their associated sensors. In other words, the assumption is that you are the user of the tool, and that data collected from the tool should be sent to your personal Hackystat account. For example, editors are single user tools, in that the sensor attached to your editor will collect data that is associated with your account in the hackystat server. In this case, which is the normal case, using HackyInstaller and supplying your user key is sufficient to allow your data to be sent to your account at the Hackystat server.

Figure 2.12, “ "Single user" tool communication with Hackystat ” illustrates data collection for a "single user" tool such as an editor.

Figure 2.12.  "Single user" tool communication with Hackystat

There is, however, another category of tool: a "multi-user" tool, such as a configuration management tool like CVS. A sensor for the CVS server will collect data on many different users' interactions with the tool. For example, if two users each commit two files to the CVS server during a particular day, then the sensor needs to send data to the two Hackystat user accounts corresponding to the two CVS users. Thus, this "multi-user" Hackystat sensor for CVS needs a "mapping" file that contains the list of CVS accounts for which Hackystat data is to be collected, and the Hackystat user key corresponding to each of these CVS accounts.

Figure 2.13, “ "Multi-user" tool scenario for Hackystat ” illustrates data collection for a "multi-user" tool such as the CVS server.

Figure 2.13.  "Multi-user" tool scenario for Hackystat

A Hackystat sensor for any tool that manages information for or from multiple users will typically need such a mapping file. Other tools of this type include bug tracking systems like Bugzilla or Jira. Sensors for these "multi-user" tools all refer to a file in the .hackystat directory called usermaps.xml in order to determine what users of the tool want Hackystat data to be collected for them and what Hackystat account they wish this data to be sent to.

Example 2.2, “Example usermaps.xml file” shows a sample usermaps.xml file. In this case, the usermaps.xml file contains user mapping data for two tools, CVS and Jira. This implies that both a CVS server and a Jira server are running on this machine. In the case of CVS, two users are having data sent to Hackystat, while in the case of Jira, three users are having data sent to Hackystat. Note that the users kawamoto and lee are having data sent from both tools, and so their data appears twice.

<usermaps> 
  <usermap tool="Cvs"> 
    <user toolaccount="kailani" userkey="8SNTD1234567"/>
    <user toolaccount="steve" userkey="456789dsTVxj"/>
  </usermap>
  <usermap tool="Jira"> 
    <user toolaccount="kailani" userkey="8SNTD1234567"/>
    <user toolaccount="steve" userkey="456789dsTVxj"/>
    <user toolaccount="gertrude" userkey="2ai6efA9z6F"/>
  </usermap>
</usermaps>

In this example, the usermaps.xml file contains user mapping data for two multi-user tools, the CVS configuration management system and the Jira issue management system. Kailani has a CVS account named "kailani", and the Hackystat user key "8SNTD1234567". Only two users of the CVS system wish their data to be sent to Hackystat, while three users of the Jira issue management system want their data sent to Hackystat.

To support the creation and maintenance of the usermaps.xml file, HackyInstaller provides the "Manage usermaps.xml file" command in the File menu. Figure 2.14, “ The HackyInstaller UserMaps editing window ” shows this window as it appears when invoked for the first time with no users.

Figure 2.14.  The HackyInstaller UserMaps editing window

As you can see, it provides a table that allows entry of a tool name, an account associated with that tool, and the Hackystat user key associated with that tool account. Clicking in any field allows you to edit and enter the appropriate information. Use the Tab key to move within fields.

Figure 2.15, “ The HackyInstaller UserMaps with data on kailani and steve ” shows this window after providing information about our example users kailani and steve.

Figure 2.15.  The HackyInstaller UserMaps with data on kailani and steve

As you can see, clicking on any row in the usermaps table enables two buttons. "Remove usermap" allows you to remove the selected entry from the table. "Validate key" allows you to check to see if the specified user key is valid for the Hackystat host listed in the main window. The results appear in the Status Log window on the main page.