# Perforce Defect Tracking Integration Project
# <http://www.ravenbrook.com/project/p4dti/>
#
# CONFIGURE_TRACKER.PY -- BUILD P4DTI CONFIGURATION FOR TRACKER
#
# Robert Cowham, Vaccaperna Systems Limited, 2003-11-20
#
#
# 1. INTRODUCTION
#
# This module defines a configuration generator for the Tracker
# integration. Configuration generators are documented in detail in
# [GDR 2000-10-16, 8].
#
# The intended readership of this document is project developers.
#
# This document is not confidential.
import os
import catalog
import check_config
import dt_tracker
import logger
import re
import string
import tracker
import time
import translator
import types
error = "Tracker configuration error"
# 2. BUILD THE MAPPING BETWEEN STATES IN TRACKER AND PERFORCE
#
# The make_state_pairs function takes a Tracker connection and the
# "closed state", and returns a list of pairs of state names (Tracker
# state, Perforce state). This list will be used to translate between
# states, and also to generate the possible values for the State field
# in Perforce.
#
# The closed_state argument is the Tracker state which maps to the
# special state 'closed' in Perforce, or None if there is no such state.
# See requirement 45. See the decision decision [RB 2000-11-28b].
#
# The case of state names in these pairs is normalized for usability in
# Perforce: see the design decision [RB 2000-11-28a].
keyword_translator = translator.keyword_translator()
date_translator = dt_tracker.date_translator()
# 3. CONVERT DATE/TIME TO SECONDS
#
# This function converts a date/time in standard format, like
# '2001-02-12 19:19:24' [ISO 8601] into seconds since the epoch.
#
# We use this to convert the start_date configuration parameter. It is
# specified as an date/time for ease of entry, but Tracker represents
# date/times as seconds since the epoch. (Note that we specify -1 for
# the DST flag -- see job000381).
def convert_isodate_to_secs(isodate):
assert isinstance(isodate, types.StringType)
date_re = "^(\d\d\d\d)-(\d\d)-(\d\d) (\d\d):(\d\d):(\d\d)$"
match = re.match(date_re, isodate)
assert match
return time.mktime(tuple(map(int, match.groups()) + [0,0,-1]))
# 4. MIGRATION FUNCTIONS
def prepare_issue_advanced(config, tr, p4, dict, job):
# Call user hook (see [GDR 2001-11-14, 3]).
config.prepare_issue(dict, job)
def translate_jobspec_advanced(config, dt, p4, job):
return config.translate_jobspec(job)
# Function to be called if fix updated
# User Hook
def fix_update_p4_to_dt(replicator, issue, job, changes):
if not issue.bug.has_key('Date Fixed') or issue.bug['Date Fixed'] == '':
changes['Date Fixed'] = date_translator.translate_time_to_dt(time.localtime())
if not issue.bug.has_key('Fixed By') or issue.bug['Fixed By'] in ['', replicator.config.p4_user]:
changes['Date Fixed'] = date_translator.translate_time_to_dt(time.localtime())
p4_user = replicator.job_modifier(job)
dt_user = replicator.config.user_translator.translate_p4_to_dt(
p4_user, replicator.dt, replicator.dt_p4)
changes['Fixed By'] = dt_user
# Function which does global mapping of different fields from p4 jobs to issues
# User Hook
def translate_p4_to_dt(replicator, issue, job, changes):
if job[replicator.config.job_status_field] in ['closed', 'fixed']:
if not issue.bug.has_key('Status') or issue.bug['Status'] == 'Assigned':
changes['Status'] = 'Fixed'
if not issue.bug.has_key('Date Fixed') or issue.bug['Date Fixed'] == '':
changes['Date Fixed'] = date_translator.translate_time_to_dt(time.localtime())
if not issue.bug.has_key('Fixed By') or issue.bug['Fixed By'] in ['', replicator.config.p4_user]:
changes['Date Fixed'] = date_translator.translate_time_to_dt(time.localtime())
p4_user = replicator.job_modifier(job)
dt_user = replicator.config.user_translator.translate_p4_to_dt(
p4_user, replicator.dt, replicator.dt_p4)
changes['Fixed By'] = dt_user
# Function which does global mapping of from issues to jobs
# User Hook
def translate_dt_to_p4(replicator, issue, job, changes):
if issue['State'] == 'Closed':
if job[replicator.config.job_status_field] <> 'closed':
changes[replicator.config.job_status_field] = 'closed'
elif changes.has_key(replicator.config.job_status_field):
del changes[replicator.config.job_status_field]
# 5. BUILD P4DTI CONFIGURATION FOR TRACKER
def configuration(config):
# 5.1. Check Tracker-specific configuration parameters
check_config.check_string(config, 'tracker_user')
check_config.check_string(config, 'tracker_password')
check_config.check_string(config, 'tracker_project')
check_config.check_string(config, 'tracker_server')
check_config.check_string(config, 'email_domain')
check_config.check_string(config, 'query_all_scrs')
check_config.check_string(config, 'query_all_scrs_changed_in_last_day')
check_config.check_string(config, 'query_all_scrs_changed_in_last_week')
check_config.check_bool(config, 'use_windows_event_log')
if os.name <> 'nt':
# "Tracker integration only runs on Windows"
raise error, catalog.msg(1300)
# Set up loggers
loggers = []
log_params = {
'priority': config.log_level,
'max_length': config.log_max_message_length,
}
# The log messages should go to (up to) three places:
# 1. to standard output (if running from a command line);
if config.use_stdout_log:
loggers.append(apply(logger.file_logger, (), log_params))
# 2. to the file named by the log_file configuration parameter (if
# not None);
if config.log_file != None:
loggers.append(apply(logger.file_logger,
(open(config.log_file, "a"),),
log_params))
# 3. to the Windows event log (if use_windows_event_log is true).
if config.use_windows_event_log:
loggers.append(apply(logger.win32_event_logger,
(config.rid,),
log_params))
config.logger = logger.multi_logger(loggers)
# 5.2. Open a connection to the Tracker server
trk = tracker.tracker(config,
config.tracker_user,
config.tracker_password,
config.tracker_project,
config.tracker_server)
config.trk = trk
config.trk.login(config.tracker_user, config.tracker_password)
if not trk.field_exists('rid'):
# "Tracker field 'rid' must be created by administrator"
raise error, catalog.msg(1301)
config.jobname_function = lambda bug: 'SCR%06d' % int(bug['Id'])
# 5.3. Translators
#
# elapsed_time_translator = dt_tracker.elapsed_time_translator()
# int_translator = dt_tracker.int_translator()
# float_translator = dt_tracker.float_translator()
text_translator = dt_tracker.text_translator()
text_line_translator = dt_tracker.text_line_translator()
# strict user translator doesn't allow unknown users
strict_user_translator = dt_tracker.user_translator(
config.replicator_address, config.p4_user, allow_unknown = 0)
# lax user translator does allow unknown users
lax_user_translator = dt_tracker.user_translator(
config.replicator_address, config.p4_user, allow_unknown = 1)
user_translator = lax_user_translator
# Valid statuses - note duplicate 'open' for Perforce
state_pairs = [('Not Started', 'open'),
('Started', 'started'),
('Evaluated', 'evaluated'),
('Designed', 'designed'),
('Fixed', 'closed'),
('Tested', 'tested'),
('Resubmitted', 'open'),
]
# 5.6. Make values for the State field in Perforce
#
# Work out the legal values of the State field in Perforce. Note
# that "closed" must be a legal state because "p4 fix -c CHANGE
# JOBNAME" always sets the State to "closed" even if "closed" is not
# a legal value. See job000225.
legal_states = map((lambda x: x[1]), state_pairs)
if 'closed' not in legal_states:
legal_states.append('closed')
legal_states = filter(lambda s: s != None, legal_states)
unique_legal_states = []
for s in legal_states:
if s not in unique_legal_states:
unique_legal_states.append(s)
state_values = string.join(unique_legal_states, '/')
state_translator = dt_tracker.status_translator(state_pairs)
severity_pairs = []
severities = config.trk.get_choices('Severity')
for dt_s in severities:
p4_s = string.lower(dt_s)
p4_s = string.replace(p4_s, " ", "_")
severity_pairs.append((dt_s, p4_s))
severity_translator = dt_tracker.status_translator(severity_pairs)
legal_severities = map((lambda x: x[1]), severity_pairs)
severity_values = string.join(legal_severities, '/')
# Tracker fields that are read and their type.
# Used to read appropriate type in Tracker.py
#
# int - integer
# desc - description (can be greater than 255 - only 1 allowed per record
# string - string (up to 255)
#
tr_fields = {
'Id': ('int'),
'Title': ('string'),
'Assigned To': ('string'),
'Description': ('desc'),
'Perforce Note': ('note'),
'Fixed in Rel.Ver.Bld[Patch]': ('string'),
'Release in Ver.Bld[Patch]': ('string'),
'Assigned Project': ('string'),
'State': ('string'),
'Status': ('string'),
'Severity': ('string'),
'Date Fixed': ('string'),
'Fixed By': ('string'),
'Submit Date': ('string'),
'rid': ('string'),
}
for field in tr_fields.keys():
if tr_fields[field] <> 'note' and not trk.field_exists(field):
# "Tracker field '%s' doesn't exist - configuration error"
raise error, catalog.msg(1302, field)
# Some Tracker fields should not be changed from Perforce.
# Use Tracker field names.
read_only_fields = ['Id',
'Title',
'Severity',
'Description',
'Assigned To',
'Assigned Project',
'Submit Date',
'Release in Ver.Bld[Patch]']
# 5.7. Fields that always appear in the Perforce jobspec
#
# The 'p4_fields' table maps Tracker field name to a definition of
# the corresponding field in Perforce. The table also has entries
# for field not replicated from Tracker: these appear under dummy
# Tracker field names in parentheses.
#
# Perforce field definitions have nine elements:
#
# 1. Field number;
# 2. Field name;
# 3. Field type (word, line, select, date, text);
# 4. Field length;
# 5. Field disposition (always, required, optional, default);
# 6. The default value for the field, or None if there isn't one
# (field Preset);
# 7. Legal values for the field (if it's a "select" field) or None
# otherwise (field Values);
# 8. Help text for the field;
# 9. Translator for the field (if the field is replicated from
# Tracker), or None (if the field is not replicated).
#
# The five fields 101 to 105 are predefined because they are
# required by Perforce. The fields Job and Date are special: they
# are required by Perforce but are not replicated from Tracker.
# Note that their help text is given (the other help texts will be
# fetched from Tracker).
#
# We extend this table with fields from the "replicated_fields"
# configuration parameter (section 5.8). Next we use the table to
# buid the Perforce jobspec (section 5.9). Finally, we use the
# table to build the "field_map" configuration parameter which the
# replicator module uses to replicate the field (section 5.10).
p4_fields = {
'(JOB)': ( 101, 'Job', 'word', 32, 'required',
None, None,
"The job name.",
None ),
'Status': ( 102, 'STATUS', 'select', 32, 'required',
state_pairs[0][1], state_values,
"Issue's fixed status in Tracker",
state_translator ),
'Assigned To': ( 103, 'Assigned_to', 'word', 32, 'optional',
'$user', None,
"Owner of issue in Tracker",
user_translator ),
'(DATE)': ( 104, 'Date', 'date', 20, 'always',
'$now', None,
"The date this job was last modified.",
None ),
'Title': ( 105, 'Title', 'line', 0, 'required',
'$blank', None,
"Title of Issue",
text_line_translator ),
'Severity': ( 110, 'Severity', 'word', 32, 'required',
severity_pairs[0][1], severity_values,
"Severity of Issue",
severity_translator ),
'Assigned Project': ( 115, 'Assigned_project', 'line', 0, 'optional',
None, None,
"Project issue is assigned to.",
text_line_translator ),
'Fixed in Rel.Ver.Bld[Patch]': ( 120, 'FIXED_IN_REL.VER.BLD[PATCH]', 'line', 0, 'optional',
None, None,
"Which release/ver fixed in.",
text_line_translator ),
'Description': ( 125, 'Description', 'text', 0, 'optional',
None, None,
"Description of issue.",
text_translator ),
'Perforce Note': ( 130, 'PERFORCE_NOTE', 'text', 0, 'optional',
None, None,
"Notes about resolution of issue.",
text_translator ),
'Submit Date': ( 135, 'Submit_date', 'date', 20, 'optional',
'$now', None,
"The date this job was submitted.",
date_translator ),
'Release in Ver.Bld[Patch]': ( 140, 'Release_In_Ver.Bld[Patch]', 'line', 0, 'optional',
None, None,
"Targeted release.",
text_line_translator ),
'(RID)': ( 192, 'P4DTI-rid', 'word', 32, 'required',
'None', None,
"P4DTI replicator identifier. Do not edit!",
None ),
'(ISSUE)': ( 193, 'P4DTI-issue-id', 'word', 32, 'required',
'None', None,
"Tracker issue database identifier. Do not "
"edit!",
None ),
'(USER)': ( 194, 'P4DTI-user', 'word', 32, 'always',
'$user', None,
"Last user to edit this job. You can't edit "
"this!",
None ),
}
# 5.9. Make jobspec description
comment = ("# A Perforce Job Specification automatically "
"produced by the\n"
"# Perforce Defect Tracking Integration\n")
jobspec = (comment, p4_fields.values())
# 5.10. Generate configuration parameters
# Set configuration parameters needed by dt_tracker.
config.start_date = convert_isodate_to_secs(config.start_date)
config.state_pairs = state_pairs
config.read_only_fields = read_only_fields
config.tr_fields = tr_fields
# Initial fields to read to decide on issue being replicated
config.initial_fields = ["Id", "State", "Assigned Project"]
# Set configuration parameters needed by the replicator.
config.date_translator = date_translator
config.job_owner_field = 'Assigned To'
config.job_status_field = 'STATUS'
config.job_date_field = 'Date'
config.jobspec = jobspec
config.prepare_issue_advanced = prepare_issue_advanced
config.translate_jobspec_advanced = translate_jobspec_advanced
config.text_translator = text_translator
config.user_translator = user_translator
config.translate_p4_to_dt = translate_p4_to_dt
config.translate_dt_to_p4 = translate_dt_to_p4
config.fix_update_p4_to_dt = fix_update_p4_to_dt
# The field_map parameter is a list of triples (Tracker database
# field name, Perforce field name, translator) required by the
# replicator.
#
# This is generated from the p4_field table by filtering out fields
# that aren't replicated (these have no translator) and selecting
# only the three elements of interest.
config.field_map = \
map(lambda item: (item[0], item[1][1], item[1][8]),
filter(lambda item: item[1][8] != None, p4_fields.items()))
# Logout to ensure Tracker all clean and tidy
config.trk.logout()
return config
# A. REFERENCES
#
# [GDR 2001-11-14] "Perforce Defect Tracking Integration Advanced
# Administrator's Guide"; Gareth Rees; Ravenbrook Limited; 2001-11-14;
# <http://www.ravenbrook.com/project/p4dti/version/1.5/manual/aag/>.
#
# [GDR 2000-10-16] "Perforce Defect Tracking Integration Integrator's
# Guide"; Richard Brooksby; Ravenbrook Limited; 2000-10-16;
# <http://www.ravenbrook.com/project/p4dti/version/1.5/manual/ig/>.
#
# [GDR 2000-10-16] "Perforce Defect Tracking Integration Integrator's
# Guide"; Gareth Rees; Ravenbrook Limited; 2000-10-16;
# <http://www.ravenbrook.com/project/p4dti/version/1.5/manual/ig/>.
#
# [ISO 8601] "Representation of dates and times"; ISO; 1988-06-15.
#
# [RB 2000-11-28a] "Case of state names" (e-mail message); Richard
# Brooksby; Ravenbrook; 2000-11-28;
# <http://info.ravenbrook.com/mail/2000/11/28/14-24-32/0.txt>.
#
#
# B. DOCUMENT HISTORY
#
# 2002-04-05 NB job000501: handle creation of new jobs when
# LASTMODIFIEDDATE or SUBMITDATE are replicated
#
#
# C. COPYRIGHT AND LICENCE
#
# This file is copyright (c) 2003 Vaccaperna Systems Ltd. All rights
# reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in
# the documentation and/or other materials provided with the
# distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
# TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
# DAMAGE.
#
#
# $Id: //info.ravenbrook.com/project/p4dti/version/1.5/code/replicator/configure_teamtrack.py#3 $