StarTeam 12.0TeamInspector Help
Micro Focus 575 Anton Blvd., Suite 510Costa Mesa, CA 92626
Copyright © Micro Focus IP Development Limited . All Rights Reserved. contains derivativeworks of Borland Software Corporation, Copyright © Borland Software Corporation (a MicroFocus company) 1998-2011.
MICRO FOCUS and the Micro Focus logo, among others, are trademarks or registered trademarksof Micro Focus IP Development Limited or its subsidiaries or affiliated companies in the UnitedStates, United Kingdom and other countries.
BORLAND, the Borland logo and are trademarks or registered trademarks of Borland SoftwareCorporation or its subsidiaries or affiliated companies in the United States, United Kingdom andother countries.
All other marks are the property of their respective owners.
ii
Contents
Getting Started.........................................................................................................6Introduction to TeamInspector....................................................................................................6
Tour of the User Interface...........................................................................................................7
TeamInspector Setup Tasks.......................................................................................................9
Continuous Integration...............................................................................................................9
Logging On and Off..................................................................................................................10
Contacting Technical Support...................................................................................................11
Configuring TeamInspector...................................................................................13Configuration Settings..............................................................................................................13
LDAP Configuration Settings.........................................................................................14
Global Default Settings..................................................................................................15
Configuration Files.........................................................................................................17
Changing the Default Configuration Settings...........................................................................18
Configuring LDAP Authentication ............................................................................................18
Configuring the Notification Service.........................................................................................19
Configuring Logon Options......................................................................................................20
Configuring SCM Environment Settings...................................................................................21
Configuring ClearCase Settings....................................................................................21
Configuring Perforce Settings........................................................................................23
Configuring StarTeam Settings......................................................................................24
Configuring Subversion Settings...................................................................................26
Build Environment and Concepts.........................................................................28TeamInspector Projects............................................................................................................28
Inspectors.................................................................................................................................30
Proprietary and Standard Inspectors.............................................................................30
OpenInspectors.............................................................................................................31
Inspector Types..............................................................................................................31
Understanding the Build Process.............................................................................................33
Build Statuses..........................................................................................................................34
Build Types...............................................................................................................................36
Build Output ............................................................................................................................37
Artifacts.........................................................................................................................37
Build Logs......................................................................................................................39
Contents | 3
Build Numbers...............................................................................................................39
Job Log....................................................................................................................................39
Security Model.........................................................................................................................40
Working in the Dashboard.....................................................................................42Getting Started With the Dashboard........................................................................................42
Portfolio Page...........................................................................................................................43
Portfolio Summary Data................................................................................................43
Portfolio Detailed Views.................................................................................................44
Portfolio Context Menu Options.....................................................................................45
Builds Page..............................................................................................................................46
Customizing Your View..................................................................................................46
Build Summary View.....................................................................................................47
Build Details View..........................................................................................................48
Builds Page Menu Actions.............................................................................................49
Most Recent Builds View..........................................................................................................50
Monitoring Your Software Projects.......................................................................51Metrics Overview......................................................................................................................51
Monitoring Build Consistency...................................................................................................52
Monitoring for Release Readiness...........................................................................................53
Monitoring for Build Process Inefficiencies...............................................................................53
Monitoring Test and Code Coverage........................................................................................53
Diagnosing Error-Prone Builds.................................................................................................54
Managing Your Builds............................................................................................56Triggering a Build from the Portfolio.........................................................................................56
Aborting a build........................................................................................................................57
Retrieving Build Artifacts..........................................................................................................57
Rerunning an Earlier Build.......................................................................................................58
Subscribing to Email Notifications............................................................................................59
Event Notification Dialog Box...................................................................................................60
Viewing Build Results...............................................................................................................60
Linking to Build Execution Results in SCTM............................................................................61
Administering the Build Environment..................................................................63Build Administration..................................................................................................................63
Configuring Builds.........................................................................................................64
Running a build..............................................................................................................65
Schedule a Build............................................................................................................66
Specifying a Build Dependency.....................................................................................67
4 | Contents
Passing Dependent Build Artifacts................................................................................68
Disabling Builds for a Project.........................................................................................68
Using TeamInspector Build Numbers............................................................................69
Managing Build Artifacts................................................................................................70
Enabling Inspectors.......................................................................................................70
Getting Unit Test Results...............................................................................................71
Getting CheckStyle Results...........................................................................................72
Getting EMMA Results..................................................................................................73
Getting SCTM Test Results...........................................................................................74
Project Administration..............................................................................................................74
Projects..........................................................................................................................75
Streams.........................................................................................................................81
Modules.........................................................................................................................88
System Administration..............................................................................................................93
Changing the TeamInspector Admin Password.............................................................93
Restarting the TeamInspector Services.........................................................................93
TeamInspector Log Files...............................................................................................95
User Administration..................................................................................................................97
Setting Up Users...........................................................................................................97
User Dialog Box.............................................................................................................98
Changing a User's Role.................................................................................................98
Users Page....................................................................................................................99
Working with OpenInspectors................................................................................................100
Creating OpenInspectors.............................................................................................100
OpenInspector Dialog Box...........................................................................................112
Editing OpenInspectors...............................................................................................113
Deleting OpenInspectors.............................................................................................114
OpenInspectors Page..................................................................................................114
Troubleshooting...................................................................................................115Troubleshooting Build Failures...............................................................................................115
Troubleshooting Installation and Configuration .....................................................................119
Troubleshooting Failed Logon Attempts.................................................................................121
Troubleshooting OpenInspectors............................................................................................122
Resolving OpenInspectors Error Conditions..........................................................................123
TeamInspector Terminology................................................................................126
Contents | 5
Getting Started
Topics in this section contain the concepts that you need to get started using TeamInspector.
Related Topics
Introduction to TeamInspector on page 6
Tour of the User Interface on page 7
TeamInspector Setup Tasks on page 9
Continuous Integration on page 9
Logging On and Off on page 10
Contacting Technical Support on page 11
Introduction to TeamInspectorTeamInspector is a continuous integration build server that fits seemlessly into your build environment—andyour application life-cycle management (ALM) strategy—and encompasses the following features:
• Continuous integration – flexible continuous integration options allow for build on check-in, build on aschedule, build on a dependent project, and user-initiated builds.
• Build and test automation – continuously monitors and analyzes changes to the code base, automaticallyinitiating builds, test activities and code inspections for continuous integration projects, and reporting detailedresults.
• Data collection and aggregation – inspectors capture relevant build, test, and code analysis data in real-timesnapshots and as historical trend data. The data collected from the captured results provides valuableinsight into development initiatives and helps ensure that code change integration is successful.
• Project-level reporting – generates relevant metrics based on projects that combine module and streamcomponents that you define, making it easier to monitor build practices as you control the level of inspectiondata to report.
• Visualization of key development metrics – provides instant access to key development metrics through asecure Web-browser interface. The Dashboardpresents meaningful and measurable information thatmanagement or development teams can use to track code quality and development progress.
• Event notification – enables users to subscribe to build events and receive email or SMS notifications.• Open-source framework – the TeamInspector architecture is designed to support integration with a variety
of open-source and third-party tools and applications, allowing administrators to define OpenInspectors™.• Agile – supports release readiness initiatives in Agile development environments by allowing for frequent
and consistent build checks and easy deployment of build packages to test teams.
The following diagram shows the components that make up the TeamInspector environment and deliver resultsthrough TeamInspector Dashboard views.
6 | Getting Started
To use TeamInspector, an administrator using the administrator (tiadmin) account must set up the projectsthat create the build environment within TeamInspector.
Related Topics
Getting Started on page 6
Tour of the User InterfaceTeamInspector launches in a Web-browser.Through the navigation pane in the left frame of the TeamInspectorwindow, you access the following functional areas:
• Dashboard• Administration
Access to these areas is controlled by user privileges assigned to your TeamInspector role (Administrator orUser).
Getting Started | 7
User Interface Elements
The following table identifies various elements that you might encounter in TeamInspector.
Description or ExampleUI Element
Pages that you open from the navigation pane appear as tabbed views. These tabs stay openduring your session, enabling you to toggle the displays. Toggling between tabs refreshes the datadisplayed on a tab.
Tabs
Column menus are available in pages presented as tables, which enable you to control how datais displayed in the table for that page. The column menu is accessible by placing your mouse in a
Column Menus
column header and then clicking the arrow that appears at the far-right of the column header, asin the following image:
If you are on the Builds page, you can filter the list of builds by project from the column menu.
TeamInspector displays a maximum of 15 items per page when listing items. If a list contains morethan 15 items, use the navigational buttons or enter a page number to navigate the list.
Paging and Refresh
8 | Getting Started
Description or ExampleUI Element
The refresh button, , is available on most pages to refresh your views.
You can hide and show additional information or panes by clicking the expand button: .Expand button
Pages on the Dashboard have context menus that appear when you right click an item listed onthose pages.
Context menus
Related Topics
Getting Started on page 6
TeamInspector Setup TasksTo get started, a TeamInspector administrator must configure the TeamInspector environment. The useraccount tiadmin is provided to enable the initial setup.
The following tasks must be performed to set up the environment for TeamInspector users:
• Set up LDAP authentication for the TeamInspector users. This is required before any user can log on.• Set up the users and select their roles.The role grants access to either the Dashboard or both the Dashboard
and Administration functions.• Set up your TeamInspector projects. This is essential to defining your builds and setting up continuous
integration options in TeamInspector.• Configure the email notification service.Your Simple Mail Transport Protocol (SMTP) server information is
required to route notifications to users.• Configure the default settings, if needed, to make adjustments for your environment.• Configure the environment settings for the software configuration management (SCM) systems you plan
to use with TeamInspector.
After setup is complete, a user who is defined in TeamInspector can log on using his or her LDAP accountand access the Dashboard to view metrics and perform user tasks.
Related Topics
Getting Started on page 6
Continuous IntegrationTeamInspector provides a continuous integration environment in which you can consistently monitor softwarequality and build processes. Frequent check-ins result in frequent builds and continuous measurement andfeedback to maintain quality checks, when you specify continuous integration. TeamInspector uses the codestreams, build tools, and build actions that you define when you configure TeamInspector projects for yourenvironment to produce builds and provide metrics.
Continuous integration in TeamInspector incorporates the following concepts:
Getting Started | 9
• Build automation
• Test automation
• Build analysis
• Source code analysis
Build automation
TeamInspector automates build processes using the tools and source control (SCM) systems you specify foryour TeamInspector projects.You set up build automation by specifying the continuous integration options inyour projects. Builds in TeamInspector are run based on projects that define the code streams and associatedmodules used for a build.
TeamInspector uses the concept of modules to define the build configuration for buildable units. TeamInspectormonitors activity in the code streams to detect when changes are checked in. A change in the code streamtriggers a build of that project when triggered builds are enabled. For more information about modules andprojects, see the TeamInspector Projects topic.
Test automation
TeamInspector facilitates self-testing code environments by enabling the integration of unit tests into theautomated builds and reporting relevant metrics resulting from those tests. Test results and statistics fromexternal testing activities, such as performance and functional tests performed by quality assurance teamsusing the Micro Focus Silk testing products can also be displayed in the TeamInspector. This informationenables you to track tests associated with each build, and view trends. These tests results are implementedby enabling inspectors that register information about test tools in your environment.
Build analysis
TeamInspector collects data about builds, tests, and code changes, and reports the data in the TeamInspectorDashboard. The TeamInspector Dashboard displays reports, logs, and statistics associated with build andsoftware change activities. TeamInspector provides both real-time metrics and historical data, which enablesyou to view trends.When check-in triggered builds are enabled and a check-in occurs, TeamInspector analyzesthe change state of the code stream in the SCM repository and triggers a build, collecting data during the buildprocess and consolidating data from other processes that are configured to run as part of the build.
Source Code Analysis
TeamInspector provides inspectors that you can enable to render data in the Dashboard resulting from sourcecode analyzers running in your environment.When inspectors are implemented, these metrics provide a meansof continuously monitoring code segments for consistency and compliance. The source code inspectors canbe implemented to provide these measurements with or without running a build.
Related Topics
Getting Started on page 6
Logging On and OffTo log on, you must be a defined user in TeamInspector. When your TeamInspector user account has beenconfigured, you can access TeamInspector by using your organization credentials to log on.
A TeamInspector administrator must do the following to define your user account:
10 | Getting Started
• Verify your LDAP user credentials
• Add you as a user in TeamInspector using your LDAP user name
• Assign your authorization role
Note:
As a best practice, always log off TeamInspector when not using it for an extended period of time. ATeamInspector user session automatically times out after a set period of inactivity (2 hours), and the userlogged out of the session must log on again to continue using the product.
To log on and off
1. Launch the TeamInspector Dashboard by entering the URL address of your TeamInspector server in aWeb browser:
http://TeamInspector_server_hostname :9080/teaminspector/index.html
If the TeamInspector server is on the local host, enterhttp://localhost:9080/teaminspector/index.html
2. Type your logon name and password in the Username and Password fields, using your organizationcredentials.
3. If you want the computer to remember your logon credentials, check the Remember Me check box.
Note:
The length of time your logon credentials will be remembered are determined by the Remember meperiod configuration setting.Your client browser used to access TeamInspector must be set to acceptcookies to use the product.
4. Click Logon.
5. When you are ready to log off, click the Log out button in the top far right of the TeamInspector window.This action terminates your user session.
Related Topics
Getting Started on page 6
Contacting Technical SupportContact Micro Focus online at the Micro Focus Technical Support web site(http://www.supportline.microfocus.com)
Micro Focus provides a support knowledge base that is accessible from the Web site to anyone seeking supportinformation. Some content in the knowledge base is restricted to registered support customers only. Customerswho have a support and maintenance agreement with Micro Focus are automatically registered for the onlinetechnical support services. Login credentials are sent via email to registered customers when the supportcontract is started.
Registered customers can also open a technical support case and manage their cases online.
Getting Started | 11
http://www.supportline.microfocus.com
Related Topics
Getting Started on page 6
12 | Getting Started
Configuring TeamInspector
TeamInspector configuration involves setting up LDAP authentication for the TeamInspector users, and settingother configuration options as appropriate for your environment. Some configuration tasks are required beforeyou can use the product, as described in the TeamInspector setup tasks.
Other settings, such as the global default settings, may be adjusted to tune the TeamInspector operations foryour environment.
Related Topics
Configuration Settings on page 13
Changing the Default Configuration Settings on page 18
Configuring LDAP Authentication on page 18
Configuring the Notification Service on page 19
Configuring Logon Options on page 20
Configuring SCM Environment Settings on page 21
TeamInspector Setup Tasks on page 9
Configuration SettingsEach time TeamInspector starts, it uses configuration settings to initialize the working environment for thesession. These settings include global default settings that can be modified by a TeamInspector administratorto control how TeamInspector uses resources. These settings can be changed from the Configuration page.
For example, you can adjust timeout values and polling cycles to set limits more in line with your workingenvironment.You can also set the maximum number of concurrent builds and working copies available forbuilds appropriate to the capacity available in your environment.
TeamInspector also maintains the following configuration properties files that contain settings:configuration.properties and ticonfig.properties.
Note: Any changes to the configuration settings require a restart of the TeamInspector services.You canuse the cycleServices script to restart the services.You must run the script on all servers whereTeamInspector is installed, that is the job servers and the master server.
Related Topics
Configuring TeamInspector on page 13
LDAP Configuration Settings on page 14
Global Default Settings on page 15
Configuration Files on page 17
Configuring TeamInspector | 13
LDAP Configuration SettingsTeamInspector uses Lightweight Directory Access Protocol (LDAP) to authenticate users and contains theLDAP configuration settings in the configuration.properties file. This file is located in the /confdirectory of your TeamInspector installation home directory.
These settings are required to use TeamInspector. LDAP authentication must be set up before TeamInspectorusers can successfully log on. To configure these settings, edit the file and specify values as indicated in thefollowing table.
Some LDAP configuration settings have pre-set default values.You can use these default values, whereapplicable. Keep in mind that each LDAP setting must have a value.
Note: The configuration.properties file also contains the values set for the database server nameand port specified for the TeamInspector data store repository.
DescriptionDefault ValueItem Name
The server name (or address) that hosts theLDAP directory for your organization or
ldap_server_nameldap_server
workgroup that will be used to verifyTeamInspector users.
The port number used to connect to theLDAP server.
ldap_server_port_numberldap_port
The base distinguished name, specified inaccordance with your LDAP directorystructure.
dc=domainname,dc=domainorganizationname,dc=domaintypesuffixldap_base_dn
For example, specifying an Internet domainname using the domain componentattributes: dc=amer,dc=borl,dc=net
The LDAP distinguished name for theaccount used for binding to the LDAP serverto verify users. For example,
amer\\tiuser
domainname\\userldap_manager_dn
The password of the LDAP user accountused for binding to the LDAP server.
passwordldap_manager_password
The filter (or search string) to use to look upusers on the LDAP server.
(sAMAccountName={0})ldap_user_search_filter
A search filter used for searching WindowsActive Directory is provided as the default.
The maximum amount of time (inmilliseconds) that TeamInspector will expend
10000ldap_user_search_timeout_in_millis
to verify a logon account with the LDAPserver.
The default is 10000 milliseconds (10seconds)
14 | Configuring TeamInspector
DescriptionDefault ValueItem Name
If a logon fails, it typically indicates that theuser's account does not match his or herLDAP user name.
The maximum amount of time (inmilliseconds) that TeamInspector will wait
10000ldap_connect_timeout_in_millis
for the LDAP server to respond to aconnection request.
Related Topics
Configuration Settings on page 13
Global Default SettingsThe following default configuration settings are available from the Configuration page in TeamInspector.Thesesettings are inherited by all projects defined in TeamInspector. It may be necessary to adjust the values morethan once to get the desired results or to meet changing needs.
Note: The table groups the settings according to their relationship to functional elements; they may notappear in this order on the Configuration page.
DescriptionDefault ValueItem Name
Maximum number of seconds that TeamInspector waits for a build tocomplete before reporting a failure and logging an error.
60000Build timeout period (secs)
Maximum number of builds that can be executed at the same time.2Number of concurrent builds
Note: setting the value to zero (0) synchronizes the value with theNumber of working copies setting.
Maximum number of working copies available for builds.2Number of working copies
This value corresponds to the number of working copies you want tohave checked out at one time on the build server.
Name of the working copy base directory.WCWorking copy directory
You can change the name or indicate another path for the working copydirectory. When entering a path, use forward slashes. If usingbackslashes, the backslash character must be escaped with anotherbackslash character. For example either C:\\TI_WC or C:/TI_WCare acceptable:
Maximum number of files that can be checked out by TeamInspectorfrom the SCM server for build or inspection processing.
5000Max check out items fromSCM
Maximum number of days that build artifacts will be stored.0Retain artifacts (0–365 days)
A value of zero (0) specifies that artifacts will be stored indefinitely.
Configuring TeamInspector | 15
DescriptionDefault ValueItem Name
Maximum number of seconds in the polling cycle for TeamInspector tocheck the data repository for changes to projects
30Project monitor interval(secs)
Maximum number of seconds between each check for build requests60Build request polling interval(secs)
The period of time (maximum number of seconds) between checks ofthe SCM system for changes to the stream.
30SCM monitor interval (secs)
This setting determines the frequency of triggered builds, except forStarTeam streams. In that case, the SCM change wait periodvalue, if larger, is used instead.
If multiple projects are configured, this value might need to be increasedto allow all project streams to be checked during the polling cycle(depending on how long it takes to check each stream, and how manypolling threads are used). The SCM monitor interval does not affect theamount of time TeamInspector waits after a change before consideringthat change for a build for StarTeam streams.The SCM change waitperiod setting is provided for this purpose.
Maximum number of threads used during the SCM polling interval tomonitor the list of streams for changes.
4SCM monitor poll threads
This setting helps control the number of threads that TeamInspectorallocates to perform checks on the code streams. Using a higher valueallows more checks to be performed during each poll interval.
The period of time (maximum number of seconds) that TeamInspectorwaits after each detected change before considering that change forinclusion in a build.
60SCM change wait period(secs)
This setting is relative to build-on-checkin projects that use code streamson StarTeam systems.This setting determines the frequency of triggeredbuilds for StarTeam streams, when the value set is larger than thescm_poll_interval values.
The Simple Mail Transport Protocol (SMTP) server to use for processingTeamInspector mail notifications.
localhostSMTP server
The port number to use on the SMTP server25SMTP port
The user account on the SMTP server to use for connecting to the serverto process mail notifications from TeamInspector .
(none)SMTP user
The SMTP user account password to use to connect to the server.(none)SMTP password
The email address to use in the “from” line in the mail notice.(none)SMTP from email address
The number of days that the remember-me logon will be in effect.Whenthe value is set to zero (0), the remember-me check box will not beavailable to users.
5Remember me period (0-31days)
The name of the server on which the Job Service is installed.localhostDefault host for builds
16 | Configuring TeamInspector
DescriptionDefault ValueItem Name
If the Job Service is installed with the Master Services, the default setting(localhost) is used. If the Job Service is installed on a remote build server,TeamInspector automatically uses the host name of the computer onwhich the first Job Service is installed (successfully registered byTeamInspector) by default. If using an alias name or IP address for yourbuild server, you must specify it for the host name.
The port number used by the TeamInspector Job Service to connect tothe FTP service on the Master server.
21FTP port number
The number of days that the remote build server can remainunresponsive before being labeled inactive and no longer available foruse by TeamInspector.
7Retain inactive service(1–365 days)
Related Topics
Configuration Settings on page 13
Configuration FilesIn addition to the global default settings that TeamInspector makes available in the product interface, somesettings are provided in configuration files located in the conf directory of your installation.
• configuration.properties• env-settings.conf
You interact with these files during setup after installing TeamInspector. These files are not overwritten duringan upgrade installation of TeamInspector. The other files in the conf directory are for the exclusive use ofTeamInspector, and are not intended for user modification.
configuration.properties File
The configuration.properties file contains the LDAP configuration settings. These settings are usedto configure LDAP authentication and enable TeamInspector users to log on using their LDAP credentials.These settings are described in LDAP Configuration Settings.
This file also contains the database connection settings for the TeamInspector data-store repository that arespecified during installation.
env-settings.conf File
The env-settings.conf file contains the environment settings for supported SCM systems which must beconfigured before you can use those systems in TeamInspector builds.The env-settings.conf.defaultfile is also provided to assist upgrade users.
The settings are described in Configuring SCM Environment Settings.
Configuring TeamInspector | 17
Related Topics
Configuration Settings on page 13
Changing the Default Configuration SettingsYou can modify the default values for the configuration settings. Changing these values enables you to overridethe pre-set values TeamInspector uses to manage resources during TeamInspector operations.
For example, you can specify a different location and directory name for the working copies that TeamInspectorchecks out to perform builds and inspections.You may want to adjust the configuration values to more efficientlyalign productivity with the capacity available in your development environment. For example:
• Change the number of working copies available for builds, as well as the maximum number of concurrentbuilds.
• Change timeout values and polling intervals.• Manage storage of build artifacts.
Note: The pre-set values are available when you view the Configuration page. Some setup configurationsettings are maintained in the configuration.properties file, and you must edit that file to set thevalues.
1. In the navigation pane, expand Administration and click Configuration.
2. On the Configurations page, modify any of the default values as appropriate for your environment.
See Global Default Settings for a detailed description of each setting.
3. Click Update to save the settings
4. Restart the TeamInspector services using the cycleServices script provided.
Note: For additional information about restarting services, see Restarting the TeamInspector Services.
The changes are effective at the next logon.
Related Topics
Configuring TeamInspector on page 13
Global Default Settings on page 15
Global Default Settings on page 15
Restarting the TeamInspector Services on page 93
Configuring LDAP AuthenticationBefore you can set up users in TeamInspector, you must configure LDAP authentication for TeamInspector.The LDAP configuration parameters enable TeamInspector users to be validated against an LDAP directory.This provides a more convenient login scheme for users by allowing them to log on with their organizationcredentials.
TeamInspector uses a two-step approach to validate users:
18 | Configuring TeamInspector
• Authentication — first, checks a TeamInspector user against the LDAP listings to verify the user's identity• Authorization — if a user is validated during the authentication process, the user's account is confirmed;
then TeamInspector checks the user's role to determine what level of access the user has based on theirauthorization level (role).
To configure LDAP authentication
1. After installing TeamInspector, navigate to the /conf directory in the TeamInspector installation homedirectory.
2. Using a text editor, open the configuration.properties file.
Note: You must have write privileges on the file to modify it.
3. Locate the following entries in the file, and enter the appropriate values:
• ldap_server — enter the name or address of the LDAP server containing the user entries againstwhich your TeamInspector users will be validated
• ldap_port — enter the port number to use to connect to the LDAP server• ldap_server_dn — enter the base object in the distinguished name hierarchy, such as a domain
name• ldap_manager_dn — enter the LDAP user name to use for binding to the LDAP server• ldap_manager_password — enter the password for the LDAP user bind account• ldap_user_search_filter — enter the search string that will be used to locate user entries on the
LDAP server during authentication, or leave the default entry if applicable (if your are using an LDAPsystem that supports Windows Active Directory).
• ldap_user_search_timeout_in_millis — You can accept the default value of 10000 milliseconds(10 seconds) or enter a new value that is more appropriate for your environment.You must enter thevalue in milliseconds.
Note: Users in TeamInspector are set up using their LDAP user names.
4. Save the file in its original location (/conf directory) to preserve your settings.
5. Restart the TeamInspector services to apply the settings.
6. After the configuration has been completed, start the TeamInspector Dashboard and log on using theTeamInspector initial login account to set up users. For more information see Setting Up TeamInspectorUsers.
Related Topics
Configuring TeamInspector on page 13
LDAP Configuration Settings on page 14
Configuring the Notification ServiceTeamInspector users can subscribe to email and SMS notifications of build events. Before users can receivethe notifications, a TeamInspector administrator must configure the mail server information needed to routethe notifications.
Configuring TeamInspector | 19
TeamInspector supports Simple Mail Transport Protocol (SMTP) for delivery of the notifications. This topicdescribes how to specify the SMTP server information that TeamInspector needs to initialize the notificationservice.
To configure email notification
1. Log on to TeamInspector and open the Configuration page.
2. Navigate to the following configuration settings and update accordingly to set up the SMTP server connection:
• smtp_server — enter the server name or address of the SMTP mail server to use for mail notifications.If the SMTP server is running on the same server as TeamInspector, you can use the default value(localhost).
• smtp_port — enter the port number used for the SMTP services. The default value is 25.• smtp_user — enter the SMTP server user account to use to access the server, if required by the SMTP
server.• smtp_password — enter the SMTP user account password, if required.• smtp_from — enter the email address to use in the “from” field of the notification. This field is optional
unless required by your SMTP server configuration for mail notifications.
3. Click Update to save your settings.
4. Restart the TeamInspector services to apply the settings.
Note: Mobile phone carriers have varying requirements and behaviors for processing email or textmessages, and may rely on various methods (such as SMS gateways or direct exchange) for messagetransfer. Therefore, the reliability of TeamInspector notifications for users specifying SMS notification isdependent on the recipient's carrier. Users who have properly set up their email notifications but experienceproblems receiving SMS notifications might need to contact their providers for assistance.
Related Topics
Configuring TeamInspector on page 13
Configuring Logon OptionsTeamInspector provides automatic logon for users who choose the Remember Me option at logon. ATeamInspector administrator can configure the behavior of the Remember Me logon option by modifying theRemember me period configuration setting.
You have the following options when configuring this setting:
• Disable automatic logon so that the Remember Me option is not available to users.• Change the number of days for which TeamInspector will remember user credentials when users check
the Remember Me check box.
Note: The Remember Me option is enabled by default and set to 5 days.The Web browser used to accessthe TeamInspector server must be configured to accept cookies to use this option and the TeamInspectorfunctionality.
To modify the logon options
1. Log on to TeamInspector and open the Configuration page.
20 | Configuring TeamInspector
2. Navigate to the following setting:
Remember me period
3. Take one of the following actions:
• To disable automatic logons, set the value to zero (0).• To change the number of days for which automatic logons will be in effect, set a value from 1–31.
TeamInspector will remember user credentials for the number of days specified in this value for anyuser who checks the Remember Me check box.
4. Click Update to save your settings.
5. Restart the TeamInspector services to apply the settings.
Changing this setting does not affect a current user session. It will be applied to users at their next logonattempt.
Related Topics
Configuring TeamInspector on page 13
Configuring SCM Environment SettingsFor each software configuration management, or source control management, (SCM) system that you plan touse with TeamInspector, you must specify the environment settings in the TeamInspector configuration beforeyou can specify the SCM system in a stream.These settings enable access to the required SCM components.
TeamInspector provides the settings for all supported SCM systems in the env-settings.conf file that isinstalled with each new installation. For upgrade installations, the settings are provided in theenv-settings.conf.default file. To configure the settings, you must uncomment and edit the entries ineach section appropriate to the SCM systems that you plan to use.
For information about the supported SCM systems, see the TeamInspector Release Notes.
Related Topics
Configuring TeamInspector on page 13
Configuring ClearCase Settings on page 21
Configuring Perforce Settings on page 23
Configuring StarTeam Settings on page 24
Configuring Subversion Settings on page 26
Configuring ClearCase SettingsTo use a ClearCase software configuration management (SCM) system with TeamInspector, your environmentmust meet the following requirements:
Configuring TeamInspector | 21
• The ClearCase Remote Client must be installed on every system on which you have TeamInspector installedand intend to use to run builds or inspections with ClearCase.
• The jar files from the IBM TeamApi installation must be accessible to TeamInspector in the same locationon all systems. The jar files are included in a zip file in a standard ClearCase client installation. These filesmust be available on every server.
Use the following steps to configure the requirements for a ClearCase stream.
1. Make sure that you have the required JAR files extracted on the TeamInspector server or servers.
• If the required JAR files are already extracted to a directory, ensure that the directory includes all of thefiles listed in step 2, then go to step 3.
• If the required JAR files are not already extracted to some location on the system on which TeamInspectoris installed, create a directory under the base installation directory of TeamInspector and extract theJAR files from the IBM teamapi.zip file. For example, create the following directory in which to extractthe files:
external/SCMAPI/ClearCase
Note: The directory names in this example are not required; you can use any directory name thatyou feel is appropriate. However, the directory in which the JAR files reside must be the same onall the TeamInspector systems.
Continue to step 2.
2. In the directory you just created, extract the following JAR files from the contents of theplugins/com.ibm.rational.stp.teamapi directory in the teamapi.zip file.
• remote_core.jar• stpcc.jar• stpcmmn.jar• stpwcm.jar• commons-codec-1.3.jar (1.3 represents the version number which can be different depending on the
version of the TeamAPI SDK that you are using.)• commons-httpclient-3.0.jar (3.0 represents the version number which can be different depending on the
version of the TeamAPI SDK that you are using.)• commons-logging-1.0.4.jar (1.0.4 represents the version number which can be different depending on
the version of the TeamAPI SDK that you are using.)
3. Open the env-settings.conf file located in the conf directory of your TeamInspector installationdirectory and update the file by uncommenting the following entries listed in the ClearCase Section:
#set.CCWC_BASEDIR=## ClearCase Classpath##set.CCWC_CLASSPATH1=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%commons-logging-1.0.4.jar#set.CCWC_CLASSPATH2=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%commons-codec-1.3.jar#set.CCWC_CLASSPATH3=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%commons-httpclient-3.0.jar#set.CCWC_CLASSPATH4=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%remote_core.jar#set.CCWC_CLASSPATH5=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%stpcmmn.jar#set.CCWC_CLASSPATH6=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%stpwvcm.jar#set.CCWC_CLASSPATH7=%CCWC_BASEDIR%%WRAPPER_FILE_SEPARATOR%stpcc.jar#set.CCWC_CLASSPATH=%CCWC_CLASSPATH1%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH2%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH3%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH4%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH5%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH6%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH7%#
22 | Configuring TeamInspector
#set.EXT_CLASSPATH=%EXT_CLASSPATH%%WRAPPER_PATH_SEPARATOR%%CCWC_CLASSPATH%#
Note: To uncomment the entries, remove the # symbol from each line containing the set statements.If these entries do not exist in the env-settings.conf file, you must add them before you can useClearCase with TeamInspector.
4. After uncommenting these entries, edit the first line by replacing with the directory inwhich you placed the IBM TeamAPI JAR files as described in step 1, or with the fully qualified location ofyour existing JAR files if already extracted on the system.
5. Save and close the env-settings.conf file.
6. Restart all the TeamInspector services.You can use the cycleservices script to stop and restart theservices.You can now create and use streams that reference ClearCase repositories for your builds and inspections.
Related Topics
Configuring SCM Environment Settings on page 21
Specifying a ClearCase SCM System on page 82
Configuring Perforce SettingsTo use a Perforce software configuration management (SCM) system with TeamInspector, your environmentmust meet the following requirements:
• The Perforce Command Line Client (P4) application must be installed on every system on whichTeamInspector is installed that you plan to use for Perforce builds and inspections.
• TeamInspector must be able to access the P4 client through the system path.You can specify the path bysetting the environment variables in the env-settings.conf file, as described in this task.
• TeamInspector uses the P4Java 0.7.x APIs and requires that the P4Java JAR file is installed in the samelocation on every system on which TeamInspector is installed and that you plan to use for Perforce buildsand inspections.You can download the P4Java JAR file from the following Web site: http://tek42.com/p4java.If the required P4Java JAR file is not already installed in some location on your TeamInspector systems,create a directory under the base installation directory of TeamInspector in which to place the JAR file andthen install the JAR file. For example:
/external/SCMAPI/P4Java
Note: The directory names used in this example for the JAR file are suggested, but not required.Youcan use any directory you feel is appropriate, as long as the directory location is consistent on everyTeamInspector system.
• TeamInspector must be able to access the P4Java JAR file. To set the environment variables required,configure the settings in the env-settings.conf file, as described in this task.
1. Locate the env-settings.conf file in the conf directory of your TeamInspector installation and edit thefile as follows:
• Uncomment the following line by removing the # symbol, and then edit the statement by replacing/path/to/p4folder with the path to your P4 executable directory.
#
Configuring TeamInspector | 23
http://tek42.com/p4java
set.PATH=%WRAPPER_FILE_SEPARATOR%path%WRAPPER_FILE_SEPARATOR%to%WRAPPER_FILE_SEPARATOR%p4folder%WRAPPER_PATH_SEPARATOR%%PATH%
• Uncomment the following lines in the P4Java section of the env-settings.conf file, and follow theinstructions in that section of the file to set the paths.
#set.P4JAVA_BASEDIR=%TI_INSTALL_DIR%%WRAPPER_FILE_SEPARATOR%external%WRAPPER_FILE_SEPARATOR%SCMAPI%WRAPPER_FILE_SEPARATOR%P4Java####set.P4JAVA_CLASSPATH1=%P4JAVA_BASEDIR%%WRAPPER_FILE_SEPARATOR%p4java-0.7.5.jar#set.P4JAVA_CLASSPATH=%P4JAVA_CLASSPATH1%####set.EXT_CLASSPATH=%EXT_CLASSPATH%%WRAPPER_PATH_SEPARATOR%%P4JAVA_CLASSPATH%#
# End P4Java Section
In the set.P4JAVA_BASEDIR statement (the first line shown above), the TI_INSTALL_DIR variablerepresents the default TeamInspectorinstallation directory, which is set in the following statement nearthe top of the env-settings.conf file: set.TI_INSTALL_DIR=C:\ProgramFiles\Borland\TeamInspector.
If TeamInspector was installed using the default installation path, uncomment the line containing thisvariable. If TeamInspector was installed in a location other than the default installation path, then replacethe P4JAVA_BASEDIR path with the fully qualified path of the directory in which the P4Java JAR file isinstalled, if different than what is provided.
Ensure that you change the version reference if different than the version you have installed.
2. When you have completed the edits, save the file to the conf directory.
3. Restart the TeamInspector services by using the cycleservices command.
You can now specify a Perforce SCM system in a TeamInspector stream.
Related Topics
Configuring SCM Environment Settings on page 21
Specifying a Perforce SCM System on page 83
Configuring StarTeam SettingsTo use a StarTeam software configuration management (SCM) system with TeamInspector, your environmentmust meet the following requirements:
• The StarTeam SDK version 10.1 or later must in installed on all the TeamInspector systems that you planto use for builds with StarTeam streams. That is, the TeamInspector master server and each server thathas the TeamInspector job service installed requires the SDK for successful builds.
• The StarTeam SDK must be installed in the same location on all the TeamInspector systems and beaccessible to TeamInspector through the environment settings. To specify the required settings, see thefollowing section.
24 | Configuring TeamInspector
1. Locate the env-settings.conf file in the conf directory of your TeamInspector installation and edit thefile as follows:
• Uncommment the lines in the StarTeam section of the env-settings.conf file, as shown in thefollowing example.
#StarTeam Section#set.ST_BASEDIR=C:\Program Files\Borland\StarTeam SDK 10.1set.ST_BASELIBDIR=%ST_BASEDIR%%WRAPPER_FILE_SEPARATOR%libset.ST_BASEBINDIR=%ST_BASEDIR%%WRAPPER_FILE_SEPARATOR%bin## StarTeam Classpath## In the first three lines of the following classpath entries, replace the# version reference (100) in the name of the starteam jar files with the correct# version for your installation.#set.ST_CLASSPATH1=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%starteam101.jarset.ST_CLASSPATH2=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%starteam101_win32.jarset.ST_CLASSPATH3=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%starteam101-resources.jar#set.ST_CLASSPATH4=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%ss.jarset.ST_CLASSPATH5=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%swingall.jarset.ST_CLASSPATH=%ST_CLASSPATH1%%WRAPPER_PATH_SEPARATOR%%ST_CLASSPATH2%%WRAPPER_PATH_SEPARATOR%%ST_CLASSPATH3%%WRAPPER_PATH_SEPARATOR%%ST_CLASSPATH4%%WRAPPER_PATH_SEPARATOR%%ST_CLASSPATH5%## The following EXT_CLASSPATH entry sets EXT_CLASSPATH value to include the# current values along with the classpath values specific to StarTeam.#set.EXT_CLASSPATH=%EXT_CLASSPATH%%WRAPPER_PATH_SEPARATOR%%ST_CLASSPATH%## StarTeam Library path#set.ST_LIBPATH1=%ST_BASEBINDIR%set.ST_LIBPATH2=%ST_BASELIBDIR%#set.ST_LIBPATH=%ST_LIBPATH1%%WRAPPER_PATH_SEPARATOR%%ST_LIBPATH2%## The following EXT_LIBPATH entry sets the EXT_LIBPATH value to include the# current values along with the libpath values specific to StarTeam.#set.EXT_LIBPATH=%EXT_LIBPATH%%WRAPPER_PATH_SEPARATOR%%ST_LIBPATH%## End StarTeam Section
Note: If these settings are not in your env-settings.conf file—for example, if you are upgradingyour installation—you can add them by copying them from the env-settings.conf.defaultfile that is provided with an installation.
• In the first line of these entries, replace the path in the set.ST_BASEDIR statement with the fully qualifiedpath of the directory in which you installed the StarTeam SDK, if it is different than what is provided.
• Modify the version number referenced in the set statements if different than what is provided.
2. When you have completed the edits, save the file to the conf directory.
3. Restart the TeamInspector services by using the cycleservices command.
You are now ready to specify a StarTeam stream in your TeamInspector projects.
Configuring TeamInspector | 25
Related Topics
Configuring SCM Environment Settings on page 21
Specifying a StarTeam SCM System on page 83
Configuring Subversion SettingsTo use a Subversion (SVN) source control management (SCM) system with TeamInspector, your environmentmust meet the following requirements:
• The SVNKit JAR files must be installed on every system on which TeamInspector is installed that you planto use for Subversion builds and inspections.You can download the SVNKit JAR files fromhttp://svnkit.com/download.php.
• TeamInspector requires environment settings in the env-settings.conf file to enable access to theSVNKit binaries. Use the following steps to configure these settings.
1. Locate the env-settings.conf file in the conf directory of your TeamInspector installation and edit thefile as follows:
• Uncommment the following lines in the SVNKit section of the env-settings.conf file, as shown inthe following example.
#set.SVNKIT_BASEDIR=%TI_INSTALL_DIR%%WRAPPER_FILE_SEPARATOR%external%WRAPPER_FILE_SEPARATOR%SCMAPI%WRAPPER_FILE_SEPARATOR%SVNKit## SVNKit Classpath#set.SVNKIT_CLASSPATH1=%SVNKIT_BASEDIR%%WRAPPER_FILE_SEPARATOR%svnkit.jarset.SVNKIT_CLASSPATH=%SVNKIT_CLASSPATH1%## The following EXT_CLASSPATH entry sets EXT_CLASSPATH value to include the# current values along with the classpath values specific to SVNKit.#set.EXT_CLASSPATH=%EXT_CLASSPATH%%WRAPPER_PATH_SEPARATOR%%SVNKIT_CLASSPATH%## End SVNKit Section#
• In the first line of these entries, replace the SVNKIT_BASEDIR location with the fully qualified path ofthe directory in which you extracted the JAR files from the downloaded SVNKit zip file, if it is differentthan what is provided.
Note: The TI_INSTALL_DIR variable in this line is set in the following statement near the top ofthe env-settings.conf file. If you use the default value that is provided, make sure the linecontaining this variable is uncommented in the file.
set.TI_INSTALL_DIR=C:\Program Files\Borland\TeamInspector
2. When you have completed the edits, save the file to the conf directory.
3. Restart the TeamInspector services by using the cycleservices command.
26 | Configuring TeamInspector
http://svnkit.com/download.php
Related Topics
Configuring SCM Environment Settings on page 21
Specifying a Subversion SCM System on page 85
Configuring TeamInspector | 27
Build Environment and Concepts
TeamInspector incorporates several objects that are the building blocks for defining your TeamInspector buildenvironment and configuring continuous integration. These objects are projects, streams, modules, andinspectors.
After you have set up these objects to define your build environment, you can begin producing builds andgetting inspection results in TeamInspector. See the Getting Started topics for more information about settingup your environment.
Related Topics
TeamInspector Projects on page 28
Inspectors on page 30
Understanding the Build Process on page 33
Build Statuses on page 34
Build Types on page 36
Build Output on page 37
Job Log on page 39
Security Model on page 40
TeamInspector ProjectsProjects are essential to defining the build execution and inspection processes that produce results inTeamInspector. These results are distribution artifacts, build analysis data, and code inspection data that areused to monitor and measure the quality of build processes and software code.You must have at least oneproject defined before you can process builds and generate metrics in TeamInspector.
A project is a named entity that you create by associating it with the following objects:
• Streams
• Modules
Note: Streams, modules, and projects are each defined independently in TeamInspector.
Streams
A stream specifies the source code repository that TeamInspector monitors for changes and checks out fromfor builds and inspections. The mapping information you enter for a stream varies depending on the softwareconfigurtion management (SCM) system that you select to use for the stream. A stream might specify a directorypath, a view, or a workspace (in the case of Perforce). All streams require connection information to the SCMhost.
You can map only a single repository in a stream. However, a stream can be assigned to more than one project.
28 | Build Environment and Concepts
Note: Before you can specify an SCM system in a stream, the SCM system settings must be configuredin the TeamInspector env-settings.conf file. For more informtion about this requirement, see theInstallation Notes.
Modules
A module specifies the build tool, build files, and the location of those files, as well as the test and analyzertools, that you intend to use for your TeamInspector builds. TeamInspector uses the module definition todetermine the build instructions, build resources, and build output for a project build.
If an attribute in the module definition is not provided and TeamInspector defaults are specified for the attribute,TeamInspector uses the default. If no defaults are specified, TeamInspector defaults to the attributes specifiedin the build tool, if available.
Example
If you are using an Ant build tool, for the module definition specify the build path, the build file name (forexample, build.xml), and the build target for builds that you want to run for a specific project. The build pathis relative to the root level of the SCM system with which you are working. If you enter an invalid path orfilename, TeamInspector allows the creation of the module definition. However, note that an invalid moduleassociated with a project will render the project invalid for builds.
If you are using a command-line builder, TeamInspector allows you to enter the command-line executablesand arguments to pass to the builder.
Considerations for Creating Projects
Think of a project as the definition of a reporting unit or a buildable unit in TeamInspector. To create a project,you must have a stream and module defined. No specific sequence is required for creating a stream and amodule, but both must exist before you can create a project.
Projects have the following characteristics or conventions to consider when creating a project:
• Projects are not seen or used by the source control system. They are used by TeamInspector to processbuild requests and inspections and analyze the results.
• Each project name, stream name, and module name must be unique within TeamInspector. The names ofthese objects are treated as case-sensitive.
• A project defines a single buildable unit. If you intend to produce builds with different outputs, you mustcreate a project for each variation of output.
• A project must be valid at the time an action is invoked on the project, or the action will fail.• If you want a project that produces inspection results from unit tests or code analyzers, you must enable
the appropriate inspectors in the module associated with the project.• If no Continuous Integration Configuration options are enabled for a project, no build or inspection results
are provided.• A project dependency can be specified in a project definition. A project with a project dependency specified
will build each time the dependent project successfully builds.
Build Environment and Concepts | 29
Related Topics
Build Environment and Concepts on page 28
InspectorsAn inspector is a TeamInspector extension that analyzes data output from a development tool, such as a testor code analysis tool, and transforms the data into comprehensive metrics that you can review in theTeamInspector Dashboard.These metrics enable users to monitor code quality and compliance, build statuses,and other statistics associated with a project, to determine release readiness.
TeamInspector supports an open inspector concept. In addition to providing a set of inspectors for somestandard and proprietary tools, TeamInspector's OpenInspector™ framework enables TeamInspectoradministrators to create inspectors to generate metrics from any test or code analysis tool running in your buildenvironment. An OpenInspector defines a transformation stylesheet that converts the XML output of the toolinto data used by TeamInspector to produce the metrics.
TeamInspector classifies inspectors into basic types based on the type of analyzer tool and the data type ofthe output file. These types are discussed in a related topic.
An analyzer tool, such as JUnit or Checkstyle might be configured in your environment to run as part of thebuild process. This is a common scenario. Or, the tool might run independently of the build process. To usethe inspectors to produce metrics in TeamInspector, you must configure your analyzer (or test) tools to runwithin your build process.
Note: You must have the analyzer tool associated with an inspector installed and available in yourenvironment before TeamInspector will generate any data from that tool.
Using Inspectors
To use inspectors and configure the metrics that you want to monitor for a TeamInspector project, you mustenable the inspectors in a module. After inspectors are configured and enabled in a module, an inspection ofany project that uses the module will generate the inspection analysis data to the Portfolio Dashboard. Onlya TeamInspector administrator can enable inspectors.
Related Topics
Build Environment and Concepts on page 28
Proprietary and Standard Inspectors on page 30
OpenInspectors on page 31
Inspector Types on page 31
Proprietary and Standard InspectorsTeamInspector provides a set of pre-defined inspectors for some commonly used tools which can readily beenabled in a module to generate metrics from those tools, if the tools are configured to produce results in yourdevelopment environment. These inspectors are maintained and provided as a standard set of inspectors toprovide metrics for each type of inspection that is supported in TeamInspector.
TeamInspector also provides a proprietary inspector that is available to enable integration with SilkCentralTest Manager (SCTM).
30 | Build Environment and Concepts
The standard inspectors include the following inspectors:
• JUnit• NUnit• CheckStyle• EMMA
TeamInspector also provides the OpenInspector extensions which enable user-defined inspectors to be createdand used to produce results for tools that are not pre-defined in TeamInspector. An extension is provided foreach of the inspector types supported. For more information, see OpenInspectors.
SCTM Inspector
If you have SilkCentral Test Manager integrated in your development environment, you can enable this inspectorto get results for an execution definition in SCTM from within the TeamInspector Dashboard. When enabled,a link to the execution results is available from the context menu on the Portfolio page. Right-click the projecton the main view of the Portfolio page to access the link.
Related Topics
Inspectors on page 30
OpenInspectorsTeamInspector's OpenInspector™ framework enables you to create inspectors to generate metrics from theresults of unit test tools, code analyzer, or code coverage tools running in your environment.
To create an OpenInspector, you must create the XSL content that TeamInspector uses to transform the toolresults into the metrics that display in the Dashboard. The XSLT content for an OpenInspector must identifya unit test, or an analysis report, and include a call back into TeamInspector, specifying the results generatedin the test output or analysis report. The content must be constructed using the XML schema elementsspecifically required to transfrom the data from your tool. The output of the tool must be in XML format.
A TeamInspector user with administrator privileges can create OpenInspectors. An understanding of ExtensibleStylesheet Language and XSL transformations (XSLT) is required to define the content for an OpenInspector.The content may be created in a file or XSL editor and then copied and pasted into the OpenInspector dialogbox. TeamInspector does not provide an XML-compliant editor in which to create the content.
Related Topics
Inspectors on page 30
Inspector TypesTeamInspector inspectors are categorized into types.The inspector type is based on the type of tool producingthe data output and the data type of the output. Currently, only the XML data type is supported as output froma test or analyzer tool. When you create an inspector (referred to as an OpenInspector), you must specify thetype. The data categories displayed in the Portfolio correspond to these types.
TeamInspector classifies inspectors as one of the following types:
• Unit Test inspectors• Code Analysis inspectors• Code Coverage inspectors
Build Environment and Concepts | 31
Note: TeamInspector also provides the SCTM inspector to enable integration with SilkCentral TestManager (SCTM).
Unit Test Inspectors
Unit test inspectors are build-associated inspectors that run after the build executable has completed processing.This means that your build scripts must include tasks that run the tests and produce the output in a file formatsupported by the inspector for that tool. TeamInspector requires the output format to be XML. A unit testinspector can be a standard inspector provided by TeamInspector, JUnit or NUnit, or a user-definedOpenInspector created for the tool that you are using in your testing framework.
A TeamInspector unit test inspector generates the following build metrics:
• number of unit tests that ran• number of successful tests and percentage of tests overall that succeeded• number of failed tests and percentage of tests overall that failed
Code Coverage Inspectors
Code coverage inspectors generate results from tools that analyze the volume of code that is covered by unittests in your development environment. TeamInspector provides an inspector for the Java code-coverage tool,EMMA.You can create a code-coverage OpenInspector to generate results from any code-analysis tool runningin your environment that produces output to an XML file.
A TeamInspector code coverage inspector generates the following build metrics:
• Class – the percentage of classes in the code that were exercised or covered by your testing framework.• Method – the percentage of methods in the code that were exercised or covered by tests.• Block – the percentage of basic blocks in the code that were exercised or covered by tests.• Line – the percentage of lines in the code that were exercised or covered by tests.
Code Analysis Inspectors
Code-analysis inspectors generate metrics resulting from code analysis tools, such as CheckStyle that checksfor code style compliance. TeamInspector provides a CheckStyle inspector.You can create a code-analysisOpenInspector to generate results from any code-analysis tool running in your environment that producesoutput to an XML file.
A TeamInspector code coverage inspector generates the following build metrics:
• number of files processed• number of errors, warnings, or informational messages produced during the code compile process• number of errors per file
Note: If you enable package documentation in your CheckStyle implementation, or configure any itemthat will create a file element in the CheckStyle report that is not a Java source file, it can result in extrafiles that show up in the file count. Therefore, if you have any error in the source file, the Code Coveragepercentage displayed in the Portfolio will not be accurate.
SCTM Inspector
TeamInspector also provides the SCTM inspector to enable integration with SilkCentral Test Manager (SCTM).You can enable this inspector to get results for an execution definition in SCTM. When enabled, a link to theexecution results is available from the context menu on the Portfolio page. Right-click the project on the mainview of the Portfolio page to access the link.
32 | Build Environment and Concepts
Related Topics
Inspectors on page 30
Understanding the Build ProcessAll TeamInspector builds are based on projects.You can define a project to be built manually or automatically,based on the continuous integration options that you choose for the project. In either case, the build processis the same.
TeamInspector Build Actions
When a build is invoked in TeamInspector, the request is processed in a series of events that occur in variousstages. TeamInspector reports status in relation to each stage. Basically, TeamInspector processes a buildrequest through the following stages:
• Initialization – In this stage, TeamInspector is preparing to build by creating a job to process the buildrequest, retrieving build records, checking out (or updating) a working copy of the source files, and submittingthe job to the build queue. When this stage has completed successfully, TeamInspector transitions to theBuild Started state.
• Build – In this stage, TeamInspector runs the build tool or build executable, collects build results, and logsany exceptions to the build log.
• Post-build – During this stage TeamInspector runs any inspectors, such as unit tests or code analyzers,that are defined for the project and stores artifacts if specified for the project.
Note: Additional statuses are associated with each of these stages, and are reported on the Builds pageduring processing. For more information about these statuses, see Build Statuses.
A build is successful when the build output meets all criteria defined by the build file or build script and thebuild return code indicates build success. The post-build processes are successful when analyzer tools areavailable and run successfully to produce results. If you have specified the Artifact Location for build output inthe module defined for the project, TeamInspector stores the build artifacts for distribution during the post-build,or cleanup, phase.
TeamInspector does not promote any build output to your source control system.
Note: If you experience unexplained build failures, see Troubleshooting Builds for information that mighthelp you resolve the issues.
Multiple Concurrent Builds
TeamInspector is configured to execute a maximum of two builds at the same time.You can change the numberof builds that run concurrently by modifying the Number of concurrent builds configuration setting.
A correlation exists between the Number of concurrent builds setting and another configuration setting:Number of working copies. By default these two settings have the same value (2). Adjusting the valueof one might require adjustments to the other, depending on your environment.You can maintain thesynchronization of these two values by setting the Number of concurrent builds value to zero (0) andadjusting the Number of working copies value as needed.
Note: If you are using a Perforce SCM system, consider how multiple concurrent builds of your projectsusing Perforce might be restricted by the number of Workspaces allowed by your Perforce license.TeamInspector uses a Perforce Workspace each time it checks out source code by creating a temporaryworkspace in the depot. If the number of workspaces created exceeds the number allowed by your Perforce
Build Environment and Concepts | 33
license, TeamInspector is unable to check out the source files and returns an error preventing the buildfrom starting.
Remote Builds
TeamInspector runs builds on a remote build server when the TeamInspector job service is installed on thebuild server and a project is configured that specifies the build server host on which the builds will run.
When remote builds are configured, TeamInspector checks out the source code to the working copy on thebuild server, runs the build and inspection processes, and provides output to the master server. This output(build results and build artifacts) is provided through the TeamInspector Dashboard. However, the build logfor a remote build is not available in the Dashboard until the build process has completed. Likewise, buildartifacts are not available until the build process has completed.
Only one build server can be specified per project. For more information about specifying the remote buildserver, see Creating a Project.
Dependent Builds
TeamInspector enables you to specify a dependent project in a project definition. When a dependent projectis specified, the project for which the dependency is specified builds any time the dependent project successfullybuilds. When a project is built by being triggered by a dependent project, the build results will show the typeas Triggered-dependency.
Working Copies
TeamInspector maintains a working copy for builds in the TeamInspector working copy directory. It updatesthe working copy with current files when a build request is queued. The default location for the working copydirectory is TEAM_INSPECTOR_HOME/WC. By default, TeamInspector allows two working copies to existin the working copy directory, labeled as WC0 and WC1.
You can change the number of working copies to use for builds by adjusting the configuration setting Numberof working copies. This value determines the number of working copies available for jobs sitting on thebuild queue. TeamInspector uses the next available working copy to process a build request when multiplerequests requiring the same build criteria are queued. If you are using remote build servers, the number ofworking copies maintained applies to each server.
Note: Both the processing capacity and disk space capacity must be taken into account when adjustingthese values. For more information about the concurrent build setting and the working copy setting, seethe TeamInspector Configuration Settings topic.
Related Topics
Build Environment and Concepts on page 28
Build StatusesTeamInspector displays various build statuses on the Builds page that indicate the current state or finaloutcome of the build process. The Portfolio views show only the success or failure of a build.
The following table lists the build statuses that TeamInspector reports during the build process.
34 | Build Environment and Concepts
DescriptionStatus
TeamInspector has started the initialization phase and is creating a job to process the build request.Setup
TeamInspector has determined the revision of code to be built and the build is ready to be queued.Pending
The job has been queued and is ready to start.Queued
The job has started, and TeamInspector is checking out the code and build resources.Initializing
One of the processes in the initialization phase failed and the job has terminated.Initialization Error
Initialization completed successfully and TeamInspector is ready to start the build execution.Build Pending
The build has started.Build Started
TeamInspector was unable to start the build process, at which point the job terminated.Build Error
The build completed successfully.Build Successful
The build completed, but reported a failed status.Build Failed
The build completed with either a successful or failed build state, and TeamInspector is running theinspectors.
Analyzing
All build and inspection processes are complete and TeamInspector is in the final step of the process.This is the phase in which TeamInspector preserves the artifacts.
Cleaning Up
All processes started by this job are complete, and the build returned a successful status.Successful
All processes started by this job are complete, but the build returned a failed status.Failed
The build completed successfully, or with a failed status, but TeamInspector encountered errors whenattempting to run the inspectors or attempting to store the artifacts and terminated the job.
Post-Build Error
The build process has been successfully aborted.Build Aborted
If the abort process is in progress TeamInspector displays the current build status with (aborted)appended in the status column to indicate at which state the build was aborted.
Related Topics
Build Environment and Concepts on page 28
Build Summary View on page 47
Build Types on page 36
Build Environment and Concepts | 35
Build TypesTeamInspector supports the continuous integration concept.That is, builds in TeamInspector can be configuredto occur automatically based on changes in checked-in code, build dependencies, or at scheduled intervals.All build executions are based on the projects that you define.
You have the following build options for a project:
• Check-in triggered builds• Dependency-triggered builds• Scheduled builds• Manual (user-initiated) builds
Note: Manual builds for users are enabled by default when a project is created. To restrict manual buildsfor users, uncheck this option in the project definition.
Check-In-Triggered Builds
A check-in triggered build occurs when code is checked in to the SCM repository and TeamInspector sees thechanged files in the stream it is monitoring. TeamInspector continually polls the SCM repository and monitorsstreams for changes. When changes are detected, a build is automatically triggered. This type of build isreported as Triggered: Checkin in the Dashboard
Automation always starts with a working copy on the server, at the revision or version that triggered the build.TeamInspector retrieves a working copy of the repository stream containing the changed files and invokes thebuild process. TeamInspector maintains a working copy for builds that is always synchronized with the currentcode stream when a build is initiated.You can configure multiple working copies for your environment. Seethe Configuration Settings topic for more details about the setting.
The build process may include unit tests and other activities based on the build configuration identified for theproject. For example, code analysis tools may be integrated into your TeamInspector build configuration.
Dependency-Triggered Builds
TeamInspector supports build dependencies by enabling you to specify a dependent project in a projectdefinition. When a dependent project is specified, the project for which you specified the dependency will buildany time the dependent project is built. TeamInspector reports the build Type as: Triggered: Dependency.
A project can have only one dependent project; however, multiple projects can have a dependency on thesame project.
Scheduled Builds
You can schedule a build to occur independent of a check-in. The TeamInspector scheduler enables you toset up recurring builds at scheduled times to run for a project. Builds are scheduled on hourly increments. Forexample, if you intend to run builds twice daily, once in the morning and again in the afternoon, you canschedule the hourly interval for 8 hours, and specify the start time for 8:00 A.M. Using this scenario, the buildswill run at 8:00 a.m. and 4:00 p.m.
Scheduled builds are useful when:
36 | Build Environment and Concepts
• You want periodic builds, such as nightly or hourly runs.• You want to run an alternate target. That target can direct your build file to do something different, such as
run a long regression test suite.You can define projects for your scheduled builds to specify the customizedtargets and code streams for the builds.
TeamInspector reports the build Type as Scheduled in the Dashboard
Manual Builds
All users can manually trigger builds for a project, when the Manual builds for users option is enabled forthe project. Ad hoc builds provide flexibility and more control in managing build executions. For example, buildengineers may want to test build processes and view the TeamInspector results, or software engineers mightneed the ability to run a build in between scheduled builds to build and test their code. Users viewing metricsin the Portfolio views may want to trigger a build and monitor the results or access the build output.
Builds can be initiated by TeamInspector users from the summary view of the Portfolio page. TeamInspectoradministrators can also initiate builds from the Projects page.
This type of build is reported as Manual in the Dashboard.
Related Topics
Build Environment and Concepts on page 28
Build Summary View on page 47
Build Statuses on page 34
Build OutputA TeamInspector build produces output that is not under source control. The output is generated in theTeamInspector working copy during a build. The output is the result of what is specified in the build file usedby the project. If you want to use this output, TeamInspector makes it available for download through theDashboard. That is, TeamInspector provides access to the build output stored in the directory that you specifyas the Artifacts Location. See more about the Artifacts Location when you view the Artifacts topic.
A build typically produces the following types of output:
Related Topics
Build Environment and Concepts on page 28
Artifacts on page 37
Build Logs on page 39
Build Numbers on page 39
ArtifactsAn artifact is a file, or a set of files, that your build produces as the result of executing build tasks. For example,the artifacts generated as output might include object files, test output, and installation packages.
Build Environment and Concepts