vcseif 1.2.0

data/lib/vcseif.rb

@@ -0,0 +1,23 @@
+# Copyright 2001-2013 Rally Software Development Corp. All Rights Reserved.
+
+minimum_ruby_version = "1.9.2"
+if RUBY_VERSION < minimum_ruby_version
+   abort "\nVCSEIF does not work with Ruby versions below #{minimum_ruby_version}.  Please upgrade.\n"
+end
+
+require_relative "version"
+
+require_relative "vcseif/utils/rally_logger"
+require_relative "vcseif/utils/exceptions"
+require_relative "vcseif/utils/proctbl"
+require_relative "vcseif/utils/lock_file"
+require_relative "vcseif/utils/time_file"
+require_relative "vcseif/utils/fuzzer"
+require_relative "vcseif/utils/konfigger"
+require_relative "vcseif/utils/auxloader"
+
+require_relative "vcseif/connection"
+require_relative "vcseif/rally_vcs_connection"
+require_relative "vcseif/vcs_connector"
+require_relative "vcseif/vcs_connector_runner"
+require_relative "vcseif/vcs_connector_driver"

data/lib/vcseif/connection.rb

@@ -0,0 +1,285 @@
+# Copyright 2001-2013 Rally Software Development Corp. All Rights Reserved.
+
+require "socket"
+require "resolv"
+
+#############################################################################################################
+
+class ChangesetSelector
+
+    attr_accessor :attribute, :relation, :value
+
+    def initialize(condition)
+        """
+            A ChangesetSelector instance is of the form: 
+                attribute relational_operator value_or_expression
+            Prime our 3 instance attributes of interest in case the regex match fails
+        """
+        @attribute = ""
+        @relation  = ""
+        @value     = ""
+        # define our extractor regex to handle a string with "attribute relation value_or_expression_that_may have spaces"
+        # examples: 'Revision = 4' or 'Author = NilsLofgren' or "CommitTimestamp >= '2012-09-12T17:32:49.000Z'"
+        # We only support these relational operators (=, !=, <, <=, >, >=) 
+        attr_identifier_pattern = '[a-zA-Z@$%&*].*[a-zA-Z0-9_@$%&*]+'
+        relational_operators     = ['=', '!=', '<', '<=', '>', '>=']
+        relations = "%s" % [relational_operators.join('|')]
+        selector_pattern_spec = "^(?<attribute>%s)\s+(?<relation>%s)\s+(?<value>.+)$" % [attr_identifier_pattern, relations]
+
+        selector_patt = Regexp.compile(selector_pattern_spec)
+        md = selector_patt.match(condition)
+        if not md.nil?
+            @attribute = md[:attribute].strip()
+            @relation  = md[:relation]
+            @value     = md[:value].strip()
+        end
+        if (@attribute.empty? or @relation.empty? or @value.empty?)
+            problem = "Invalid Changeset Selector specification: %s" % condition
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+    end
+end
+
+#############################################################################################################
+
+class VCSConnection
+    
+    attr_accessor :log, :config
+    attr_reader   :username, :password, :username_required, :password_required, :rev_uri, :file_uri
+    attr_reader   :connected
+    attr_accessor :changeset_selectors, :sshkey_path
+
+    REVNUM_TOKEN  = "{revnumber}"
+    REVFILE_TOKEN = "{filepath}"
+
+    def initialize(logger)
+        @log      = logger
+        @config   = nil
+        @username = nil
+        @password = nil
+        @username_required = true
+        @password_required = true
+        @changeset_selectors   = []
+        @connected = false
+        @log.info("Initializing %s connection version %s" % [name(), version()])
+    end
+
+    def name()
+        """
+            abstract, provider should return a non-empty string with name of the specific connector
+        """
+        raise NotImplementedError, problem
+    end
+
+    #Placeholder to put the version of the connector
+    def version()
+        """
+            abstract, provider should return a non-empty string with version 
+            identification of the specific connector
+        """
+        problem = "All descendants of the VCSConnection class need to implement version()"
+        raise NotImplementedError, problem
+    end
+
+    def getBackendVersion()
+        problem = "All descendants of the VCSConnection class need to implement getBackendVersion()"
+        raise NotImplementedError, problem
+    end
+
+    def connect()
+        %{
+            Returns true or false depending on whether a connection was "established".
+            As many connectors are stateless, the "establishment of a connection" might
+            just mean that the target and credentials are adequate to post a request and
+            receive a non-error response.
+         }
+        problem = "All descendants of the VCSConnection class need to implement connect()"
+        raise NotImplementedError, problem 
+    end
+
+    def disconnect()
+        """
+            Returns true or false depending on whether an existing connection was disconnected
+            successfully.
+            As many connectors are stateless, the disconnection may be as easy as 
+            resetting an instance variable to None
+        """
+        problem = "All descendants of the VCSConnection class need to implement disconnect()"
+        raise NotImplementedError, problem
+    end
+
+
+    def validate()
+        satisfactory = true
+
+        if @username_required == true
+            if !username || @username.empty?
+                @log.error("<Username> is required in the config file")
+                satisfactory = false
+            else
+                @log.debug('%s - user entry "%s" detected in config file' % [self.class.name, @username])
+            end
+        end
+
+        if @password_required == true
+            if !password || @password.empty?
+                @log.error("<Password> is required in the config file")
+                satisfactory = false
+            else
+                @log.debug('%s - password entry detected in config file' % self.class.name)
+            end
+        end
+
+        satisfactory = hasValidChangesetSelectors() if satisfactory
+
+        return satisfactory
+    end
+
+
+    def getRecentChangesets(ref_time)
+        """
+            Finds items that have been created since a reference time (ref_time is in UTC) 
+            and applying all specified ChangesetSelector conditions.
+
+            Concrete subclasses must implement this method and return a list of qualified items.
+        """
+        problem = "All descendants of the VCSConnection class need to implement getRecentChangesets(ref_time)"
+        raise NotImplementedError, problem
+    end
+
+    def is_windows?
+      RUBY_PLATFORM.downcase.include?("mswin") || RUBY_PLATFORM.downcase.include?("mingw")
+    end
+
+    #look for tokens {revnumber} and {filepath} and put in the correct values
+    #cgit here:
+    #commit: http://git.company.com/cgit/reponame.git/commit/?id={revnumber}
+    #file:   http://git.company.com/cgit/reponame.git/diff/{filepath}?id={revnumber}
+    #github:
+    #commit: https://github.com/reponame/commit/{revnumber}
+    #file:   https://github.com/reponame/blob/{revnumber}/{filepath}
+    #Mercurial (Hg):
+    #commit: http://hgweb:8000/rev/{revnumber}
+    #file:   http://hgweb:8000/file/{revnumber}/{filepath}
+    def get_rev_uri(revision_number)
+      return nil if @rev_uri.nil?
+      @rev_uri.gsub(REVNUM_TOKEN, revision_number)
+    end
+
+    def get_file_rev_uri(revision_number, filepath, operation = nil)
+      return nil if @file_uri.nil?
+      file_uri = @file_uri.gsub(REVNUM_TOKEN, revision_number)
+      file_uri.gsub(REVFILE_TOKEN, URI::encode(filepath))
+    end
+
+    private
+    def internalizeConfig(config)
+        """
+            config has already been read, it comes to us here as
+            a dict with information relevant to this connection
+        """
+        @config = config
+        username  = config['Username'] || false # Deprecate
+        user      = config['User']     || false # Deprecate
+        @username = username || user
+        @password = config['Password'] || false # Deprecate
+        @sshkey_path   = config["SSHKeyPath"]
+        @changeset_selectors  = config['ChangesetSelectors'] || []
+
+        @rev_uri  = config["RevURI"] unless config["RevURI"].nil?
+        @file_uri = config["FileURI"] unless config["FileURI"].nil?
+
+        # minimum valid selector spec is 6 chars, 'xy = z'
+        bad_chgset_selectors = @changeset_selectors.select {|sel| sel.length < 6}
+        if bad_chgset_selectors.length > 0
+            problem = "One or more ChangesetSelector specifications is structurally invalid"
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+        
+        if @changeset_selectors.length > 0
+            #transform our textual selector conditions to ChangesetSelector instances
+            @changeset_selectors = @changeset_selectors.collect {|cs| ChangesetSelector.new(cs)}
+        end
+    end
+
+
+    def field_exists?(field_name)
+        """
+            Return a boolean truth value (true/false) depending on whether the targeted
+            field_name exists for the current connection on a Changeset
+        """
+        problem = "All descendants of the VCSConnection class need to implement field_exists?(field_name)"
+        raise NotImplementedError, problem
+    end
+
+
+    def hasValidChangesetSelectors()
+        """
+            This method should be overridden in the VCSConnection subclass for 
+            connections whose target does not support standard relational 
+            operators of (=, !=, <, >, <=, and >=) .
+        """
+        if @changeset_selectors.length == 0
+            return true
+        end
+        status = true
+        @changeset_selectors.each do |cs|
+            if not field_exists?(cs.field)
+                @log.error("ChangesetSelector field_name %s not found" % cs.field)
+                status = false
+            end
+        end
+
+        return status
+    end
+
+
+    def _targetServerIsLocalhost(target)
+        localhost_short = Socket.gethostname
+        return true if target == localhost_short
+        return true if target.downcase == "localhost"
+        # is the IP of the target also the IP for resolv.getaddress(Socket.gethostname)?
+        target_ip = Resolv.getaddress(target)
+        localhost_ip = ''
+        begin
+            localhost_ip = Resolv.getaddress(localhost_short)
+        rescue => ex
+            ok = false
+            begin
+                ifc = getInterfaceInfo()
+                if ifc.include?('en0') and not ifc['en0'].nil?
+                    localhost_ip = ifc['en0']
+                    ok = true
+                elsif ifc.include?('en1') and not ifc['en1'].nil?
+                    localhost_ip = ifc['en1']
+                    ok = true
+                else
+                    raise if not ok
+                end
+            rescue => ex
+               puts "#{ex.class.name} => #{ex.message}"
+            end
+        end
+        return target_ip == localhost_ip
+    end
+
+    def getInterfaceInfo()
+        # This seems to be only necessary on *nix when Resolv.getaddress(Socket.gethostname) fails
+        ifc_info = {}
+        ifc_out = %x[/sbin/ifconfig -a]
+        for line in ifc_out.split("\n") do
+            if line =~ /^(\w+\d): /
+               ifc = $1
+               ifc_info[ifc] = nil
+            elsif line =~ /\binet (\d+\.\d+\.\d+\.\d+) /
+                  ip_addr = $1
+                  ifc_info[ifc] = ip_addr
+            end
+        end
+        return ifc_info
+    end
+
+end
+

data/lib/vcseif/rally_vcs_connection.rb

@@ -0,0 +1,925 @@
+# Copyright 2001-2013 Rally Software Development Corp. All Rights Reserved.
+
+require 'time'
+require 'uri'  # for URI::encode of the filename attribute of Change
+
+require 'vcseif/utils/exceptions'
+require 'vcseif/connection'
+require 'vcseif/utils/auxloader'
+
+# from 'vcseif' we use utils/exceptions.UnrecoverableException, 
+#                      utils/exceptions.ConfigurationError
+#                      utils/exceptions.OperationalError
+#                      connection.VCSConnection
+#                      utils/auxloader.ExtensionLoader
+
+require 'rally_api'
+
+############################################################################################
+
+class RallyAPI::RallyObject
+    # Augment RallyAPI::RallyObject with the ability to set an attribute;
+    # We'll use it to set an 'ident' attribute 
+    def []=(field, value) 
+        @rally_object[field] = value 
+    end
+end
+
+############################################################################################
+
+class RallyVCSConnection < VCSConnection
+
+    RALLY_VCS_CONNECTION_VERSION = "1.2.0"
+    WSAPI_VERSION = "1.43"
+
+    VALID_ARTIFACT_TYPES = ['HierarchicalRequirement', 'Task', 'Defect', 'DefectSuite']
+
+    ISO8601_TS_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+    EXTENSION_SPEC_PATTERN = Regexp.compile('^(?<ext_class>[\w\.]+)\s*\((?<ext_parm>[^\)]+)\)$')
+
+    attr_reader   :valid_artifact_pattern
+    attr_accessor :server
+    attr_accessor :rally, :operational_errors
+    attr_reader   :extensions
+    attr_reader   :rally_wsapi_version, :repo_ref
+    attr_reader   :user_cache
+
+    def initialize(config, logger)
+        @valid_artifact_pattern = nil # set after config with artifact prefixes are known
+        super(logger)
+        internalizeConfig(config) 
+        @log.info("Rally WSAPI Version %s" % rallyWSAPIVersion)
+        @integration_other_version = ""
+        @username_required = true
+        @password_required = true
+        @operational_errors = 0
+        @user_cache = {}
+    end
+
+    def name()
+        "Rally"
+    end
+
+    def version()
+        RALLY_VCS_CONNECTION_VERSION
+    end
+
+    def rallyWSAPIVersion()
+        @rally_wsapi_version
+    end
+
+    def getBackendVersion()
+        %{
+            Conform to Connection subclass protocol which requires the version of 
+            the system this instance is "connected" to.
+         }
+        return "Rally WSAPI %s" % rallyWSAPIVersion
+    end
+
+    def internalizeConfig(config)
+        super(config)
+
+        @server = false
+        @server = config['Server'] if config.has_key?('Server')
+        if !@server || @server.nil?
+            problem = "RallyConnection spec missing a value for Server"
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+        if server.downcase =~ /http:/ or server.downcase =~ /\/slm/
+            @log.error("Rally URL should be in the form 'rally1.rallydev.com'")
+            problem = "RallyConnection Server spec invalid format"
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+
+        proxy = config['Proxy'] || nil
+        set_proxy_info(config) if not proxy.nil?
+
+        @rally_wsapi_version = config['WSAPIVersion'] || WSAPI_VERSION
+        @workspace_name    = config['Workspace']      || nil
+        @repository_name   = config['RepositoryName'] || nil
+        @repo_ref = nil
+        @restapi_debug     = config['Debug'] || false
+        @restapi_logger    = @log
+        #@restapi_logger   = @log if restapi_debug || nil
+    end
+
+
+    def set_proxy_info(config)
+        """
+            Given the config with any Proxy* related items, the simple case is to assemble the
+            final proxy to be stuffed in ENV['http_proxy'] as <protocol>://<proxy>.
+            If the config has config['ProxyUser'] and config['ProxyPassword'] values, then
+            the final proxy is assembled with <protocol>://<proxy_credentials>@<proxy>
+            and stuffed in ENV['http_proxy'].
+        """
+        proxy = config['Proxy']
+        proxy_protocol = config['ProxyProtocol'] || "http"  # protocol default is 'http'
+        if proxy.downcase =~ /^(https?):\/\/(.+)$/
+            proxy_protocol = $1
+            proxy          = $2
+        end
+
+        proxy_user     = config['ProxyUser']     || nil
+        proxy_password = config['ProxyPassword'] || nil
+
+        if proxy_user.nil? and proxy_password.nil?
+            proxy = "%s://%s" % [proxy_protocol, proxy]
+        elsif not proxy_user.nil? and not proxy_password.nil?
+            proxy_credentials = "%s:%s" % [proxy_user, proxy_password]
+            proxy = "%s://%s@%s" % [proxy_protocol, proxy_credentials, proxy]
+        else # one of proxy_user / proxy_password is nil
+            problem = "Proxy specified, insufficient proxy authentication information supplied"
+            @log.error(problem)
+            problem = "RallyConnection ProxyUser/ProxyPassword settings must both have values"
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+        ENV['http_proxy'] = proxy
+    end
+
+
+    def get_custom_headers()
+        custom_headers =  RallyAPI::CustomHttpHeader.new()
+        custom_headers.name    = @integration_name    || "Rally VCS Connector for UNKNOWN"
+        custom_headers.vendor  = @integration_vendor  || 'Rally'
+        custom_headers.version = @integration_version || "1.0"
+        
+        if not @integration_other_version.empty?
+            conn_ver_target_ver = "%s - %s" % [custom_headers.version, @integration_other_version]
+            custom_headers.version = conn_ver_target_ver
+        end
+        return custom_headers
+    end
+
+
+    def set_integration_header(header_info)
+        @integration_name    = header_info['name']
+        @integration_vendor  = header_info['vendor']
+        @integration_version = header_info['version']
+        if header_info.has_key?('other_version')
+            @integration_other_version = header_info['other_version']
+        end
+    end
+
+
+    def setSourceIdentification(vcs_type, vcs_uri)
+        @vcs_type = vcs_type
+        @vcs_uri  = vcs_uri
+    end
+
+
+    private
+    def configureExtensionEnvironment()
+        %{
+            For now, the only extension to be considered is one that would provide a service
+            to pull artifact identifiers and actions from within a commit message that is going
+            to be used in creating a new Changeset in Rally.  The enablement of that is controlled
+            by the truthiness of the UpdateArtifactState entry in the Rally section of the config.
+            If UpdateArtifactState is enabled, we'll want to load the extension that will provide
+            the service of artifact identifier/action extraction.  But before that happens, 
+            a list containing Hashes with information about the allowed values for the update field
+            of each artifact type must be constructed.  This list is passed to the extension
+            at instantiation time so that it can accurately determine which actions to report
+            were present in the commit message.
+
+            To do that, we'll query Rally for the allowed values of each of the artifact types
+            in VALID_ARTIFACT_TYPES.
+         } 
+        artifact_state_field = { 'US' => 'ScheduleState',
+                                  'S' => 'ScheduleState',
+                                 'DS' => 'ScheduleState',
+                                 'DE' => 'State',
+                                 'TA' => 'State'
+                               }
+
+        # Do a Rally query to get allowed values for each actifact_type.artifact_state_field.
+        # so that we can have it to populate the artifact_specs list
+        wksp_oid = @workspace_ref.split('/')[-1][0...-3]
+
+        artifact_specs = []
+        @art_prefixes.each do |prefix|  
+            art_type = @artifact_type[prefix]
+            rally_type = art_type
+            if ['Story', 'UserStory'].include?(rally_type)
+                rally_type = 'HierarchicalRequirement' # Peee-yuuuh
+            end
+            upd_field = artifact_state_field[prefix]
+            begin
+                allowed_values = @rally.allowed_values(rally_type, upd_field).keys()
+                next if allowed_values.nil?
+            rescue => ex
+                @log.debug("Unable to retrieve any allowed values for #{rally_type}.#{upd_field}")
+                next
+            end
+            candy = "allowed values for %s.%s: %s" % [art_type, upd_field, allowed_values.join(" | ")]
+            @log.debug(candy)
+            spec = {    'artifact' => art_type,
+                          'abbrev' => prefix, 
+                    'update_field' => upd_field,
+                    'valid_values' => allowed_values
+                   }
+            artifact_specs << spec
+        end
+
+        @extensions = {}
+        extension = loadExtension(@config, 'UpdateArtifactState', 'StateExtractorClass')
+        # extension comes back as an assoc array, augment it with a live instance if anything is in it
+        if !extension.nil? and extension.length > 0
+            # TODO: see if some other means of supplying the initial argument can be done
+            #       this really only works for *ArtifactsAndActionsExtractor related classes
+            extension['extender']        = extension['extension_class'].new(artifact_specs)
+            @extensions['StateExtractor'] = extension
+        end
+    end
+
+
+    def loadExtension(conf, enabler, extension_ident)
+        """
+            alpha level implementation, doesn't allow for instantiation parms,
+            or method name(s) other than service.  
+            Handling of service parm not really wonderful either (How about multiple parms...?)
+
+            Caller must provide a conf Hash with enabler and extension_ident keys in that Hash.
+            The enabler controls whether or not we look for, load and obtain an instance of
+            the extension_ident.
+            The extension_ident has to be in the form of [[subdir.]filename.]ClassName([parm])
+        """
+        extension = {}
+
+        booleans = ["TrueClass", "FalseClass"]
+        enabled = conf[enabler] || false
+        if enabled and booleans.include?(enabled.class.name)
+            trues = ['true', '1', 'yes', 'y', 'ok', 'on', 'enable']
+            enabled = trues.include?(enabled.to_s.downcase) ? true : false
+        end
+        @log.info("%s enabled to use %s?  %s" % [enabler, extension_ident, enabled])
+        if enabled
+            extension_spec = conf[extension_ident] || nil
+            md = EXTENSION_SPEC_PATTERN.match(extension_spec)
+            if not md
+                msg = "%s specified to enable %s via '%s' but that specification is in an unrecognized format" % \
+                       [enabler, extension_ident, extension_spec]
+                confex =  VCSEIF_Exceptions::ConfigurationError.new(msg)
+                raise confex, msg
+            end
+                
+            extension_class_name, extension_parm = md[:ext_class], md[:ext_parm]
+            extension_class = ExtensionLoader.getExtension(extension_class_name)
+            @log.debug("Extension class %s loaded" % extension_class_name)
+
+            extension = {'extension_class_name'=> extension_class_name,
+                         'extension_class'     => extension_class,
+                         'extension_parm'      => extension_parm,
+                        }
+        end
+        return extension
+    end
+
+
+    public
+    def connect()
+        @log.info("Connecting to Rally")
+        custom_headers = get_custom_headers()
+        rally_config = { :base_url  => "https://%s/slm" % @config['Server'],
+                         :username  => @config['Username' ],
+                         :password  => @config['Password' ],
+                         :version   => @rally_wsapi_version,
+                         :headers   => custom_headers
+                       }
+        # specifically exclude workspace from rally_config, so we can do a vanilla connect
+        # and then see if the workspace value in the @config actually exists
+        # in the workspaces available for the user
+
+        proxy = ENV['http_proxy'] || nil
+        if not proxy.nil? and not proxy.empty?
+            @log.info("Proxy for connection to Rally: %s" % proxy)
+            rally_config[:proxy => proxy]
+        end
+
+        begin
+          @rally = RallyAPI::RallyRestJson.new(rally_config)
+          info = @rally.user
+        rescue Exception => ex
+            @log.debug(ex.message)
+            problem = "Unable to connect to Rally at %s as user %s" % [@config['Server'], @config['Username']]
+            operr = VCSEIF_Exceptions::OperationalError.new(problem)
+            @operational_errors += 1
+            raise operr, problem
+        end
+        @log.info("Connected to Rally server: %s" % @config['Server'])    
+
+        # verify the given workspace name exists
+        wksp = @rally.find_workspace(@config['Workspace'])
+        if wksp.nil? or (not wksp.nil? and wksp['Name'] != @config['Workspace'])
+            desc =  "Specified Workspace: '%s' not in list of workspaces available "
+            desc << "for your credentials as user: %s"
+            problem = desc % [@config['Workspace'], @config['Username']]
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+
+        # now that we know @config['Workspace'] is a valid workspace, 
+        # ensure that all further interactions with Rally are confined to that workspace
+        # as embodied in the wksp object we just got back from the check
+        @rally.rally_default_workspace = wksp
+        @log.info("    Workspace: %s" % @config['Workspace'])
+        # and verify that the BuildandChangesetEnabled flag is set for this workspace
+        wksp.read()
+        wksp_conf = wksp.WorkspaceConfiguration
+        wksp_conf.read()
+        if wksp_conf.BuildandChangesetEnabled != true
+            problem = "The BuildandChangesetEnabled flag is not enabled for the '%s' workspace. " % @config['Workspace']
+            problem << "Contact your Rally workspace administrator to set this up."
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+        @wksp = wksp
+        @workspace_ref = @wksp['_ref']
+        @workspace_oid = @workspace_ref.split('/')[-1][0...-3]  # last part of url sans the '.js' suffix
+        getArtifactPrefixes()
+        @connected = true
+        return true
+    end
+
+    def getArtifactPrefixes()
+        @artifact_type   = {}
+        @artifact_prefix = {}
+        @art_prefixes = []
+
+        query_info = { :type => :typedefinition, :fetch => "ElementName,IDPrefix", 
+                       :workspace => @wksp } 
+        pfx_query = RallyAPI::RallyQuery.new(query_info)
+        results = @rally.find(pfx_query)
+        for typedef in results do
+            next if typedef['IDPrefix'].nil? or typedef['IDPrefix'].empty?
+            next if not VALID_ARTIFACT_TYPES.include?(typedef['ElementName'])
+            art_type = typedef['ElementName']
+            art_type = 'UserStory' if art_type == 'HierarchicalRequirement'
+            art_prefix = typedef['IDPrefix']
+            @artifact_type[art_prefix] = art_type
+            @artifact_prefix[art_type] = art_prefix
+            @art_prefixes << art_prefix
+        end
+        prefixes = @artifact_prefix.values.join('|')
+        @valid_artifact_pattern = Regexp.compile('^(%s)\d+$' % prefixes)
+    end
+
+    def validate()
+        # obtain a ref to the target SCMRepository
+        @log.info("SCMRepository: %s" % @config['RepositoryName'])
+        repo_name = @config['RepositoryName']
+        #todo should this get defaulted by the connector?  it doesn't at the moment
+        if repo_name.nil?
+            problem = "A repo name must be specified in the Rally section of the config."
+            @log.error(problem)
+            confex = VCSEIF_Exceptions::ConfigurationError.new(problem)
+            raise confex, problem
+        end
+
+        repo = getSCMRepository(@wksp, repo_name)
+
+        if repo.nil?
+            repo = createSCMRepository(repo_name, @vcs_type, 'Created by VCSConnector', @vcs_uri)
+            action = "created SCMRepository: '%s' in the '%s' workspace"
+            @log.info(action % [repo_name, @workspace_name])
+        else
+            repo.read()
+            repo_oid = repo['_ref'].split('/')[-1][0...-3]
+            created = Time.parse(repo['CreationDate'])
+            found_repo = "Found SCMRepository '%s' with OID of %s created on %s in workspace '%s'"
+            @log.debug(found_repo % [repo_name, repo_oid, created.localtime, @wksp['Name']])
+        end
+        repo_oid = repo['_ref'].split('/')[-1][0...-3]
+        @repo_ref = 'scmrepository/%s' % repo_oid
+
+        configureExtensionEnvironment()
+
+      return true
+    end
+
+
+    def disconnect()
+        """
+            Reset our rally instance variable to nil and toggle @connected indicator
+        """
+        @rally = nil
+        @connected = false
+    end
+
+
+    private
+    def getSCMRepository(workspace, repo_name)
+        query = RallyAPI::RallyQuery.new(:type  => :scmrepository, 
+                                         :fetch => true, 
+                                         :workspace => @wksp)
+        query.query_string = '(Name = "%s")' % repo_name
+        begin
+            results = @rally.find(query)
+        rescue Exception => ex
+            problem = "Unable to obtain Rally query results for SCMRepository named '%s'" % ex.message
+            boomex = VCSEIF_Exceptions::UnrecoverableException.new(problem)
+            raise boomex, problem
+        end
+        if results.length > 0
+            return results.first
+        else
+            @log.debug("No SCMRepository named |#{repo_name}| in Workspace: |#{workspace.Name}|")
+            return nil
+        end
+    end
+
+
+    def createSCMRepository(repo_name, scm_type, desc=nil, uri=nil)
+        """
+            Create an SCMRepository using the given parms in the current workspace.
+
+            NOTA BENE:  in order to get your SCMRepository created in a specific workspace
+                        you _MUST_ provide the ref to that workspace, otherwise the 
+                        SCMRepository will be created in your default workspace.
+
+            ADDITIONAL: An SCMRepository is only indirectly associated with a Project 
+                        so setting it in the creation here would have no effect;
+                        hence we dispense with attempting to do so.
+        """
+        repo_spec = {
+                      "Name"        => repo_name,
+                      "SCMType"     => scm_type,
+                      "Description" => desc || "",
+                      "Uri"         => uri  || "",
+                      "Workspace"   => @workspace_ref,
+                    }
+        activity = "Creating SCMRepository '%s' (%s) in the '%s' workspace..."
+        @log.info(activity % [repo_name, scm_type, @wksp.Name])
+        begin
+            repo = @rally.create(:scmrepository, repo_spec)
+        rescue Exception => ex
+            problem = 'Unable to create SCMRepository: %s' % ex.message
+            boomex = VCSEIF_Exceptions::UnrecoverableException.new(problem)
+            raise boomex, problem
+        end
+        @log.info('SCMRepository %s created, OID=%s' % [repo.Name, repo.ObjectID])
+        repo.read()
+        return repo
+    end
+    
+
+    public
+    def getRecentChangesets(ref_time)
+        """
+            Obtain all Changesets created in Rally at or after the ref_time parameter
+            (which is a Time instance)
+        """
+        ref_time_readable = ref_time.to_s.sub('UTC', 'Z')
+        ref_time_iso      = ref_time.iso8601
+        @log.info("Detecting recently added Rally Changesets")
+        selectors = ['SCMRepository.Name = "%s"' % @repository_name,
+                     'CreationDate >= %s'        % ref_time_iso
+                    ]
+        # TODO: See if having ChangesetSelectors is something that will be useful,
+        #       but note that it will necessitate "binary'ing" the resultant query conditions
+        #       to the Rally WSAPI requirements.
+        #for cs in changeset_selectors do
+        #    sel = '%s %s "%s"' % [cs.field, ss.relation, cs.value]
+        #    selectors << sel
+        #end
+
+        log_msg = '   recent Changesets query: %s' % selectors.join(' AND ')
+        @log.info(log_msg)
+
+        chgset_query = RallyAPI::RallyQuery.new(:type      => :changeset,
+                                                :fetch     => "Revision,CommitTimestamp",
+                                                :workspace => @workspace,
+                                                :project   => nil,
+                                                :pagesize  =>  200,
+                                                :limit     => 2000)
+        chgset_query.query_string = '((%s) AND (%s))' % selectors  # P-eeee-yuuuhhhh (syntax)!
+
+        begin
+            results = @rally.find(chgset_query)
+        rescue => ex
+            bomex = VCSEIF_Exceptions::UnrecoverableException.new(ex.message)
+            raise boomex, ex.message.to_s
+        end
+
+        log_msg = "  %d recently added Rally Changesets detected"
+        @log.info(log_msg % results.total_result_count)
+        changesets = []
+        results.each do |changeset|
+            changeset['ident'] = changeset.Revision
+            changesets << changeset
+        end
+
+        if not changesets.empty?
+          last_changeset = changesets.last  
+          @log.info("date of last reflected Changeset in Rally: #{last_changeset.CommitTimestamp}")
+        end
+
+        return changesets
+    end
+
+
+    def createChangeset(int_work_item)
+        """
+            This method should never be overridden (it might be called 'final' in another language).  
+            Instead override any of the next three methods.
+        """
+        modified_int_work_item = preCreate(int_work_item)
+        work_item              = _createInternal(modified_int_work_item)
+        modified_artifact      = postCreate(work_item)
+        return modified_artifact
+    end
+
+
+    private
+
+    def preCreate(int_work_item)
+        """
+            Connection assumes int_work_item is giving us a timestamp already in iso8601 format
+        """
+        drop_author = true  # default to not including the Author in the Changeset
+        results     = nil
+        # TODO: fix the following so we already have either User object or the username AND the user._ref ...
+        username = int_work_item['Author']
+        have_potential_author = !username.nil? and !username.empty?
+        if have_potential_author
+            user_query = RallyAPI::RallyQuery.new({:type => :user, :fetch => 'UserName'})
+            user_query.query_string = '(UserName = "%s")' % username
+            begin
+                results = @rally.find(user_query)
+            rescue => ex
+                @log.debug(ex.message)
+                problem = "Unable to complete Rally query for user information about '%s'" % username
+                operr = VCSEIF_Exceptions::OperationalError.new(problem)
+                @operational_errors += 1
+                raise operr, problem
+            end
+        end
+        if not results.nil?
+            user = results.first
+            begin
+                int_work_item['Author'] = user._ref
+                drop_author = false
+            rescue Exception => ex
+                verbiage = "  No Rally User entry associated with '%s' was found, " % username
+                verbiage << "Author field for Changeset not set"
+                @log.warn(verbiage)
+            end
+        end
+
+        int_work_item.delete('Author') if drop_author
+
+        return int_work_item
+    end
+
+
+    def _createInternal(int_work_item)
+        # add Workspace and SCMRepository refs
+        int_work_item['Workspace']     = @workspace_ref 
+        int_work_item['SCMRepository'] = @repo_ref 
+
+        # add Artifacts from looking at Message and extracting the FormattedID values
+        artifactIDs = extractArtifactFormattedIDs(int_work_item['Message'])
+        if artifactIDs
+            @log.debug("artifactIDs from extractArtifactFormattedIDs: %s" % artifactIDs.join(", "))
+        end
+        artifacts = getArtifacts(artifactIDs)
+        artifacts.each { |art| @log.debug("    valid existing artifact: %s" % art.FormattedID) }
+        arts = artifacts.collect{ |art| art.FormattedID}.join(" ")
+        if artifacts.empty?
+            @log.debug("No valid artifacts were mentioned in message")
+        else
+            @log.debug("valid artifacts mentioned in message: %s" % arts)
+        end
+        artifact_refs = artifacts.collect {|art| {'_ref' => art._ref}}
+        int_work_item['Artifacts'] = artifact_refs
+
+        action_targets = {}
+        if @extensions.include?('StateExtractor')
+            extension = @extensions['StateExtractor']
+            if !extension.nil? and extension
+                extender = extension['extender']
+                # TODO: don't like hard-coding 'Message', what if we need others...?
+                action_targets = extender.service(int_work_item['Message'])  
+            end
+        end
+
+        # save the action_targets and artifacts until after we create the Changeset/Changes
+        # then we can attempt to update those if so specified in the config (UpdateArtifactState : true)
+
+        # snarf the Additions, Modifications, Deletions to produce the Change list
+        # but then drop those out of the int_work_item
+        adds = int_work_item['Additions']
+        mods = int_work_item['Modifications']
+        dels = int_work_item['Deletions']
+        extraneous = ["Additions", "Modifications", "Deletions"]
+        for file_status in extraneous do    # get rid of extraneous keys in int_work_item now
+            int_work_item.delete(file_status)
+        end
+
+##
+##        puts ""
+##        puts "changeset raw data prior to attempted creation in Rally:"
+##        for field in ['Workspace', 'SCMRepository', 'Revision', 'CommitTimestamp',  
+##                      'Author', 'Message', 'Uri', 'Artifacts'] do
+##            puts "    %18s : %s" % [field, int_work_item[field]]
+##        end
+##        puts "valid artifacts mentioned in message: #{arts}"
+##        if config.get('UpdateArtifactState') and action_targets:
+##            showArtifacts(action_targets, artifacts)
+##        else
+##            puts "UpdateArtifactState setting: %s  action_targets: %s" % \
+##                  [config.get('UpdateArtifactState'), action_targets.inspect]
+##        end
+##        puts ""
+##        #NOTE: above commented out debugging/troubleshooting code last used June 2012
+##
+        changeset = nil
+        begin
+            changeset = @rally.create(:changeset, int_work_item)
+            cset_info = [changeset.ObjectID, changeset.Revision[0...16], changeset["CommitTimestamp"]]
+            verbiage = "Created Changeset: OID: %s  Revision: %s Timestamp:|%s|"
+            if artifacts.empty?
+                verbiage << " (not associated with any Artifacts)"
+            else
+                cset_info << arts
+                verbiage << " associated with Artifacts: %s"
+            end
+            @log.debug(verbiage % cset_info)
+        rescue Exception => ex
+            @log.debug(ex.message)
+            operr = VCSEIF_Exceptions::OperationalError.new(ex.message)
+            @operational_errors += 1
+            raise operr, ex.message.to_s
+        end
+
+        # add the Change records for the adds, mods and dels...
+        changes = {'A' => adds, 'M' => mods, 'D' => dels}
+        changes.each_pair do |action, files|
+            files.each do |fileinfo|
+                fn  = fileinfo[:file] || ""
+                uri = fileinfo[:link] || ""
+##
+##                ci = ["Changeset: #{changeset.ObjectID}",
+##                      "   Action: #{action}  PathAndFilename: #{fn}",
+##                      "      Uri: #{uri}"
+##                     ]
+##                puts "candidate Change info:\n    %s" % ci.join("\n    ")
+##
+                chg_rec = {'Changeset'       => changeset._ref,
+                           'Action'          => action,
+                           'PathAndFilename' => fn,
+                           'Uri'             => uri
+                          }
+                begin
+                    change = @rally.create(:change, chg_rec)
+                    info = [change.ObjectID, action, fn, uri]
+                    blurb = "    Change %s created for %s %s  URI: %s"
+                    @log.debug(blurb % info)
+                rescue Exception => ex
+                    operr = VCSEIF_Exceptions::OperationalError.new(ex.message)
+                    @operational_errors += 1
+                    raise operr, ex.message.to_s
+                end
+            end
+        end
+
+        # call another method to attempt to update the artifacts with info in action_targets
+        if @config['UpdateArtifactState'] and action_targets
+             #showArtifacts(action_targets, artifacts)
+            updateArtifacts(action_targets, artifacts)
+        end
+
+        #we have to do the read since the changes are not on there with the original ref
+        return changeset.read
+    end
+
+    def postCreate(artifact)
+        """
+            Either flesh this out here or override in a subclass to provide 
+            processing after the Changeset has been created in Rally.
+        """
+        return artifact
+    end
+
+
+    public
+    def changesetExists?(revision_ident)
+        """
+            Issue a query against Changeset to obtain the Changeset identified by revision_ident.
+            Return a boolean indication of whether such an item exists in repository_name.
+        """
+        criterion1 = 'SCMRepository.Name = "%s"' % @repository_name
+        criterion2 = 'Revision = %s'             % revision_ident
+        criteria   = '((%s) AND (%s))' % [criterion1, criterion2]
+        
+        query = RallyAPI::RallyQuery.new({:type   => :changeset, 
+                                          :fetch  => "Revision,CommitTimestamp,SCMRepository,Name",
+                                          :workspace => @workspace
+                                         })
+        query.query_string = criteria
+        begin
+            result = @rally.find(query)
+        rescue => ex
+            @log.debug(ex.message)
+            problem = "Unable to complete Rally query regarding existence of Changeset '%s'" % revision_ident
+            operr = VCSEIF_Exceptions::OperationalError.new(problem)
+            @operational_errors += 1
+            raise operr, problem
+        end
+        exists = false
+        exists = true if not result.nil? and result.total_result_count > 0
+        return exists
+    end
+
+
+    def getArtifacts(targets)
+        """
+            For now this is brute force requiring a thump on the Rally endpoint for each artifact FormattedID.
+            TODO: consider caching for quicker turnaround and killing the duplicative queries.
+        """
+        artifacts = []
+        targets.each do |target|
+            prefix = target.gsub(/\d/, '')
+            rally_entity_type = @artifact_type[prefix].downcase.to_sym
+            query = RallyAPI::RallyQuery.new(:type  => rally_entity_type,
+                                             :fetch => "ObjectID,Name,FormattedID,ScheduleState,State",
+                                             :workspace => @wksp)
+            query.query_string = '(FormattedID = %s)' % target
+            begin
+                results = @rally.find(query)
+            rescue Exception => ex
+                # TODO: determine if setting missing to the text here is accurate,
+                #       we should only hit this if the Rally WSAPI call fails,
+                #       if there is no such Artifact, the query should return with empty results
+                missing = "No such Artifact: '%s' found in Rally for workspace: %s"
+                @log.warning(missing % [target, @workspace_name])
+            end
+            if !results.nil? and results.total_result_count > 0
+                artifact = results.first
+                @log.debug("artifact obtained: %s" % artifact.FormattedID)
+                artifacts << artifact
+            end
+            
+        end
+        return artifacts
+    end
+
+    def getRallyUsers(attributes=nil)
+        """
+            Run a REST get against Rally using @rally to get User information for all Rally
+            users in the currently scoped workspace and populate a cache keyed by the transform
+            lookup target with the UserName as the value for each key.
+            This makes it a snap to service the lookup method, we just have to consult the cache.
+        """
+        fetch_fields = "_ref,UserName"
+        attributes.gsub(/UserName,?/, '') if !attributes.nil? and attributes =~ /UserName/
+        fetch_fields += "," + attributes  if !attributes.nil? and !attributes.empty?
+        fetch_fields += ",DisplayName"    if fetch_fields !~ /DisplayName/
+        query = RallyAPI::RallyQuery.new(:type => :user, :fetch => fetch_fields)
+        begin 
+            results = @rally.find(query)
+        rescue Exception => ex
+            if @log and @log.respond_to?('error')
+                @log.error("Unable to retrieve User information from Rally")
+            end
+            raise
+        end
+       
+        results.each do |user|
+            urec = {}
+            urec["ref"] = user.send("_ref")
+            if not attributes.nil?
+                for attr_name in attributes.split(',') do
+                    urec[attr_name] = user.send(attr_name)
+                end
+            end
+            urec['UserName']    = user.send('UserName')    if not urec.has_key?('UserName')
+            urec['DisplayName'] = user.send('DisplayName') if not urec.has_key?('DisplayName')
+            @user_cache[urec['UserName']] = urec
+            if @log and @log.respond_to?('debug')
+                @log.debug("user cache item |%s|" % urec['UserName'])
+            end
+        end
+        return @user_cache.dup  # let caller have their own copy of the @user_cache
+    end
+
+
+    private
+    def isCompletedTask?(art_type, target_field, action)
+        """
+            Convenience method
+        """
+        return (art_type == 'Task' and target_field == 'State' and action == 'Completed')
+    end
+
+
+    def showArtifacts(action_targets, artifacts)
+        """
+            Go through the action_targets Hash processing only those entries with a non-nil key.
+
+        """
+        for action, targets in action_targets.each_pair do
+            next if action.nil?
+            targets = action_targets[action]
+            for target in targets do
+                artifact = artifacts.select { |art| art.FormattedID == target }
+                next if artifact.length == 0
+
+                prefix = target.gsub(/\d/, '')
+                begin
+                     target_field = 'ScheduleState' if artifact.ScheduleState
+                rescue
+                     target_field = 'State'
+                end
+                upd_rec = { 'FormattedID' => target, target_field => action }
+                if isCompletedTask?(@artifact_type[prefix], target_field, action)
+                    upd_rec['ToDo'] = 0
+                end
+            end
+        end
+    end
+
+
+    def updateArtifacts(action_targets, artifacts)
+        """
+            Go through the action_targets Hash processing only those entries with a non-nil key.
+
+            This may be the right point at which to qualify for update based on the action word.
+            However, as an action word can be associated with multiple targets that may not be
+            the same artifact type, this might be a bit dicey. For now, go with the shotgun...
+
+        """
+        actions = action_targets.keys.select {|key| key != nil}
+        @log.debug( "updateArtifacts has %d actions" % actions.length)
+        for action in actions do
+            targets = action_targets[action]
+            @log.debug( "updateArtifacts has %d artifacts to %s" % [targets.length, action])
+             for target in targets do
+                @log.debug("updateArtifacts target: %s" % target)
+                prefix = target.gsub(/\d/, '')
+                target_artifacts = artifacts.select {|art| art.FormattedID == target}
+                if target_artifacts.empty?
+                    @log.debug("   there are no target artifacts")
+                    next
+                end
+                artifact = target_artifacts.first
+                target_field = 'State'
+                target_field = 'ScheduleState' if not ['defect', 'task'].include?(@artifact_type[prefix].downcase)
+                debug_info = "updateArtifacts to assign %s %s as |%s|"
+                @log.debug(debug_info % [artifact.FormattedID, target_field, action])
+                upd_rec = { 'FormattedID' => target, target_field => action }
+                if isCompletedTask?(@artifact_type[prefix], target_field, action)
+                    upd_rec['ToDo'] = 0
+                end
+                @log.info("Updating %s %s field with value of %s" % [target, target_field, action])
+                debug_info = "attempting to update %s with %s" % [@artifact_type[prefix], upd_rec]
+                @log.debug(debug_info)
+                rally_entity_type = @artifact_type[prefix].downcase.to_sym
+                begin
+                    updated = @rally.update(rally_entity_type, artifact.ObjectID, upd_rec)
+                rescue Exception => ex
+##
+##                    puts "Exception detected in updateArtifacts, line 874, %s" % ex.message
+##                    puts "   action value: #{actions}"
+##                    puts "  targets value: #{targets}"
+##                    puts "  target  value triggering exception: #{target}"
+##                    NOTE: last used in July 2012
+##
+                    operr = VCSEIF_Exceptions::OperationalError.new(ex.message)
+                    @operational_errors += 1
+                    raise operr, ex.message
+                end
+                debug_info = "After update, %s %s %s field has value of |%s|" % \
+                         [@artifact_type[prefix], updated.FormattedID, 
+                          target_field, updated.send(target_field)]
+                @log.debug(debug_info) 
+            end
+        end
+    end
+
+    public
+    def extractArtifactFormattedIDs(message)
+        %{
+            A brute force method to extract what look to be Rally Artifact FormattedID values
+            from within the message.  
+            The algorithm is to replace any comma chars with a single space, any 
+            colon with a single space, any semi-colon with a single space, 
+            any '.' char with a single space, any '-' char with a single space  and 
+            then split the message on whitespace, resulting in a list of "word" tokens.
+            The token list is then subjected to conformance with a pattern for FormattedID 
+            fof the types of artifacts that are listed in the configuration.
+            Returns the qualified list of tokens that are indeed validly constructed Rally FormattedIDs 
+             (although this method makes no attempt to determine that an artifact actually exists for 
+              each FormattedID candidate).
+         }
+        washed_message = message.gsub(',', ' ').gsub(':', ' ').gsub(';', ' ').gsub('.', ' ').gsub('-', ' ')
+        message_words = washed_message.split()
+        artifact_ids = message_words.select {|token| @valid_artifact_pattern.match(token)}
+        @log.debug("candidate FormattedIDs: %s" % artifact_ids.join(", "))
+        return artifact_ids.sort
+    end
+
+end