StarTeam 12.0 TeamInspector Help Micro Focus 575 Anton Blvd., Suite 510 Costa Mesa, CA 92626
Copyright © Micro Focus IP Development Limited . All Rights Reserved. contains derivative works of Borland Software Corporation, Copyright © Borland Software Corporation (a Micro Focus company) 1998-2011.
MICRO FOCUS and the Micro Focus logo, among others, are trademarks or registered trademarks of Micro Focus IP Development Limited or its subsidiaries or affiliated companies in the United States, United Kingdom and other countries.
BORLAND, the Borland logo and are trademarks or registered trademarks of Borland Software Corporation or its subsidiaries or affiliated companies in the United States, United Kingdom and other countries.
All other marks are the property of their respective owners.
ii Contents
Getting Started...... 6 Introduction 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...... 13 Configuration 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...... 28 TeamInspector 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...... 42 Getting 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...... 51 Metrics 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...... 56 Triggering 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...... 63 Build 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...... 115 Troubleshooting 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 TeamInspector
TeamInspector is a continuous integration build server that fits seemlessly into your build environment—and your 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 a schedule, build on a dependent project, and user-initiated builds. • Build and test automation – continuously monitors and analyzes changes to the code base, automatically initiating builds, test activities and code inspections for continuous integration projects, and reporting detailed results. • Data collection and aggregation – inspectors capture relevant build, test, and code analysis data in real-time snapshots and as historical trend data. The data collected from the captured results provides valuable insight 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 stream components that you define, making it easier to monitor build practices as you control the level of inspection data to report. • Visualization of key development metrics – provides instant access to key development metrics through a secure Web-browser interface. The Dashboardpresents meaningful and measurable information that management 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 results through TeamInspector Dashboard views.
6 | Getting Started To use TeamInspector, an administrator using the administrator (tiadmin) account must set up the projects that create the build environment within TeamInspector.
Related Topics
Getting Started on page 6
Tour of the User Interface
TeamInspector launches in a Web-browser.Through the navigation pane in the left frame of the TeamInspector window, you access the following functional areas: • Dashboard • Administration Access to these areas is controlled by user privileges assigned to your TeamInspector role (Administrator or User).
Getting Started | 7 User Interface Elements The following table identifies various elements that you might encounter in TeamInspector.
UI Element Description or Example
Tabs Pages that you open from the navigation pane appear as tabbed views. These tabs stay open during your session, enabling you to toggle the displays. Toggling between tabs refreshes the data displayed on a tab.
Column Menus Column menus are available in pages presented as tables, which enable you to control how data is displayed in the table for that page. The column menu is accessible by placing your mouse in a column header and then clicking the arrow that appears at the far-right of the column header, as in the following image:
If you are on the Builds page, you can filter the list of builds by project from the column menu.
Paging and Refresh TeamInspector displays a maximum of 15 items per page when listing items. If a list contains more than 15 items, use the navigational buttons or enter a page number to navigate the list.
8 | Getting Started UI Element Description or Example
The refresh button, , is available on most pages to refresh your views.
Expand button You can hide and show additional information or panes by clicking the expand button: .
Context menus Pages on the Dashboard have context menus that appear when you right click an item listed on those pages.
Related Topics
Getting Started on page 6
TeamInspector Setup Tasks
To get started, a TeamInspector administrator must configure the TeamInspector environment. The user account 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 account and access the Dashboard to view metrics and perform user tasks.
Related Topics
Getting Started on page 6
Continuous Integration
TeamInspector provides a continuous integration environment in which you can consistently monitor software quality and build processes. Frequent check-ins result in frequent builds and continuous measurement and feedback to maintain quality checks, when you specify continuous integration. TeamInspector uses the code streams, build tools, and build actions that you define when you configure TeamInspector projects for your environment 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 for your TeamInspector projects.You set up build automation by specifying the continuous integration options in your projects. Builds in TeamInspector are run based on projects that define the code streams and associated modules used for a build. TeamInspector uses the concept of modules to define the build configuration for buildable units. TeamInspector monitors activity in the code streams to detect when changes are checked in. A change in the code stream triggers a build of that project when triggered builds are enabled. For more information about modules and projects, see the TeamInspector Projects topic.
Test automation TeamInspector facilitates self-testing code environments by enabling the integration of unit tests into the automated builds and reporting relevant metrics resulting from those tests. Test results and statistics from external testing activities, such as performance and functional tests performed by quality assurance teams using the Micro Focus Silk testing products can also be displayed in the TeamInspector. This information enables you to track tests associated with each build, and view trends. These tests results are implemented by 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 TeamInspector Dashboard. The TeamInspector Dashboard displays reports, logs, and statistics associated with build and software change activities. TeamInspector provides both real-time metrics and historical data, which enables you to view trends.When check-in triggered builds are enabled and a check-in occurs, TeamInspector analyzes the change state of the code stream in the SCM repository and triggers a build, collecting data during the build process 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 source code analyzers running in your environment.When inspectors are implemented, these metrics provide a means of continuously monitoring code segments for consistency and compliance. The source code inspectors can be implemented to provide these measurements with or without running a build.
Related Topics
Getting Started on page 6
Logging On and Off
To log on, you must be a defined user in TeamInspector. When your TeamInspector user account has been configured, 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. A TeamInspector user session automatically times out after a set period of inactivity (2 hours), and the user logged 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 a Web browser: http://TeamInspector_server_hostname :9080/teaminspector/index.html If the TeamInspector server is on the local host, enter http://localhost:9080/teaminspector/index.html 2. Type your logon name and password in the Username and Password fields, using your organization credentials. 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 me period configuration setting.Your client browser used to access TeamInspector must be set to accept cookies 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 Support
Contact 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 support information. Some content in the knowledge base is restricted to registered support customers only. Customers who have a support and maintenance agreement with Micro Focus are automatically registered for the online technical support services. Login credentials are sent via email to registered customers when the support contract is started. Registered customers can also open a technical support case and manage their cases online.
Getting Started | 11 Related Topics
Getting Started on page 6
12 | Getting Started Configuring TeamInspector
TeamInspector configuration involves setting up LDAP authentication for the TeamInspector users, and setting other configuration options as appropriate for your environment. Some configuration tasks are required before you 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 for your 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 Settings
Each time TeamInspector starts, it uses configuration settings to initialize the working environment for the session. These settings include global default settings that can be modified by a TeamInspector administrator to 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 working environment.You can also set the maximum number of concurrent builds and working copies available for builds 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 can use the cycleServices script to restart the services.You must run the script on all servers where TeamInspector 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 Settings
TeamInspector uses Lightweight Directory Access Protocol (LDAP) to authenticate users and contains the LDAP configuration settings in the configuration.properties file. This file is located in the /conf directory of your TeamInspector installation home directory. These settings are required to use TeamInspector. LDAP authentication must be set up before TeamInspector users can successfully log on. To configure these settings, edit the file and specify values as indicated in the following table. Some LDAP configuration settings have pre-set default values.You can use these default values, where applicable. 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 name and port specified for the TeamInspector data store repository.
Item Name Default Value Description
ldap_server ldap_server_name The server name (or address) that hosts the LDAP directory for your organization or workgroup that will be used to verify TeamInspector users.
ldap_port ldap_server_port_number The port number used to connect to the LDAP server.
ldap_base_dn dc=domainname,dc=domainorganizationname,dc=domaintypesuffix The base distinguished name, specified in accordance with your LDAP directory structure. For example, specifying an Internet domain name using the domain component attributes: dc=amer,dc=borl,dc=net
ldap_manager_dn domainname\\user The LDAP distinguished name for the account used for binding to the LDAP server to verify users. For example, amer\\tiuser
ldap_manager_password password The password of the LDAP user account used for binding to the LDAP server.
ldap_user_search_filter (sAMAccountName={0}) The filter (or search string) to use to look up users on the LDAP server. A search filter used for searching Windows Active Directory is provided as the default.
ldap_user_search_timeout_in_millis 10000 The maximum amount of time (in milliseconds) that TeamInspector will expend to verify a logon account with the LDAP server. The default is 10000 milliseconds (10 seconds)
14 | Configuring TeamInspector Item Name Default Value Description
If a logon fails, it typically indicates that the user's account does not match his or her LDAP user name.
ldap_connect_timeout_in_millis 10000 The maximum amount of time (in milliseconds) that TeamInspector will wait for the LDAP server to respond to a connection request.
Related Topics
Configuration Settings on page 13
Global Default Settings
The following default configuration settings are available from the Configuration page in TeamInspector.These settings are inherited by all projects defined in TeamInspector. It may be necessary to adjust the values more than 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 not appear in this order on the Configuration page.
Item Name Default Value Description
Build timeout period (secs) 60000 Maximum number of seconds that TeamInspector waits for a build to complete before reporting a failure and logging an error.
Number of concurrent builds 2 Maximum number of builds that can be executed at the same time. Note: setting the value to zero (0) synchronizes the value with the Number of working copies setting.
Number of working copies 2 Maximum number of working copies available for builds. This value corresponds to the number of working copies you want to have checked out at one time on the build server.
Working copy directory WC Name of the working copy base directory. You can change the name or indicate another path for the working copy directory. When entering a path, use forward slashes. If using backslashes, the backslash character must be escaped with another backslash character. For example either C:\\TI_WC or C:/TI_WC are acceptable:
Max check out items from 5000 Maximum number of files that can be checked out by TeamInspector SCM from the SCM server for build or inspection processing.
Retain artifacts (0–365 days) 0 Maximum number of days that build artifacts will be stored. A value of zero (0) specifies that artifacts will be stored indefinitely.
Configuring TeamInspector | 15 Item Name Default Value Description
Project monitor interval 30 Maximum number of seconds in the polling cycle for TeamInspector to (secs) check the data repository for changes to projects
Build request polling interval 60 Maximum number of seconds between each check for build requests (secs)
SCM monitor interval (secs) 30 The period of time (maximum number of seconds) between checks of the SCM system for changes to the stream. This setting determines the frequency of triggered builds, except for StarTeam streams. In that case, the SCM change wait period value, if larger, is used instead. If multiple projects are configured, this value might need to be increased to allow all project streams to be checked during the polling cycle (depending on how long it takes to check each stream, and how many polling threads are used). The SCM monitor interval does not affect the amount of time TeamInspector waits after a change before considering that change for a build for StarTeam streams.The SCM change wait period setting is provided for this purpose.
SCM monitor poll threads 4 Maximum number of threads used during the SCM polling interval to monitor the list of streams for changes. This setting helps control the number of threads that TeamInspector allocates to perform checks on the code streams. Using a higher value allows more checks to be performed during each poll interval.
SCM change wait period 60 The period of time (maximum number of seconds) that TeamInspector (secs) waits after each detected change before considering that change for inclusion in a build. This setting is relative to build-on-checkin projects that use code streams on StarTeam systems.This setting determines the frequency of triggered builds for StarTeam streams, when the value set is larger than the scm_poll_interval values.
SMTP server localhost The Simple Mail Transport Protocol (SMTP) server to use for processing TeamInspector mail notifications.
SMTP port 25 The port number to use on the SMTP server
SMTP user (none) The user account on the SMTP server to use for connecting to the server to process mail notifications from TeamInspector .
SMTP password (none) The SMTP user account password to use to connect to the server.
SMTP from email address (none) The email address to use in the “from” line in the mail notice.
Remember me period (0-31 5 The number of days that the remember-me logon will be in effect. When days) the value is set to zero (0), the remember-me check box will not be available to users.
Default host for builds localhost The name of the server on which the Job Service is installed.
16 | Configuring TeamInspector Item Name Default Value Description
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 on which the first Job Service is installed (successfully registered by TeamInspector) by default. If using an alias name or IP address for your build server, you must specify it for the host name.
FTP port number 21 The port number used by the TeamInspector Job Service to connect to the FTP service on the Master server.
Retain inactive service 7 The number of days that the remote build server can remain (1–365 days) unresponsive before being labeled inactive and no longer available for use by TeamInspector.
Related Topics
Configuration Settings on page 13
Configuration Files
In addition to the global default settings that TeamInspector makes available in the product interface, some settings 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 during an upgrade installation of TeamInspector. The other files in the conf directory are for the exclusive use of TeamInspector, and are not intended for user modification. configuration.properties File The configuration.properties file contains the LDAP configuration settings. These settings are used to 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 are specified during installation. env-settings.conf File The env-settings.conf file contains the environment settings for supported SCM systems which must be configured before you can use those systems in TeamInspector builds. The env-settings.conf.default file 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 Settings
You can modify the default values for the configuration settings. Changing these values enables you to override the 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 TeamInspector checks out to perform builds and inspections.You may want to adjust the configuration values to more efficiently align 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 concurrent builds. • 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 configuration settings are maintained in the configuration.properties file, and you must edit that file to set the values.
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 Authentication
Before 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 organization credentials. 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 their authorization level (role). To configure LDAP authentication
1. After installing TeamInspector, navigate to the /conf directory in the TeamInspector installation home directory. 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 against which 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 LDAP system 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 the value 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 the TeamInspector initial login account to set up users. For more information see Setting Up TeamInspector Users.
Related Topics
Configuring TeamInspector on page 13 LDAP Configuration Settings on page 14
Configuring the Notification Service
TeamInspector users can subscribe to email and SMS notifications of build events. Before users can receive the notifications, a TeamInspector administrator must configure the mail server information needed to route the notifications.
Configuring TeamInspector | 19 TeamInspector supports Simple Mail Transport Protocol (SMTP) for delivery of the notifications. This topic describes how to specify the SMTP server information that TeamInspector needs to initialize the notification service. 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 text messages, and may rely on various methods (such as SMS gateways or direct exchange) for message transfer. Therefore, the reliability of TeamInspector notifications for users specifying SMS notification is dependent on the recipient's carrier. Users who have properly set up their email notifications but experience problems receiving SMS notifications might need to contact their providers for assistance.
Related Topics
Configuring TeamInspector on page 13
Configuring Logon Options
TeamInspector provides automatic logon for users who choose the Remember Me option at logon. A TeamInspector administrator can configure the behavior of the Remember Me logon option by modifying the Remember 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 access the TeamInspector server must be configured to accept cookies to use this option and the TeamInspector functionality.
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 any user 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 logon attempt.
Related Topics
Configuring TeamInspector on page 13
Configuring SCM Environment Settings
For each software configuration management, or source control management, (SCM) system that you plan to use with TeamInspector, you must specify the environment settings in the TeamInspector configuration before you 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 is installed with each new installation. For upgrade installations, the settings are provided in the env-settings.conf.default file. To configure the settings, you must uncomment and edit the entries in each 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 Settings
To use a ClearCase software configuration management (SCM) system with TeamInspector, your environment must meet the following requirements:
Configuring TeamInspector | 21 • The ClearCase Remote Client must be installed on every system on which you have TeamInspector installed and 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 location on all systems. The jar files are included in a zip file in a standard ClearCase client installation. These files must 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 the files 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 TeamInspector is installed, create a directory under the base installation directory of TeamInspector and extract the JAR files from the IBM teamapi.zip file. For example, create the following directory in which to extract the files: external/SCMAPI/ClearCase Note: The directory names in this example are not required; you can use any directory name that you feel is appropriate. However, the directory in which the JAR files reside must be the same on all the TeamInspector systems.
Continue to step 2.
2. In the directory you just created, extract the following JAR files from the contents of the plugins/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 installation directory and update the file by uncommenting the following entries listed in the ClearCase Section: #set.CCWC_BASEDIR=
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 use ClearCase with TeamInspector.
4. After uncommenting these entries, edit the first line by replacing
Related Topics
Configuring SCM Environment Settings on page 21 Specifying a ClearCase SCM System on page 82
Configuring Perforce Settings
To use a Perforce software configuration management (SCM) system with TeamInspector, your environment must meet the following requirements: • The Perforce Command Line Client (P4) application must be installed on every system on which TeamInspector 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 by setting 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 same location on every system on which TeamInspector is installed and that you plan to use for Perforce builds and 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 and then install the JAR file. For example:
• 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 the file 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 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 the instructions 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 variable represents the default TeamInspectorinstallation directory, which is set in the following statement near the top of the env-settings.conf file: set.TI_INSTALL_DIR=C:\Program Files\Borland\TeamInspector. If TeamInspector was installed using the default installation path, uncomment the line containing this variable. If TeamInspector was installed in a location other than the default installation path, then replace the P4JAVA_BASEDIR path with the fully qualified path of the directory in which the P4Java JAR file is installed, 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 Settings
To use a StarTeam software configuration management (SCM) system with TeamInspector, your environment must meet the following requirements: • The StarTeam SDK version 10.1 or later must in installed on all the TeamInspector systems that you plan to use for builds with StarTeam streams. That is, the TeamInspector master server and each server that has 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 be accessible to TeamInspector through the environment settings. To specify the required settings, see the following section.
24 | Configuring TeamInspector 1. Locate the env-settings.conf file in the conf directory of your TeamInspector installation and edit the file as follows: • Uncommment the lines in the StarTeam section of the env-settings.conf file, as shown in the following example. #StarTeam Section # set.ST_BASEDIR=C:\Program Files\Borland\StarTeam SDK 10.1 set.ST_BASELIBDIR=%ST_BASEDIR%%WRAPPER_FILE_SEPARATOR%lib set.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.jar set.ST_CLASSPATH2=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%starteam101_win32.jar set.ST_CLASSPATH3=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%starteam101-resources.jar # set.ST_CLASSPATH4=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%ss.jar set.ST_CLASSPATH5=%ST_BASELIBDIR%%WRAPPER_FILE_SEPARATOR%swingall.jar set.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 upgrading your installation—you can add them by copying them from the env-settings.conf.default file 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 qualified path 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 Settings
To use a Subversion (SVN) source control management (SCM) system with TeamInspector, your environment must meet the following requirements: • The SVNKit JAR files must be installed on every system on which TeamInspector is installed that you plan to use for Subversion builds and inspections.You can download the SVNKit JAR files from http://svnkit.com/download.php. • TeamInspector requires environment settings in the env-settings.conf file to enable access to the SVNKit 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 the file as follows: • Uncommment the following lines in the SVNKit section of the env-settings.conf file, as shown in the 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.jar set.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 of the directory in which you extracted the JAR files from the downloaded SVNKit zip file, if it is different than what is provided. Note: The TI_INSTALL_DIR variable in this line is set in the following statement near the top of the env-settings.conf file. If you use the default value that is provided, make sure the line containing 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 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 build environment and configuring continuous integration. These objects are projects, streams, modules, and inspectors. After you have set up these objects to define your build environment, you can begin producing builds and getting inspection results in TeamInspector. See the Getting Started topics for more information about setting up 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 Projects
Projects are essential to defining the build execution and inspection processes that produce results in TeamInspector. These results are distribution artifacts, build analysis data, and code inspection data that are used to monitor and measure the quality of build processes and software code.You must have at least one project 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 from for builds and inspections. The mapping information you enter for a stream varies depending on the software configurtion management (SCM) system that you select to use for the stream. A stream might specify a directory path, a view, or a workspace (in the case of Perforce). All streams require connection information to the SCM host. 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 configured in the TeamInspector env-settings.conf file. For more informtion about this requirement, see the Installation Notes.
Modules A module specifies the build tool, build files, and the location of those files, as well as the test and analyzer tools, that you intend to use for your TeamInspector builds. TeamInspector uses the module definition to determine 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 specified in 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 (for example, build.xml), and the build target for builds that you want to run for a specific project. The build path is relative to the root level of the SCM system with which you are working. If you enter an invalid path or filename, TeamInspector allows the creation of the module definition. However, note that an invalid module associated 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 executables and 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 a module, 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 process build requests and inspections and analyze the results. • Each project name, stream name, and module name must be unique within TeamInspector. The names of these objects are treated as case-sensitive. • A project defines a single buildable unit. If you intend to produce builds with different outputs, you must create 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
Inspectors
An inspector is a TeamInspector extension that analyzes data output from a development tool, such as a test or code analysis tool, and transforms the data into comprehensive metrics that you can review in the TeamInspector 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 some standard and proprietary tools, TeamInspector's OpenInspector™ framework enables TeamInspector administrators to create inspectors to generate metrics from any test or code analysis tool running in your build environment. An OpenInspector defines a transformation stylesheet that converts the XML output of the tool into 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 of the 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 the build process. This is a common scenario. Or, the tool might run independently of the build process. To use the inspectors to produce metrics in TeamInspector, you must configure your analyzer (or test) tools to run within your build process. Note: You must have the analyzer tool associated with an inspector installed and available in your environment 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 must enable the inspectors in a module. After inspectors are configured and enabled in a module, an inspection of any project that uses the module will generate the inspection analysis data to the Portfolio Dashboard. Only a 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 Inspectors
TeamInspector provides a set of pre-defined inspectors for some commonly used tools which can readily be enabled in a module to generate metrics from those tools, if the tools are configured to produce results in your development environment. These inspectors are maintained and provided as a standard set of inspectors to provide metrics for each type of inspection that is supported in TeamInspector. TeamInspector also provides a proprietary inspector that is available to enable integration with SilkCentral Test 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 created and used to produce results for tools that are not pre-defined in TeamInspector. An extension is provided for each 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 inspector to 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 project on the main view of the Portfolio page to access the link.
Related Topics
Inspectors on page 30
OpenInspectors
TeamInspector's OpenInspector™ framework enables you to create inspectors to generate metrics from the results 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 tool results into the metrics that display in the Dashboard. The XSLT content for an OpenInspector must identify a unit test, or an analysis report, and include a call back into TeamInspector, specifying the results generated in the test output or analysis report. The content must be constructed using the XML schema elements specifically 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 Extensible Stylesheet 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 dialog box. TeamInspector does not provide an XML-compliant editor in which to create the content.
Related Topics
Inspectors on page 30
Inspector Types
TeamInspector inspectors are categorized into types.The inspector type is based on the type of tool producing the data output and the data type of the output. Currently, only the XML data type is supported as output from a test or analyzer tool. When you create an inspector (referred to as an OpenInspector), you must specify the type. 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 Test Manager (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 format supported by the inspector for that tool. TeamInspector requires the output format to be XML. A unit test inspector can be a standard inspector provided by TeamInspector, JUnit or NUnit, or a user-defined OpenInspector 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 unit tests 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 running in 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 checks for code style compliance. TeamInspector provides a CheckStyle inspector.You can create a code-analysis OpenInspector to generate results from any code-analysis tool running in your environment that produces output 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 item that will create a file element in the CheckStyle report that is not a Java source file, it can result in extra files that show up in the file count. Therefore, if you have any error in the source file, the Code Coverage percentage 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 the execution results is available from the context menu on the Portfolio page. Right-click the project on the main view of the Portfolio page to access the link.
32 | Build Environment and Concepts Related Topics
Inspectors on page 30
Understanding the Build Process
All 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 process is the same.
TeamInspector Build Actions When a build is invoked in TeamInspector, the request is processed in a series of events that occur in various stages. TeamInspector reports status in relation to each stage. Basically, TeamInspector processes a build request through the following stages: • Initialization – In this stage, TeamInspector is preparing to build by creating a job to process the build request, retrieving build records, checking out (or updating) a working copy of the source files, and submitting the job to the build queue. When this stage has completed successfully, TeamInspector transitions to the Build Started state. • Build – In this stage, TeamInspector runs the build tool or build executable, collects build results, and logs any 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 page during 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 the build return code indicates build success. The post-build processes are successful when analyzer tools are available and run successfully to produce results. If you have specified the Artifact Location for build output in the 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 might help 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 number of 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 value of one might require adjustments to the other, depending on your environment.You can maintain the synchronization of these two values by setting the Number of concurrent builds value to zero (0) and adjusting the Number of working copies value as needed. Note: If you are using a Perforce SCM system, consider how multiple concurrent builds of your projects using 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 temporary workspace 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 build from starting.
Remote Builds TeamInspector runs builds on a remote build server when the TeamInspector job service is installed on the build 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 the build 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 log for a remote build is not available in the Dashboard until the build process has completed. Likewise, build artifacts 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 build server, see Creating a Project.
Dependent Builds TeamInspector enables you to specify a dependent project in a project definition. When a dependent project is specified, the project for which the dependency is specified builds any time the dependent project successfully builds. When a project is built by being triggered by a dependent project, the build results will show the type as Triggered-dependency.
Working Copies TeamInspector maintains a working copy for builds in the TeamInspector working copy directory. It updates the working copy with current files when a build request is queued. The default location for the working copy directory is TEAM_INSPECTOR_HOME/WC. By default, TeamInspector allows two working copies to exist in 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 Number of working copies. This value determines the number of working copies available for jobs sitting on the build queue. TeamInspector uses the next available working copy to process a build request when multiple requests requiring the same build criteria are queued. If you are using remote build servers, the number of working copies maintained applies to each server. Note: Both the processing capacity and disk space capacity must be taken into account when adjusting these values. For more information about the concurrent build setting and the working copy setting, see the TeamInspector Configuration Settings topic.
Related Topics
Build Environment and Concepts on page 28
Build Statuses
TeamInspector displays various build statuses on the Builds page that indicate the current state or final outcome 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 Status Description
Setup TeamInspector has started the initialization phase and is creating a job to process the build request.
Pending TeamInspector has determined the revision of code to be built and the build is ready to be queued.
Queued The job has been queued and is ready to start.
Initializing The job has started, and TeamInspector is checking out the code and build resources.
Initialization Error One of the processes in the initialization phase failed and the job has terminated.
Build Pending Initialization completed successfully and TeamInspector is ready to start the build execution.
Build Started The build has started.
Build Error TeamInspector was unable to start the build process, at which point the job terminated.
Build Successful The build completed successfully.
Build Failed The build completed, but reported a failed status.
Analyzing The build completed with either a successful or failed build state, and TeamInspector is running the inspectors.
Cleaning Up 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.
Successful All processes started by this job are complete, and the build returned a successful status.
Failed All processes started by this job are complete, but the build returned a failed status.
Post-Build Error The build completed successfully, or with a failed status, but TeamInspector encountered errors when attempting to run the inspectors or attempting to store the artifacts and terminated the job.
Build Aborted The build process has been successfully 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 Types
TeamInspector supports the continuous integration concept.That is, builds in TeamInspector can be configured to 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 builds for 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 the changed files in the stream it is monitoring. TeamInspector continually polls the SCM repository and monitors streams for changes. When changes are detected, a build is automatically triggered. This type of build is reported 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 the build process. TeamInspector maintains a working copy for builds that is always synchronized with the current code stream when a build is initiated.You can configure multiple working copies for your environment. See the 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 the project. 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 project definition. When a dependent project is specified, the project for which you specified the dependency will build any 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 the same project.
Scheduled Builds You can schedule a build to occur independent of a check-in. The TeamInspector scheduler enables you to set up recurring builds at scheduled times to run for a project. Builds are scheduled on hourly increments. For example, if you intend to run builds twice daily, once in the morning and again in the afternoon, you can schedule the hourly interval for 8 hours, and specify the start time for 8:00 A.M. Using this scenario, the builds will 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 customized targets 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 for the project. Ad hoc builds provide flexibility and more control in managing build executions. For example, build engineers may want to test build processes and view the TeamInspector results, or software engineers might need the ability to run a build in between scheduled builds to build and test their code. Users viewing metrics in 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. TeamInspector administrators 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 Output
A TeamInspector build produces output that is not under source control. The output is generated in the TeamInspector working copy during a build. The output is the result of what is specified in the build file used by the project. If you want to use this output, TeamInspector makes it available for download through the Dashboard. That is, TeamInspector provides access to the build output stored in the directory that you specify as 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
Artifacts
An 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 | 37 Typically, artifacts are distribution files or packages, such as installers, that users want to copy and use. TeamInspector enables you to specify the directory where distribution artifacts are deposited during a build and then stores the artifacts for retrieval through the Dashboard. Artifacts are archived to the following location in your installation directory on the TeamInspector master server: TEAM_INSPECTOR_HOME/tomcat/webapps/artifacts/project_ID/build_number/ Tip: To determine the project name that corresponds to the project_ID in the artifacts folder, log on with administrator privileges and view the Projects page. If the Project ID column is not displayed, open the Columns menu and then check the Project ID check box to add it to your view.
Configuring the Artifacts Location To capture the artifacts that you want to store and distribute through TeamInspector, you must specify the artifacts location in a module. To set up a project for artifact distribution, create or edit a module that defines the build target and output location for your distribution artifacts. To specify the output location, enter the directory name and path in the Artifacts Location text box. Make sure your project is set up to use this module. Schedule builds for the project to coincide with your distribution strategy. The artifacts location value must specify a directory that exists inside the working copy after the build completes. TeamInspector does not support the artifact location identifying the entire working copy, or any location outside the working copy.
Artifacts Management By default, TeamInspector sets no limits on the length of time that it retains build artifacts on the master server. To enable artifact management, change the Retain artifacts configuration setting from 0 to the desired number of days. Artifacts older than the number of days specified in this setting are removed during the next daily purging cycle. For more information, see Managing Build Artifacts. Note: When artifact management is enabled and a project is deleted, TeamInspector also deletes the build artifacts for that project. The configuration setting for artifact retention applies to all projects that are defined in TeamInspector.
Tip: When enabling this setting, consider the number of projects for which you intend to preserve artifacts on the server. Also, consider the size of your distribution artifacts and the limitations of server space to be allocated to the artifact archive. The greater the number of days that you specify to store artifacts, the more disk space you will need to allocate to storing build artifacts on the master server.
Artifact Distribution When you configure your builds to produce distribution packages, TeamInspector enables you to download the packages from the Artifacts tab on the Builds page. This feature facilitates build distribution to team members during continuous integration cycles.
Artifacts Dependencies If your project dependency definition in TeamInspector includes the need to use the artifacts from a build of a dependent project as an input to a build of another project you can make use of the artifact URLs generated in the tibuild.properties file. For more information about the artifact URLs, see Passing Dependent Build Artifacts.
38 | Build Environment and Concepts Related Topics
Build Output on page 37
Build Logs
A build typically includes tasks to log events. TeamInspector creates a build log (build.log) for each build it initiates and makes the contents available for viewing in the Dashboard. The build logs are stored in the archive directory specified in the module that is associated with the project. The build log is created when the build script or build commands are executed and reports on each step that is processed during the build execution phase. To review information logged in the pre- and post-build phases of the build process, view the Job Log. You can open and view the build log, or download the build log file from the Artifacts tab, that is available from the Builds page.You can also access the build log from the Portfolio page when you choose the View most recent builds option from the context menu.
Related Topics
Build Output on page 37
Build Numbers
TeamInspector generates a build number for each build of a project and stores it in the tibuild.properties file. Each time a build is run on a project, the number is incremented by one for that project. So, the build number sequence displayed for a project is specific to that project. For example, if TeamInspector has executed five builds on project A, and ten builds on project B, it displays 5 as the last build number for project A and 10 as the last build number for project B. The build number is displayed on the Builds page and on the Portfolio pages of the TeamInspector Dashboard. You can reference these build numbers in your build tasks to use them for labeling of build output, such as build artifacts that you want to distribute through the Dashboard. For more information about how to implement these build numbers in your build scripts, see Using TeamInspector Build Numbers.
Related Topics
Build Output on page 37
Job Log
TeamInspector begins capturing events as soon as a build is initiated and records them in the job log. Some events are also captured in other log files, depending on which service is processing the event. For example, when the job server begins executing the build commands that compile the code, the build tasks or steps are captured in the build log. To help you track the progress of a build and monitor build states, you can view a condensed statement of each chronological event from the Job Log tab. The Job Log tab is available when you open the Build Details view on the Builds page. The Job Log tab provides the following information:
Build Environment and Concepts | 39 • Message – a condensed statement that describes what occurred in the process • Date – the date timestamp logged for the event when it started • Host – the host server on which the process ran • Service Type – the name of the TeamInspector service that processed the action If you are interested in more verbose information about these events, view the teaminspector-job.log.
Related Topics
Build Environment and Concepts on page 28
Security Model
The TeamInspector security model is based on users, roles, and the permission level associated with a role. A user is anyone defined as a user in TeamInspector and authenticated to TeamInspector when logging on. The actions a user can perform within TeamInspector are defined by the user's assigned role. Therefore, user authentication and user authorization are both required to access the resources and actions in TeamInspector. TeamInspector has two roles: • Administrator • User
Note: Users with system administrative privileges on the server can also use the command-line interface to run a TeamInspector build.
Administrator Role A role represents a single permission level. A permission level grants a specific level of access in TeamInspector. The Administrator role grants access to all resources and areas of functionality in TeamInspector, which includes the functionality inherent in the user role. The Administrator role allows users to do the following: • Configure the product • Administer users • Create projects • Set up builds and enable inspections • View metrics, reports, and build artifacts Note: A user can be assigned only one role in .
User Role The user role grants permission to access the TeamInspector Dashboard area. The Dashboard includes the portfolio views, build and inspection results, and the ability to start a build and manage your builds.This role is designed for users who are interested in monitoring software development metrics for quality results, or want to run builds and inspections and monitor the results, as well as access build distributions. Note: The Manual Builds for Users option must be enabled for a project before users with the User role can manually run builds in TeamInspector
40 | Build Environment and Concepts User Authentication Users are validated through LDAP authentication. When a user logs on using his organizational credentials, TeamInspector authenticates the user if the user is defined in TeamInspector and the user's credentials are verified via LDAP.The administrator responsible for setting up TeamInspector must enable LDAP authentication for the product before users can be defined. A TeamInspector administrator defines users based on their LDAP user names. Authentication occurs at log on. If user authentication fails, the user is denied access to log on. If the user's credentials are verified, the user's authorization privileges are checked. If the user's role cannot be verified, authorization fails and the user is denied access.
Related Topics
Build Environment and Concepts on page 28
Build Environment and Concepts | 41 Working in the Dashboard
The TeamInspector Dashboard displays all build and inspection results and enables you to monitor current build activity and historical trends for your projects from the Dashboard pages that are described in this section. In addition to analyzing build results, code quality inspections, and unit test metrics, you can perform various tasks from the Dashboard. For information about how to access these tasks, see Monitoring Your Software Projects and Managing Your Builds.
Related Topics
Getting Started With the Dashboard on page 42 Portfolio Page on page 43 Builds Page on page 46 Most Recent Builds View on page 50
Getting Started With the Dashboard
After an administrator has set up the environment, any TeamInspector user logging on with either the User role or the Administrator role can access the Dashboard. In the TeamInspector Dashboard, users can perform the following tasks from the Portfolio page or from the Builds page. The tasks that are available depend on the context of the page you are viewing. To learn more about the available options from each Dashboard page, see the other topics in this section. • Monitor build statuses and quality measurements for all your projects (Portfolio) • Analyze historical and current build, test, and inspection data (Portfolio) • View detailed inspection results for the most recent builds of a project (Portfolio) • View detailed build execution results for all builds (Builds page) • Filter and sort data in the detailed views (Builds page) • Track build progress or build process results after starting a build (Builds page) • Download build artifacts (Portfolio, Builds page ) • Run a project build (Portfolio) • Rerun an earlier version of a buld (Builds page) • Subscribe to email notifications to receive build alerts and confirmations (Portfolio) Note: The inspection data displayed in the Portfolio views are determined by the projects set up by your TeamInspector administrator.
42 | Working in the Dashboard Related Topics
Working in the Dashboard on page 42
Portfolio Page
TeamInspector ➤ Dashboard ➤ Portfolio The Portfolio page is the TeamInspector default view. Use the Portfolio page to monitor your development projects by reviewing the data resulting from builds, unit tests, and code inspections.The Portfolio page provides two views: • Summary view (main view) • Detailed view Note: If no items found displays on the Portfolio page, it indicates that projects are not defined or no builds have executed in the TeamInspector environment. See the Getting Started topics for information about how to set up your environment.
Portfolio Views The summary view, or main view, is a cross-project view that shows the results from the last 20 builds for each project. The summary view also shows the relevant data for the last build of each project. To view more than 20 builds at one time, use the detailed view. To open the detailed views for a project, select (click) the project in the Portfolio project list of the summary view. Note: If no data points appear in a column, it indicates that no inspector is enabled to capture data of that type for the project.
Related Topics
Working in the Dashboard on page 42 Portfolio Summary Data on page 43 Portfolio Detailed Views on page 44 Portfolio Context Menu Options on page 45
Portfolio Summary Data
The main view of the Portfolio page is meant to be a quick overview of the current activity for each of your projects. The following columns describe the summary data that is presented in this view: Item Name Description
Project Name This column displays the project names of all projects in your portfolio for which you can monitor builds and inspection data collected for the project.
Build Status This graph represents build results from the last 20 builds that occurred for the selected project. A green block indicates a successful build and a red block indicates a failed build.
Working in the Dashboard | 43 Item Name Description
To view when the last build occurred, point and hold the cursor over the graph in the build status column.
Unit Test Results This graph represents the success rate of unit tests for the last 20 builds that were executed for a project. The percentage shown represents the percentage of unit tests successfully executed for the last build. View the detailed charts to see the number of files analyzed by the test tools, the number of errors per file, the total number of warnings, and the total number of errors for each build represented in the view, or to view more than 20 builds.
Code Analysis This graph represents the code analysis errors that occurred for the last 20 builds for a project.The number shown in this column represents the number of errors for the last build. View the detailed charts to see the number of files analyzed, the number of errors per file, the number of warnings, and the number of errors for each build.
Code Coverage Results This graph represents code coverage results for the last 20 builds executed for a project. The percentage displayed represents the percentage of method coverage for the last build. To review class, method, block, and line coverage, view the detailed charts.
Related Topics
Portfolio Page on page 43
Portfolio Detailed Views
The detailed views provide the following information for a project that can help you determine which builds were error-prone or which code inspections revealed potential problems in the source code. Item Name Description
Builds tab The Build Results tab shows the build status detail view enabling you to determine the success and failure of builds by build number.You can use the slider bar to increase or decrease the number of builds shown in the Status window.
Unit Tests tab The Unit Tests tab graphs the following results from JUnit, Nunit, or other unit-test tools that run with your builds.
Percent success Shows the percentage of unit tests that were executed successfully for each build.
Test results Shows the number of unit tests that were executed successfully, the number that failed the test criteria, and the number that returned unexpected errors for each build.
44 | Working in the Dashboard Item Name Description
Code Analysis tab The Code Analysis tab graphs the following results from a Checkstyle inspection or from other code-analysis tools producing results from your builds.
Warnings and errors Charts the number of warnings and the number of errors, in 10K increments, for all files checked during the build for each build in the project.
File analysis Charts the number of files analyzed per build as indicated by the left axis, and the number of errors per file for each build as indicated by the right axis.
Code Coverage tab The Code Coverage tab graphs the following results from EMMA inspections or from other code-coverage tools producing results from your builds.
Methods Charts the percentage of method coverage completed for each build of a project.
Overall Charts the total test coverage from your code-coverage results for each build in a single graph. The graph shows the percentage of classes, methods, blocks, and lines covered if configured in your code-coverage implementation.
Related Topics
Portfolio Page on page 43
Portfolio Context Menu Options
When you right-click a project listed in the Portfolio summary view, you can choose one of the following actions from the context menu: Menu Action Description
View details Opens the detailed views, in which you can review a breakdown of the data and choose a different time range of builds to view. See Portfolio Detailed Views for more information
SCTM Results Provides a link to SCTM execution results, if you have Silk Central Test Manager (SCTM) integrated in your development environment.
View most recent builds Shows the last 20 builds that were executed by TeamInspector. Click a build to examine the inspection results for the build. This view provides a link to SCTM execution results, if you have SilkCentral Test Manager (SCTM) integrated in your development environment. You can also download build artifacts from this view.
Build Invokes a build on the selected project.Your build request is submitted to the build queue for processing.
Working in the Dashboard | 45 Menu Action Description
Notification Enables you to subscribe to build events and set up e-mail (or SMS) notification of those events.
Related Topics
Portfolio Page on page 43
Builds Page
TeamInspector ➤ Dashboard ➤ Builds Use the Builds page to review summary information and monitor results for any build that is triggered by a TeamInspector user or process.The Build Summary lists the status of all builds that have been queued, started, or run by TeamInspector, displayed 15 at a time. Use the navigation bar at the bottom of the list to navigate to the builds you are interested in viewing. If you do not see your builds in the list, check that the filter settings are not restricting your projects from displaying. From the Build Summary list you can customize your view, refresh the data, view more comprehensive details about a build, and perform build actions. Note: When you refresh the data, the list of builds in your current view can change. If one or more builds have started or completed running since you opened the view, these builds are included in the refreshed view, causing the last builds in a list of 15 builds to move to the next page.
Related Topics
Working in the Dashboard on page 42 Customizing Your View on page 46 Build Summary View on page 47 Build Details View on page 48 Builds Page Menu Actions on page 49 Build Numbers on page 39
Customizing Your View
The Build Summary view presents a default set of data.You can sort the data by column in the summary view in either ascending or descending order.You can also customize your view by adding or removing columns in the display and by filtering the builds by project. To access the column menu options, use the following procedure:
1. On the Builds page, place the mouse cursor in the header cell of the column for which you want to select options.
46 | Working in the Dashboard The arrow indicating a selection list appears. 2. Click the arrow to open the menu and select the options appropriate to how you want the data displayed in the view. • Filtering – In the Projects column menu, check the Filters check box and check each project that you want displayed in the view.You can turn filtering on and off by checking and unchecking the Filter option. • Sorting – In the selected column menu, select Sort Ascending or Sort Descending to sort the data for that column. This option is available in all of the column menus, but applies only to the data in the column in which you open the context menu. • Columns displayed – In any of the column menus, select Column and check or uncheck the columns to display or hide.
By default, TeamInspector sorts the Builds page by build number in ascending order. Use the column menu in the Build No column to change the sort order, or click in the column header to reverse the sort order.
Related Topics
Builds Page on page 46
Build Summary View
By default, the Build Summary view displays the following columns of data.You can change the default view by using the Columns menu. Column Description
Project Name of the project on which the build was run.
Build no Build sequence number for the build in relation to the series of builds run for this project.
Build tool Build tool or method (such as a command-line script) used to execute the build, as specified in the module component of the project definition.
Build status The current state of the build process for the selected build. TeamInspector displays a wide range of statuses during processing.The final status that displays for a build is the state the build was in when processing stopped. For example, if the status remains in the Pending state, it indicates that TeamInspector was not able to queue the build for processing. If a build appears to be suspended in a state, it generally indicates a time-delay during processing while in that state.
Build start time The timestamp (on the local client) when TeamInspector began processing the build request.
Type Indicates how the build was triggered: Check-in, Dependency, Manual, or Scheduled. For more information about the build types, see Build Types.
Working in the Dashboard | 47 Related Topics
Builds Page on page 46 Build Statuses on page 34 Build Types on page 36
Build Details View
The Build Details view appears when you click a build on the Builds page. The tabs in the Build Details view present the following information about your project builds: Tab Name Description
Detail tab In addition to the default columns displayed in the Build Summary view, the following information about the selected build is provided on the Detail tab.
Build end time The time on the local (client) server that the build process ended.
Duration Span of time from beginning to end that the build ran (actual time expended by TeamInspector to complete the build).
Host Host name or identity of the server on which the build was executed.
OS The operating system running on the host build server.
Started by user The TeamInspector user who started the manual build. No data appears in the User column for automated builds (scheduled or triggered builds).
Changes tab Lists the files that changed in this build. If the state of the files indicate no changes occurred for the build, the Changes tab displays a message that no items were found. This tab also indicates the name of the user who checked in the files.
Job Log tab Displays the state of events that occurred during the processing of the build request and shows which TeamInspector service performed the task that logged the event. This information is useful for monitoring the progress of a build in process. It also helps you isolate events and determine which service component failed during the build process. When viewing a build on the Job Log tab that is in progress, refresh the data to ensure you are viewing current data as the build progresses. Toggling between tabs in the Build Details view refreshes data displayed on a tabbed view.
Build Log tab Displays the contents of the log file for this build. If the build is in the queued state or has not yet completed, the message The build log is not available appears. All builds are queued to the TeamInspector job service for execution.
Artifacts tab Displays the output this build produced. From this tab, you can view files in the artifact directory or download artifacts to a specified location.You must have the Artifact Location configured in the module used for the project builds to capture the output.
48 | Working in the Dashboard Related Topics
Builds Page on page 46
Builds Page Menu Actions
TeamInspector provides various options that allow you to control the data displayed on the Builds page, and to perform actions on builds, by using the following menus.
Column Menu The column menu appears when you place your cursor inside a column header cell.This menu controls sorting, filtering, and which data columns are visible in your view.
Menu Option Description
Sort ascending Arranges data in the column in ascending order. Columns with alpha characters are sorted in alphabetical order from A-Z. Other columns are sorted numerically. This is the default sort behavior for columns.
Sort descending Changes the sort order from ascending to descending (last to first). For example, descending order sorts builds with the latest build number listed first.
Columns Opens a list of all available columns and allows you to check or uncheck the columns that you want to add or remove from your Build Summary view. The default columns are described on the Builds page.
Filter Enables filtering of builds by project. By default, filtering is disabled resulting in all projects being displayed on the Builds page. When you choose the filter option and select the projects that you are interested in filtering, only the projects that you have checked will display. If the Filters menu option is checked, filtering is enabled. If unchecked, the filtering is disabled.
Context Menu When you right-click in the row of a selected build on the Builds page, the following menu options are available.
Menu Action Description
View details Opens the Build Details view enabling you to review detailed build results. See Build Details View for information about the data displayed in the Build Details view.
Abort build Terminates a build that is in progress and reports the status as aborted appended to the build state at the point of termination.
Rerun build Reruns an original version of an earlier build, enabling you to produce artifacts specific to the build.
Working in the Dashboard | 49 Related Topics
Builds Page on page 46
Most Recent Builds View
The Most Recent Builds view lists the last 20 builds that occurred for a project, enabling you to focus your monitoring on the most recent activity. From this view, you can immediately see if a build succeeded or failed, view the analysis results for each build, and retrieve the artifacts for each build. This view provides the following build results:
• Build status – The build status icon represents success or failure for each build. • Unit tests – This column shows the percentage of tests that completed successfully. To view details about the errors, review the test output files in the Artifacts directory. • Code analysis – This column shows the number of code style errors. To view details about the errors, review the Checkstyle output files in the Artifacts directory. • Code coverage – This column shows the percentage of method coverage for the build. To view details about the errors, review the coverage output files in the Artifacts directory. • Duration – This column shows how long the build process took to complete in hours:minutes:seconds. • Link to external results – Displays a link to SCTM execution definition results if SilkCentral Test Manager is integrated with TeamInspector. • Artifacts – This area displays the build output.You can open or download the files from this area. If you have configured your builds to output installation packages, users can access the packages from this area. Installation packages are labelled with the build number if you have configured your build tasks to use TeamInspector build numbers.
Related Topics
Working in the Dashboard on page 42
50 | Working in the Dashboard Monitoring Your Software Projects
The Portfolio is a build management interface that enables you to monitor the current activity of all your projects. In the Portfolio, metrics are consolidated into a single high-level view that enables you to identify relationships between the data presented, observe trends, and recognize anomalies. The data presented in the graphical views enable you to perform consistency checks and quickly assess the health of your software build projects. These metrics can help you identify, measure, and assess the overall success of your development projects, such as in the following ways: For a sample view of the Portfolio metrics, how to interpret them, and the requirements for generating them to the TeamInspector Dashboard, see Metrics Overview.
Related Topics
Metrics Overview on page 51 Monitoring Build Consistency on page 52 Monitoring for Release Readiness on page 53 Monitoring for Build Process Inefficiencies on page 53 Monitoring Test and Code Coverage on page 53 Diagnosing Error-Prone Builds on page 54
Metrics Overview
The metrics that TeamInspector provides are dependent on the development tools running in your environment and the inspectors enabled for those tools in TeamInspector. TeamInspector runs a build or a code inspection based on how the project that triggers the inspection is configured. TeamInspector provides current metric data (in approximate real-time) and trending data in the graphical views on the Portfolio page. These metrics are presented in a meaningful way that can provide valuable insight into build and software code efficiency. For example: • Build efficiency — build times, build errors, success and failure rates. • Code quality — consistency checks, standards compliance, and unit-test success and failure rates. • Code coverage — code coverage from testing frameworks. • Execution results — results from quality control tests, such as SilkCentral Test Manager. From the detailed views, this data enables you to view the range of scores a metric produces over time and helps you measure the overall results against an average or a target goal. The following image shows an example of metrics displayed in the Portfolio when inspectors for tests, code analysis, and code coverage are enabled.
Interpreting the metrics in the Portfolio The metrics displayed in the graphs represent the following measurements:
Monitoring Your Software Projects | 51 • Builds — shows success (green bar) or failure (red bar) for each of the last 20 builds (or up to 100 builds in the detailed view). • Unit Tests — a sparkline represents tests that succeeded successfully for the last 20 builds and shows the percentage of tests that completed successfully for the last build.The detailed views break down the metrics, representing the percentage of tests that ran successfully (on the y axis) per build (x axis) in the first chart, and the number of tests that succeeded, failed, or returned errors in the second chart. • Code Analysis — represents the level of errors for the last 20 builds and shows the number of errors in the last build, for comparison. The detailed charts show the number of warnings and errors (y axis) per build (x axis) in the first chart, and the number of files analyzed (left y axis) and number of errors per file (right y axis) for each build in the second chart. If you see a high number of errors • Code Coverage results — represents the amount of method coverage for the last 20 builds and the percentage of coverage in the last build. Also displays class, block, and line coverage in the Details view, if you have those levels of coverage configured in your code-coverage reporting tools. • SCTM Execution results — If you have configured SilkCentral Test Manager (SCTM) to integrate with your TeamInspector builds, you can access execution results from the Portfolio.You can link to the SCTM server to view results from the context menu on the Portfolio page and from the Most Recent Builds view. If no link appears, it indicates that no information was returned from the SCTM server, or the SCTM inspector is not enabled. A “0” shown in any graph on the summary view indicates no data is available for the project. If no graph appears in a column for a project on the Portfolio page, it indicates that the inspector is not enabled for that analyzer. To enable inspectors to produce results from an analyzer tool, contact your TeamInspector administrator Note: In addition to the build status information displayed in the Portfolio views, TeamInspector provides complete details about each build that is available from the Builds page.
Related Topics
Monitoring Your Software Projects on page 51
Monitoring Build Consistency
Since the Portfolio Summary view is a time-series snapshot of the last 20 builds, you can pinpoint when inconsistencies start appearing and proactively address them. Build inconsistencies that show up in the Portfolio can help you Identify when build configuration changes occur. For example, you might notice a series of failed builds, or that unit test results or code analysis checks stopped at some point during the last 20 builds. This could indicate that something changed in the build script or test environment or that build resources or test tools became unavailable. You can investigate build failures further by viewing the build process information provided on the Builds page and reviewing the Job log.The Build log and the list of files that changed for the failed builds can also be useful in tracing build issues.
52 | Monitoring Your Software Projects Related Topics
Monitoring Your Software Projects on page 51
Monitoring for Release Readiness
Because the Portfolio Summary view is a cross-project view, in which you can monitor all the projects that you are responsible for, it provides insight into which projects are least likely to achieve release readiness. With this insight you are alerted to a potential risk in development builds and can focus on bringing the project up to par with your release milestones. For example, in the Portfolio Summary view, scan the list of projects for signs of problems, such as several failed builds in succession, and a recurring incidence of failed tests, and then note the project dates. If the end date, or release date (RTM), is looming, you can concentrate on taking action to address the issues and get back on track.
Related Topics
Monitoring Your Software Projects on page 51
Monitoring for Build Process Inefficiencies
The Portfolio view can provide a glimpse into build inefficiencies, because you can immediately identify which projects are not running unit tests or code analysis and code checks for the builds.This enables you to consider implementing, enabling, or integrating with test frameworks to provide the necessary checks during your build processes. For example, you might consider implementing JUnit or Nunit tests, or integrating with your SilkCentral Test Manager (SCTM) system to obtain execution results from your Silk testing framework.
Related Topics
Monitoring Your Software Projects on page 51
Monitoring Test and Code Coverage
If your goal is to determine if you have adequate code coverage or test coverage, or to examine the results of code coverage or unit tests for your project builds, you can access these statistics from the Portfolio. These results are charted in the Detail graphs in correlation with the build in which they were executed. From the Summary view, you can instantly determine if tests and coverage are implemented for your project builds. If tests and coverage are implemented, use the detailed views to analyze the results. For an explanation of the the metrics presented in the detailed graphs, see Portfolio Detailed Views.
Monitoring Your Software Projects | 53 Unit Tests The Portfolio shows the percentage of JUnit and/or NUnit tests that ran successfully for the builds. When you open the Portfolio detailed view for the project (click the project in the Portfolio list), you can see the correlation of successes, errors, and warnings per build for any range of builds that you choose, using the time slide bar. To review the actual number of errors and warnings for a particular build, in the Test results graph hover over the datapoint at the top of the graph line that corresponds to a particular build.
Code Coverage TeamInspector captures and reports the code coverage results according to the granularity specified in your EMMA implementation (that is, classes, methods, blocks, and lines).You can stay on top of the method coverage results from the Portfolio Summary view.You can monitor the additional levels of coverage from the detailed views. For example, if you are striving for 70-80% coverage you can track this from the Portfolio views. If you want to track trends for code coverage, you can do this by specifying any time period that you choose to view in the detailed views. This type of monitoring is typical in test-driven development environments, in which you automate tests, test often, and test early.
Related Topics
Monitoring Your Software Projects on page 51
Diagnosing Error-Prone Builds
When you observe failed builds in the Portfolio views, or review test coverage statistics that indicate a large number of errors or failed tests in the builds, you can investigate further by reviewing the information available from the Builds page. Following is an example scenario that relates to diagnosing error-prone builds.
Example Scenario You are monitoring the Portfolio page. The build status chart on the Portfolio page indicates a trend of failed builds.You need to determine the source of the problem. 1. Click the project in the Portfolio list of projects to open the Project details and determine the build numbers for the failed builds.Then, close the Project details view and go to the Builds page to review build execution details for those builds. 2. Click the build number of a failed build to open the Build Details tabs (make sure you are filtering on the project that you are interested in viewing). Use the following tabs to help isolate the failures: • Click the Job Log tab to determine at what stage in the processing that errors or problems occurred and which service was involved in the processing steps. • Click the Changes tab to view the source files that were updated for the build and which user checked in the files. • Click the Build Log tab to review the build execution events.
3. To help determine what might have caused build errors, refer to the information provided in the Troubleshooting section. You now have information that can help you narrow down the source of the build problems.
54 | Monitoring Your Software Projects Related Topics
Monitoring Your Software Projects on page 51 Troubleshooting Build Failures on page 115
Monitoring Your Software Projects | 55 Managing Your Builds
After starting a build in TeamInspector you may want to perform various actions to manage the build, such as abort a build, retrieve build artifacts, or rerun an earlier version of a build.You can perform these tasks, as well as access all builds, monitor builds in progress, and get comprehensive build results, from the Builds page in the Dashboard. Note: Although most build tasks are performed from the Builds page, you can retrieve build packages from the Most Recent Builds view that is accessible from the Portfolio context menu.You can also monitor build status, build quality metrics, and build trends from the Portfolio page in the Dashboard
Related Topics
Triggering a Build from the Portfolio on page 56 Aborting a build on page 57 Retrieving Build Artifacts on page 57 Rerunning an Earlier Build on page 58 Subscribing to Email Notifications on page 59 Event Notification Dialog Box on page 60 Viewing Build Results on page 60 Linking to Build Execution Results in SCTM on page 61
Triggering a Build from the Portfolio
Any TeamInspector user can trigger a build from the Portfolio page, if the option that allows users to build manually is enabled for the project. When you trigger a build, the build is queued to run according to the availability of resources. When multiple builds are queued, the builds are executed according to the number of concurrent builds and the number of working copies allowed by the TeamInspector configuration settings. Note: The user account you log on with must have system rights to execute the build file.
1. Open the Portfolio from the Dashboard area of the navigation pane, if not already open. 2. On the Portfolio page, right-click the project that you have selected to build and choose Build. A message is returned confirming the successful queueing of the build.You can monitor build results from the Portfolio detailed views and from the Builds page.
Note: The Build option is not available in the menu if user-triggered builds are not allowed for the project. Contact your TeamInspector administrator for build options.
56 | Managing Your Builds Related Topics
Managing Your Builds on page 56 Portfolio Context Menu Options on page 45
Aborting a build
When you abort a build in progress, TeamInspector attempts to terminate the process immediately, or at the earliest available point. If the build process is in the initialization phase, the build process typically terminates when transitioning to the next state. If the build process is in the Build Started state the abort procedure might not be successful until the build steps have completed, depending on the build tool or commands used to execute the build.
1. In the navigation pane, expand Dashboard and click Builds. The Builds Page opens. 2. Locate and then right-click the project build that you intend to abort. 3. Choose Abort Build. 4. Observe any user messages resulting from the request.
An aborted build will show on the Builds page with a Build aborted status. For builds that are in the process of being aborted, the status column shows the current state of the build with (aborted) appended to indicate that the abort request is pending. If the status remains in a pending state, it indicates that TeamInspector was unable to fulfill the request. View the Job Log from the Builds page for more detailed information about the process. An aborted build appears as a failed build in the Portfolio views. The abort process can fail If TeamInspector encounters a problem, such as unable to get a response from the service needed to process the request, or if the build process has already completed by the time the request is processed.
Related Topics
Managing Your Builds on page 56 Understanding the Build Process on page 33
Retrieving Build Artifacts
Each time TeamInspector builds a project, it maintains the build artifacts for download, if the artifacts are in the artifact location that has been configured for the project. For information about configuring the artifact location, see Build Output. You can access the artifact files for a build through the Artifacts tab when you view the build results, as described in the following steps.
1. In the Dashboard section of the navigation pane, click Builds. 2. On the Build Summary page, click the build that contains the build artifacts you are interested in retrieving.
Managing Your Builds | 57 The Build Details view opens. 3. Click the Artifacts tab. The artifacts directory listing for the project opens. Note: If a build failed or was aborted, the message No Items found appears.
4. Select the artifact that you want to download, and right-click to select the save option and specify a download location.You can also click (left-click) an artifact file to open the file or save the file to your workstation. Note: Multiple-file select is not enabled for the artifacts directory tree on the Artifacts tab, so individual files must be downloaded one at a time.
Related Topics
Managing Your Builds on page 56 Build Details View on page 48
Rerunning an Earlier Build
This task describes how to rebuild an earlier build of a TeamInspector project. Any TeamInspector user can rerun a build If manual builds for users is allowed for the project, and the user has the appropriate user rights to execute a build on the system. This task is useful for reproducing an earlier build to generate artifacts that are not available from the initial run of that build. When you rerun an existing build, TeamInspector retains the original build number and updates the date to report the last run date for that build number. Note: If the Artifacts Location is not specified in the module associated with the project at the time that you rerun the build, the artifacts are not generated. Rebuilding projects that have project dependencies defined in TeamInspector is not supported.
Tip: When a project—or the module or stream associated with the project—is deleted, all builds associated with that project are deleted as well and therefore those builds cannot be replicated.
1. In the navigation pane, expand Dashboard and click Builds. The Builds page opens. 2. Locate and then right-click the project build that you intend to rerun. 3. Choose Rerun Build. You can view the results of the build from the Build Summary page or from the Portfolio view. 4. To view details about the build or retrieve the build artifacts, on the Builds page click the build number of the build that you reran. The Build Details window opens. Click the appropriate tab to get the information that you need.
When you rerun an earlier build to reproduce the results of that build, the results are shown in the Portfolio views using the original number of the build. Therefore, If the results do not appear in the main view of the Portfolio page, open the detail view for the project and use the slider to expand the time line of the view until the build number appears in the view window.
58 | Managing Your Builds Related Topics
Managing Your Builds on page 56
Subscribing to Email Notifications
You can subscribe to build events and receive notifications of those events by specifying an email address or SMS address for each project in which you have an interest. Any user logging on to the Portfolio page can subscribe to event notification. Notification subscription is per project. To subscribe to all projects, you must set up notification for each project. TeamInspector allows you to be notified of the following events: • when a build starts • when a build completes successfully • when a build failed
Note: The SMTP services must be configured by a TeamInspector administrator before you can set up your email notifications.
1. Open the Portfolio page of the Dashboard. 2. Right-click the selected project for which you are interested in receiving notifications and choose Notification. The Event Notification dialog box opens. 3. In the dialog box, check the check boxes for one or more of the events to which you are interested in subscribing. • Build started • Build succeeded • Build failed
4. In the Notification methods section, check one or both of the check boxes to indicate how you want to receive notifications and enter the appropriate contact information: • Email — enter the email address to use for your notifications. For example, [email protected] • SMS — enter the mobile number or messaging service address (SMS) information, to use for your text message notifications. For example, [email protected]
Note: If you enable options in the Notification methods section and enter valid contact information, but no events are enabled in the Project events section, you will not receive any notifications.
5. Click Save.
To disable notifications, open the Event Notifications dialog box and take one of the following actions: • Uncheck all the project event check boxes. • Uncheck the notification methods that you intend to disable.
Note: It is not necessary to take both actions. If all events are disabled, or all notification methods are disabled, event notification is disabled.Your contact information is saved.
Managing Your Builds | 59 Related Topics
Managing Your Builds on page 56
Event Notification Dialog Box
Use this dialog box to select the events and notification methods to subscribe to build notification: Item Description
Project events Select one or more of the following events for which you are interested in receiving notifications: • Build started – Check this option to receive a notification any time a build of the selected project starts. The notification includes the timestamp of when the build started. • Build succeeded – Check this option to receive a notification any time a build of the project completes successfully. • Build failed – Check this option to receive a notification any time that a build fails to complete successfully.
Notification Select one or both of the following options to specify how you want to receive notifications: methods • Email – Check this option to receive e-mail notification of events. Enter your complete e-mail address. For example, [email protected] • SMS – Check this option to receive a short message notification of events, such as a text message. Enter your mobile number or the SMS address provided by your Short Message Service (SMS) provider.
Related Topics
Managing Your Builds on page 56
Viewing Build Results
A TeamInspector build produces build results that you can monitor from the Dashboard. On the Portfolio page of the Dashboard, you can monitor build statuses in high-level and detailed view charts. For more in-depth information about the Portfolio views, see the Portfolio page topic. Use the Refresh button on the Portfolio page to update the data that you are viewing. For detailed execution results, view the Builds page. The Builds page provides the following build results for all projects or the projects that you select using the projects filter: • Build Summary – Provides a default set of columns showing the build sequence number, build tool used to execute the build, build status, build start time, and build type (manual, scheduled, or triggered).You can change these default columns or add columns. Selecting a project in the list opens the tabbed views that enable you to view build details, build changes, the build log, and build artifacts. • Build details – Provides all execution details (as opposed to selected columns of data presented in the summary view). • Build changes – Provides a list of files that changed for the build and the name of the user that checked in the file. • Job log – Shows each step in the build process and which service performed the action.
60 | Managing Your Builds • Build log – Provides a record of build events logged during each build process. • Build artifacts – Provides access to files and distribution objects generated during the build process.
Note: Your build file must be configured to produce the output for the build artifacts and the location of that output must be specified in a module in your project.
To view build results
1. In the Dashboard section of the navigation pane, click Builds. The Build Summary opens displaying status information for all recent builds.The first 15 builds are displayed. Use the paging bar at the bottom of the list to view additional entries and navigate the list. To see additional columns in the Build Summary, click in a column heading to open the Columns menu and select one or more of the following columns: • Build End Time – The time stamp of when the build process completed. • Duration – The period of time consumed by the build process. • Host – The build server on which the build was executed. • OS – The operating system running on the build server. • User – The user that invoked the build, if the build type is Manual. Note that no data is displayed in this column if the build was invoked from the TeamInspector command-line interface (CLI).
2. In the Build Summary, select the build for which you are interested in viewing results data, and then click one of the following tabs to view the detail. • Detail – Click this tab to view details about the build execution. This tab opens by default when you select a build in the summary list. • Changes – Click this tab to view a list of the files that changed for this build. • Job Log – Click this tab to monitor the progress of a build and review the state of each task. • Build Log – Click this tab to open and view the build log. To download the log, use the Artifacts tab. • Artifacts – Click this tab to display the artifacts directory and select files to download.
3. To refresh the data, click the refresh icon on the paging bar. Toggling between tabs also refreshes the data displayed for a tab.
Related Topics
Managing Your Builds on page 56 Build Statuses on page 34 Build Types on page 36
Linking to Build Execution Results in SCTM
If the SilkCentral Test Manager (SCTM) product is integrated in your build environment, you can access execution results for builds in SCTM.
Managing Your Builds | 61 1. In the Dashboard, open the Portfolio page. 2. Right-click the build for which you are interested in viewing execution results, and take one of the following actions: • Choose SCTM results. A link to the SCTM executions page is opened. • Choose View most recent builds, and then click the link located below the list of builds. Although the first action provides direct access from the Portfolio page; the second allows you to access the results while working in the Most Recent Builds view.
Note: For more information about SCTM execution definitions, see your SilkCentral Test Manager documentation.
Related Topics
Managing Your Builds on page 56
62 | Managing Your Builds Administering the Build Environment
A large part of administering the build environment is setting up and managing the projects that define the build and inspection activities and results in TeamInspector. For example, how you set up your projects determines the metrics that are available for viewing in the Portfolio views. Projects depend on inspectors being enabled in the module component of a project to generate results. Projects also specify the continuous integration options that determine when builds will run in TeamInspector. Note: The TeamInspector Administrator role is required to perform all the tasks described in this section.
Related Topics
Build Administration on page 63 Project Administration on page 74 System Administration on page 93 User Administration on page 97 Working with OpenInspectors on page 100
Build Administration
Maintaining the TeamInspector build environment involves a variety of tasks. The tasks in this section relate to build execution and managing and storing build results. For example, you can manage the disk space used for storing build artifacts. Running builds on projects and specifying continuous integration options to determine how builds are triggered for a project are also typical build administration tasks.
Related Topics
Administering the Build Environment on page 63 Configuring Builds on page 64 Running a build on page 65 Schedule a Build on page 66 Specifying a Build Dependency on page 67 Passing Dependent Build Artifacts on page 68 Disabling Builds for a Project on page 68 Using TeamInspector Build Numbers on page 69 Managing Build Artifacts on page 70 Enabling Inspectors on page 70 Getting Unit Test Results on page 71 Getting CheckStyle Results on page 72
Administering the Build Environment | 63 Getting EMMA Results on page 73 Getting SCTM Test Results on page 74
Configuring Builds
TeamInspector builds are configured by defining a project and specifying the build processes to enable for that project. For each project that you define in TeamInspector, you can automate builds for that project by specifying the Continuous Integration Configuration options.You can enable all three types of continuous integration options for a project or create multiple projects, each defining a different buildable unit and different continuous integration option. For more information about the continuous integration options, see the TeamInspector Build Types topic. Note: By default, all projects have manual builds enabled for all users. Before you can set up your builds in TeamInspector, you must have your build environment set up.
Tip: If you are using Ant as your build tool, you must have the ANT_HOME variable set to the path where Ant is installed, if you do not have Ant in your build path.
To configure builds in TeamInspector
1. Create a project using a defined stream and module, or first create a new stream or module if needed for the project. For example: • If a stream is already defined that maps to the source code in an SCM repository that you want to use for builds, select that stream to associate with the project. A stream can be, and typically is, associated with multiple projects. • If a module is defined that specifies the build tool, build path, build file, and build target you want to use for the project builds, select that module to associate with the project. If you want to set a different build target for a build tool or specify a different builder, create a new module definition to associate with the project. If unit tests are implemented in your builds, make sure to enable the appropriate unit test inspector in the module that you associate with your projects to enable test results to display in the TeamInspector. See the links provided in the Related Information section for instructions on adding a stream or a module, or enabling inspectors. 2. Specify the manual build and continuous integration options to enable for the project.You can set these options when you create a project, or accept the default settings and edit the project when you want to adjust the settings. • Allow users to build manually (enabled by default) • Triggered builds (disabled by default) • Scheduled builds (disabled by default) The triggered build options include build on check-in and build on dependency. Scheduled builds provide the option to avoid building projects that have no changes detected since the last scheduled build. Note: To produce metrics from unit test results and analyzer tools running in your environment, the inspectors that correspond to your tools must be enabled. See Enabling Inspectors in the Related Information section for more information.
3. To synchronize the build numbers that your build tool generates with those that TeamInspector generates during a project build, implement a build task in your build file to pass the build number properties to your
64 | Administering the Build Environment build tool, or pass the environment variable for command-line builders. For more information, see Using TeamInspector Build Numbers.
If a project becomes invalid for any reason, any builds invoked on that project will fail. For example, an invalid project is typically caused by a change in the build system or code stream defined in the module and stream underlying the project definition. In this case, updating the module or stream to reflect the changes, or associating a new module or stream with the project, will correct the problem.
Related Topics
Build Administration on page 63 TeamInspector Setup Tasks on page 9
Running a build
TeamInspector builds can be initiated by TeamInspector administrators or users. If Allow users to build manually is enabled for a project, any user logging on to TeamInspector can run a build on that project from the Dashboard. If a build is already in process when you submit the build request, the job is queued to run when resources are available. The number of builds that can run concurrently are determined by the Number of concurrent builds configuration setting. There are two ways to run a manual build in TeamInspector: • From the Projects page (requires the Administrator role). • From the Portfolio page (available to all TeamInspector users). See Triggering a Build from the Portfolio View for details. Note: The user account you log on with must have system rights to execute the build file.You can also schedule builds in TeamInspector or build on check-in.
To run a manual build from the Projects page
1. In the navigation pane, expand Administration and click Projects. 2. Select the project for which you want to run a build and then click Build. 3. To view the build results, click Builds in the Dashboard. The Build Summary page opens showing build status information. To view additional details about a build, select the build and then click on the Detail tab, Changes tab, or Build Log tab. The Job Log tab is also available, which helps you track the state of each phase during the build processing.
Note: You can also run a build from the command line interface. Using a command-line script enables you to run multiple projects that specify different build targets in a single batch process. See Running a Build From the Command Line for more details.
Administering the Build Environment | 65 Related Topics
Build Administration on page 63
Schedule a Build
You can schedule a build of a project to occur at a specified time and interval. Builds are then submitted to the job queue on a recurring basis according to the build schedule. All TeamInspector builds, regardless of how they are triggered, are queued and run sequentially.
Related Topics
Build Administration on page 63 Scheduling a Build on page 66 Updating a Build Schedule on page 67
Scheduling a Build
1. Click Administration in the navigation pane, and then click Projects. 2. On the Projects page, select the project for which you want to schedule builds. 3. Click Edit. 4. In the Continuous integration configuration area, check the Build on a schedule check box. 5. If you want to bypass a scheduled build when no changes to the source files have occurred since the last build, check the Skip scheduled build when no SCM change is detected checkbox. 6. In the Start date field, select from the drop-down calendar a date on which the builds will start. 7. In the Start time field, select from the drop-down list options the hour at which the first build will start. Note: The start time you select corresponds to the build server time where the builds will run.
8. In the Interval field, enter the number of hours to indicate the interval for the build cycle. Note: Enter a whole number (positive integer) for the interval value. For example, for eight hours enter the value 8.
9. Click Update to accept the settings. Note: If you select a start time in the past, the first build will be scheduled to occur at the next upcoming interval. For example, presume that the current time is 6:00 a.m. on January 1, 2011 and you are setting a build schedule to start on January 1, 2011 at 1:00 a.m., with an 8 hour interval, the first build will occur in three hours – at 9:00 a.m.
Related Topics
Schedule a Build on page 66 Updating a Build Schedule on page 67
66 | Administering the Build Environment Updating a Build Schedule
1. Navigate to the Projects screen and select the project for which you are changing the build schedule. 2. Click Edit. 3. Select or enter new values for the build schedule that are enabled for this project. 4. If you intend to disable the build schedule, uncheck the Build on a schedule checkbox. Note: For more information about disabling a build schedule, see the Disabling Builds topic.
5. Either check or uncheck the Skip scheduled build when no SCM change is detected to specify your preference. 6. Click Update to save the settings.
Related Topics
Schedule a Build on page 66 Scheduling a Build on page 66
Specifying a Build Dependency
You can set up build dependencies in TeamInspector by specifying which project, if any, will trigger a build of your project. This option is useful for ensuring that a project always builds automatically based on the reliance of a stable build of another project. For example, you want to trigger a build of all components after the successful build of specific components. Another example, is when you might need to build code on multiple platforms, in which case you can specify a project that builds on a Linux system to trigger the build of a project on a Microsoft Windows system. To set up a dependent project build
1. Open the Projects page. 2. Select the project for which you intend to specify a build dependency and click Edit. The Update Project dialog box opens. 3. In the Continuous integration configuration section, check the Start a build upon successful build of project check box and select the dependent project. 4. Click Update to save the setting.
Note: If the check box is checked for this option, but No dependent project is specified in the text box, the option is invalid.
Administering the Build Environment | 67 Related Topics
Build Administration on page 63
Passing Dependent Build Artifacts
TeamInspector provides artifact URLs in a properties file that can be used to pass artifacts to a build from a dependent project build. If your project dependency definition in TeamInspector includes the need to use the artifacts from a build of a dependent project as input to a build of another project, you can use the artifact URLs generated in the tibuild.properties file. TeamInspector creates this file in the working copy directory. For example, these URLs can be accessed from within your Ant build script by using Ant's GET or FTP tasks. To use the artifact URLs, reference them in your build tasks and include a reference to the file tibuild.properties. The following properties are available in the tibuild.properties file, when a dependent project is specified. ${borland.teaminspector.build.dependent.dependent project name.http.url) ${borland.teaminspector.build.dependent.dependent project name.ftp.server) ${borland.teaminspector.build.dependent.dependent project name.ftp.port) ${borland.teaminspector.build.dependent.dependent project name.ftp.user) ${borland.teaminspector.build.dependent.dependent project name.ftp.password) ${borland.teaminspector.build.dependent.dependent project name.ftp.dir)
Note: These properties can be used with and without specifying the dependent project name.
1. Add a reference in your build script to include the tibuild.properties file for your builds. For an Ant build, for example, add the following line:
2. Create a task in your build script that uses the properties. For an Ant build, for example, create a target task with the following properties:
Related Topics
Build Administration on page 63 Artifacts on page 37
Disabling Builds for a Project
By default, all users logging on with User role privileges can invoke a build on a project. TeamInspector gives administrators the option to disable the build-on-demand option (referred to as a manual build) for users of a project. Administrators can also manage continuous integration options for a project by disabling or enabling automated builds.
68 | Administering the Build Environment To manage the build processes for a project
1. In the navigation area, expand Administration and select Projects. 2. Select the project and click Edit to manage the build options for that project. 3. To deactivate the manual build option, uncheck the Allow users to build manually check box. 4. In the Continuous integration configuration area, uncheck the check boxes for the options you are disabling. Alternatively, check the check boxes for build options that you want enabled. 5. Click Update to save the settings.
Note: If you disable scheduled builds, the schedule is not deleted and can be resumed when you re-enable it. When disabled, the schedule remains visible but appears dimmed in the project dialog box.
Related Topics
Build Administration on page 63
Using TeamInspector Build Numbers
TeamInspector generates a build number for each build that is initiated for a project. These build numbers can be referenced in your build scripts or build files for the purpose of labeling distribution files and packages. TeamInspector provides the build number in the tibuild.properties file, and also provides an environment variable that you can use to pass the build number to command-line builders. If you are using a command-line builder, use the following environment variable to pass the build number as input to your build tasks. ${BORLAND_TEAMINSPECTOR_BUILD_NUMBER) If you are using a build tool such as Ant or NAnt, use the following procedure as an example of how to reference the build properties file and specify the build numbers in your build tasks. Note: In the following example, if your build tasks are configured to build installation packages, the TeamInspector build number will be included in the package name.
To implement TeamInspector build numbers in your Ant or NAnt builds
1. Add a reference in your build script to include the build properties file for your builds. For example: For an Ant build, add the following line:
2. Create a task in your build script that uses the build number properties. For example: In an Ant build file create a target task with the following properties: