echi-converter 0.4.2 → 0.4.4

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/reports
+.yardoc
+doc

data/{History.txt → CHANGELOG}

@@ -226,4 +226,9 @@
 * Minor enhancement(s):
   * Added an option 'echi_use_utc' in application.yml to record all data times in UTC for binary files, true by default
 * Bug fix(es):  
-* Known issue(s):
+* Known issue(s):
+
+== 0.4.4 2012-01-10
+
+* Added Version 16 file format support
+* Fixed requiring logger for newer versions of Ruby

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in ruby_speech.gemspec
+gemspec

data/README.md

@@ -0,0 +1,184 @@
+The ECHI (External Call History Interface) Converter
+-------------
+
+Provides a Ruby based utility for fetching Avaya CMS / ECHI files in binary/ASCII form from an FTP server, converting them, if necessary, to ASCII and then inserting them into a database via ActiveRecord.  With this utility you only need the standard Avaya CMS Release 13 or better without any additional software or utilities from Avaya, as this utility will process either binary or ASCII output from the Avaya CMS.
+
+Status
+======
+This release is now in production use within Call Centers using the Avaya CMS.  The utility successfully and reliably imports the data provided by the Avaya CMS ECHI into various databases, including Microsoft Sqlserver, Oracle and MySQL.  This provides the repository of call segments that may then be used to provide detailed Cradle to Grave reporting for the call center.
+
+Features
+========
+The utility provides the following capabilities:
+
+  * Support of ActiveRecord (means you may use Oracle, MySQL, MS-SQL, Postgres, DB2, ODBC, etc)
+  * Generate your schema via ActiveRecord Migrations automatically
+  * Fetch Binary or ASCII CSV files from the Avaya CMS platform via FTP
+  * Insert the records into the defined database table using database transactions, via ActiveRecord, on a per file basis to support recovery on failure
+  * Change schema structure via YML configuration file to accommodate various releases of the ECHI format
+  * Supports inserting data from the various '.dat' files provided by the Avaya CMS into associated tables
+  * Runs as a daemon (via fork) on Posix (*NIX) and a service on Windows
+  * Has a watchdog process on Posix or you may set a service watch on Windows
+  * Allows for multiple FTP sessions to be used for greater performance
+
+Table names:
+
+  * echi_records - stores all ECHI data
+  * echi_logs - stores a log entry for each file processed
+  * echi_acds - stores the data from the acd.dat file
+  * echi_agents - stores the data from the agname.dat file
+  * echi_aux_reasons - stores the data from the aux_rsn.dat file
+  * echi_cwcs - stores data from the cwc.dat file
+  * echi_splits - stores data from the split.dat file
+  * echi_trunk_groups - stores data from the tkgrp.dat file
+  * echi_vdns - stores data from the vdn.dat file
+  * echi_vectors - stores data from the vector.dat file
+
+What ECHI-Converter is not
+=============
+* A reporting engine
+* A set of database maintenance scripts
+
+Requirements
+============
+* [Ruby v1.8.6+](http://www.ruby-lang.org/)
+* [Rubygems v1.2+](http://www.rubygems.org/)
+* [ActiveRecord v2.1+](http://activerecord.rubyforge.org/)
+* [ActiveSupport v2.1+](http://activesupport.rubyforge.org/)
+* [Daemons v1.0.10+](http://daemons.rubyforge.org/)
+* [FasterCSV v1.2.3+](http://fastercsv.rubyforge.org/)
+* [Rake v0.8.1+](http://rake.rubyforge.org/)
+* [UUIDTools v1.0.3+](http://sporkmonger.com/projects/uuidtools/)
+* [Win32-service v.0.6.1+](http://win32utils.rubyforge.org/) (Manual install for Windows only)
+* Avaya CMS ECHI Release 12+ enabled and configured to send to an FTP server
+
+Installing
+==========
+    `gem install echi-converter`
+
+Setup
+=====
+First, create the directory with all of the project files where you will run this application from:
+
+    `echi-converter create myproject`
+
+Once you have installed a project into your preferred directory, you then need to configure for your environment.  The first step is to modify each of these files:
+
+  * config/application.yml
+    * Change each of the 'echi' settings for connecting to your local FTP server where the CMS puts the ASCII/binary files
+    * Select which schema you would like to use (ie - extended_version12.yml) based on what you have in place
+  * config/database.yml
+    * Change to match your local database and database login credentials, full ActiveRecord support
+    * Note: Your database user and database must exist before running rake, as rake will then create the schema
+
+Once this is complete, then simply run these commands from the project directory:
+
+  * rake migrate (creates the tables required for the system)
+  * echi-converter (starts the server daemon, refer to its usage)
+
+Note:  When using a Windows FTP server, you must configure the FTP server to provide a UNIX directory listing format.
+
+Usage
+======
+* echi-converter create myproject - create the local project to run the ECHI converter from
+* echi-converter upgrade myproject - location of project to upgrade after a new gem is installed
+
+For POSIX (*NIX):
+
+* echi-converter run myproject - Run the ECHI converter interactively from the location given
+* echi-converter start myproject - Start the ECHI converter in daemon mode from the location given
+* echi-converter stop myproject - Stop the ECHI converter daemon
+* echi-converter restart myproject - Restart the ECHI converter
+* echi-converter zap myproject - If there has been an unexpected close and the system still thinks the converter is running, clean up the pid files
+
+For MS-Windows:
+
+* echi-converter install myproject - install the service (must specify complete path such as c:\path\to\my\project - if the directory name or path has any spaces, please enclose the "myproject" in double quotes )
+* echi-converter start - start the service
+* echi-converter stop - stop the service
+* echi-converter pause - pause the service
+* echi-converter resume - resume the service
+* echi-converter status - returns the status of a configured service
+* echi-converter delete - delete the service"
+
+* If you would like to run the script interactively, you may also execute this command:
+** ruby "c:\myproject\lib\main_win32.rb"
+
+Multi-byte character support:
+
+* If you require multi-byte character support be sure to set your database to 'utf8' as well as uncomment the option 'encoding: utf8' in the config/database.yml file
+
+Demonstration of usage
+================
+Start the daemon/service:
+
+    `echi-converter start myproject`
+
+Stop the daemon/service:
+
+    `echi-converter stop myproject`
+
+Supported Platforms
+==================
+While the use of Ruby allows for operation on a multitude of platforms, these are the platforms that have actually been tested on.  If you have success running on other platforms, please feel free to provide details on the Google Group.
+
+Operating Systems
+===============
+* POSIX
+* Windows XP SP2
+* Windows 2000
+* Windows 2003
+
+Databases
+=========
+* MySQL
+* Microsoft Sqlserver
+* DB2
+* Sqlite3
+* Postgres
+* Oracle
+
+FTP Servers
+============
+* VSFTP
+* Windows 2003/XP FTP Servers (When using a Windows FTP server, you must configure the FTP server to provide a UNIX directory listing format.)
+
+Related Avaya Documentation for ECHI
+==============
+* [Avaya Call Management System Release 14 External Call History Interface](http://support.avaya.com/elmodocs2/cms/R14/ECHI.pdf)
+* [Avaya Call Management System Release 13 External Call History Interface](http://support.avaya.com/elmodocs2/cms_r13_1/07-300737_ECHI.pdf)
+
+Screencast
+============
+You may view the screencast on howto install and use the ECHI-Converter [here](http://www.screencast.com/t/lQQkIVkUZMr).
+
+Consulting Services
+=============
+If you would like help installing, configuring or adding features please do not hesitate to contact the consulting services of Adhearsion [here](http://www.adhearsion.com/consulting).
+
+Forum
+======
+Please report questions on the [Google Group](http://groups.google.com/group/echi-converter)
+Please report bugs on the [Bug tracker](https://github.com/mojolingo/echi-converter/issues)
+
+Changelog
+======
+View the [changelog](https://github.com/mojolingo/echi-converter/blob/master/CHANGELOG)
+
+How to submit patches
+==============
+* Read the [8 steps for fixing other people's code](http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/)
+* Submit a pull request on github
+
+License
+========
+This code is free to use under the terms of the LGPL license.
+
+Contact
+========
+Comments are welcome. Send an email to [echi [at] mojolingo.com](mailto:echi@mojolingo.com).
+
+Brought to you by
+=================
+* [Adhearsion](http://www.adhearsion.com), the open-source, unconventional voice framework that ties technologies together neatly.
+* [Mojo Lingo](http://www.mojolingo.com), voice applications that work like magic!

data/Rakefile

@@ -1,152 +1,26 @@
 require 'rubygems'
 require 'rake'
-require 'rake/clean'
-require 'rake/testtask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
-require 'rake/rdoctask'
-require 'rake/contrib/rubyforgepublisher'
-require 'fileutils'
-require 'hoe'
-require 'active_record'  
+require 'logger'
+require 'active_record'
 require 'yaml'
 
-include FileUtils
-require File.join(File.dirname(__FILE__), 'lib', 'echi-converter', 'version')
+require 'yard'
+YARD::Rake::YardocTask.new
 
-AUTHOR = 'Jason Goecke'  # can also be an array of Authors
-EMAIL = "jason [at] goecke.net"
-DESCRIPTION = "ECHI Conversion Utility - Provides a utility to fetch Avaya CMS / ECHI binary files, convert them and insert into a database table via ActiveRecord"
-GEM_NAME = 'echi-converter' # what ppl will type to install your gem
-
-@config_file = "~/.rubyforge/user-config.yml"
-@config = nil
-def rubyforge_username
-  unless @config
-    begin
-      @config = YAML.load(File.read(File.expand_path(@config_file)))
-    rescue
-      puts <<-EOS
-ERROR: No rubyforge config file found: #{@config_file}"
-Run 'rubyforge setup' to prepare your env for access to Rubyforge
- - See http://newgem.rubyforge.org/rubyforge.html for more details
-      EOS
-      exit
-    end
-  end
-  @rubyforge_username ||= @config["username"]
-end
-
-RUBYFORGE_PROJECT = 'echi-converter' # The unix name for your project
-HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
-DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
-
-NAME = "echi-converter"
-REV = nil 
-# UNCOMMENT IF REQUIRED: 
-# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
-VERS = EchiConverter::VERSION::STRING + (REV ? ".#{REV}" : "")
-CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
-RDOC_OPTS = ['--quiet', '--title', 'echi-converter documentation',
-    "--opname", "index.html",
-    "--line-numbers", 
-    "--main", "README",
-    "--inline-source"]
-
-class Hoe
-  def extra_deps 
-    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
-  end 
-end
-
-# Generate all the Rake tasks
-# Run 'rake -T' to see list of generated tasks (from gem root directory)
-hoe = Hoe.new(GEM_NAME, VERS) do |p|
-  p.author = AUTHOR 
-  p.description = DESCRIPTION
-  p.email = EMAIL
-  p.summary = DESCRIPTION
-  p.url = HOMEPATH
-  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
-  p.test_globs = ["test/**/test_*.rb"]
-  p.clean_globs |= CLEAN  #An array of file patterns to delete on clean.
-  
-  # == Optional
-  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
-  #p.extra_deps = []     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
-  p.extra_deps = [
-    ['activerecord', '>=1.15.3'],
-    ['activesupport', '>=1.4.2'],
-    ['daemons', '>=1.0.7'],
-    ['fastercsv', '>=1.2.0'],
-    ['hoe', '>=1.3.0'],
-    ['rake', '>=0.7.3'],
-    ['uuidtools', '>=1.0.1']
-  ]
-  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
-end
-
-CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
-PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
-hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+##Add the ability to use ActiveRecord Migrations to create the database
+desc "Migrate the database through scripts in db/migrate. Target specific version with VERSION=x"
+task :migrate => :environment do
+  # Load the working directory and configuration file
+  workingdirectory = File.expand_path(File.dirname(__FILE__))
+  config = YAML::load File.open("#{workingdirectory}/config/application.yml")
 
-desc 'Generate website files'
-task :website_generate do
-  Dir['website/**/*.txt'].each do |txt|
-    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
-  end
-end
+  # Load the configured schema
+  @@echi_schema = YAML::load File.open(File.join(workingdirectory, "config", config["echi_schema"]))
 
-desc 'Upload website files to rubyforge'
-task :website_upload do
-  host = "#{rubyforge_username}@rubyforge.org"
-  remote_dir = "/var/www/gforge-projects/#{PATH}/"
-  local_dir = 'website'
-  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+  ActiveRecord::Migrator.migrate 'db/migrate', ENV["VERSION"] ? ENV["VERSION"].to_i : nil
 end
 
-desc 'Generate and upload website files'
-task :website => [:website_generate, :website_upload, :publish_docs]
-
-desc 'Release the website and new gem version'
-task :deploy => [:check_version, :website, :release] do
-  puts "Remember to create SVN tag:"
-  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
-    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
-  puts "Suggested comment:"
-  puts "Tagging release #{CHANGES}"
+task :environment do
+  ActiveRecord::Base.establish_connection YAML::load(File.open('config/database.yml'))
+  ActiveRecord::Base.logger = Logger.new 'log/database.log'
 end
-
-desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
-task :local_deploy => [:website_generate, :install_gem]
-
-task :check_version do
-  unless ENV['VERSION']
-    puts 'Must pass a VERSION=x.y.z release version'
-    exit
-  end
-  unless ENV['VERSION'] == VERS
-    puts "Please update your version.rb to match the release version, currently #{VERS}"
-    exit
-  end
-end
-
-##Add the ability to use ActiveRecord Migrations to create the database
-desc "Migrate the database through scripts in db/migrate. Target specific version with VERSION=x"  
-  task :migrate => :environment do  
-    #Load the working directoy and configuration file
-    workingdirectory = File.expand_path(File.dirname(__FILE__))
-    configfile = workingdirectory + '/config/application.yml'
-    config = YAML::load(File.open(configfile))
-
-    #Load the configured schema
-    schemafile = workingdirectory + "/config/" + config["echi_schema"]
-    @@echi_schema = YAML::load(File.open(schemafile))
-    
-    ActiveRecord::Migrator.migrate('db/migrate', ENV["VERSION"] ? ENV["VERSION"].to_i : nil )  
-end  
-   
-task :environment do  
-  ActiveRecord::Base.establish_connection(YAML::load(File.open('config/database.yml')))  
-  ActiveRecord::Base.logger = Logger.new(File.open('log/database.log', 'a'))  
-end

data/TODO

@@ -0,0 +1,4 @@
+TODO for echi_converter
+==========================
+- Add SSH/SFTP support
+- Add the ability to export to CSV files as well

data/bin/echi-converter

@@ -3,6 +3,7 @@ require 'rubygems'
 require 'daemons'
 require 'fileutils'
 require 'yaml'
+require 'logger'
 include FileUtils
 
 Signal.trap("INT") do
@@ -10,7 +11,7 @@ Signal.trap("INT") do
   Process.exit
 end
 
-usage = "Usage: 
+usage = "Usage:
   echi-converter create myproject - create the local project to run the ECHI converter from (on Windows, directory names must not have spaces)
   echi-converter upgrade myproject - location of project to upgrade after a new gem version is installed"
 
@@ -30,11 +31,11 @@ if RUBY_PLATFORM["-mswin32"]
      echi-converter status - check the status of a configured service
      echi-converter delete - delete the service"
 else
-  usage = usage + 
+  usage = usage +
     "echi-converter run myproject - Run the ECHI converter interactively from the location given
     echi-converter start myproject - Start the ECHI converter in daemon mode from the location given
     echi-converter stop myproject - Stop the ECHI converter daemon
-    echi-converter restart myproject - Restart the ECHI converter 
+    echi-converter restart myproject - Restart the ECHI converter
     echi-converter zap myproject - If there has been an unexpected close and the system still thinks the converter is running, clean up the pid files"
 end
 
@@ -79,7 +80,7 @@ def create_project dir_name
     end
   rescue => err
     puts err
-    puts 'Fatal...exiting... - ' + err
+    puts 'Fatal...exiting... - ' + err.to_s
     exit
   end
   puts ''
@@ -92,8 +93,8 @@ def upgrade_project project_name
   dest_dir_relative = project_name || Dir.pwd
   dest_dir = File.expand_path dest_dir_relative
   base_dir = File.expand_path File.dirname(__FILE__)
-  
-  begin 
+
+  begin
     echi_install_conf = YAML::load(File.open("#{@echi_gem_loc}/config/install_files.yml"))
     #Copy files
     echi_install_conf["files_to_upgrade"].each do |file|
@@ -153,11 +154,11 @@ end
 
 #Launches dynamically or as a deamon for *NIX platforms
 def launch_project run_type, project_name
-  
+
   #Set various file paths
   pid_directory = project_name + '/log'
   script_path = project_name + '/lib/main.rb'
-  
+
   #Build options to run as a daemon
   options = {
     :app_name => 'echi-converter',
@@ -170,12 +171,12 @@ def launch_project run_type, project_name
     :dir => pid_directory,
     :script => ''
   }
-  
+
   #If set, run interactively and not as a daemon
   if run_type == 'run'
     options["ontop"] = true
   end
-  
+
   #Daemonize
   Daemons.run(script_path, options)
 end
@@ -212,9 +213,9 @@ elsif ARGV[0] == 'run' || ARGV[0] == 'start' || ARGV[0] == 'stop' || ARGV[0] ==
     begin
       launch_project ARGV[0], ARGV[1]
     rescue => err
-      puts 'Failed to launch project: ' + err
+      puts 'Failed to launch project: ' + err.to_s
     end
   end
 else
   puts usage
-end
+end