taskjuggler 0.0.4 → 0.0.5

data/lib/SheetReceiver.rb

@@ -0,0 +1,355 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = SheetReceiver.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009, 2010 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'digest/md5'
+require 'mail'
+require 'open4'
+require 'yaml'
+require 'SheetHandlerBase'
+
+class TaskJuggler
+
+  class SheetReceiver < SheetHandlerBase
+
+    def initialize(appName, type)
+      super(appName)
+
+      @sheetType = type
+      # The following settings must be set by the deriving class.
+      # Sheet type specific option for tj3client
+      @tj3clientOption = nil
+      # Base directory to store received sheets
+      @sheetDir = nil
+      # Base directory where to find the resource file.
+      @templateDir = nil
+      # Directory to store the failed emails.
+      @failedMailsDir = nil
+      # Directory to store the failed sheets
+      @failedSheetsDir = nil
+      # File that holds the acceptable signatures.
+      @signatureFile = nil
+      # The log file
+      @logFile = nil
+
+      # Regular expressions to identify a status sheet.
+      @sheetHeader = /^[ ]*statussheet\s([a-z][a-z0-9_]*)\s([0-9]*-[0-9]*-[0-9]*)/
+      # Regular expression to extract the sheet signature (date).
+      @signatureFilter = /^[ ]*statussheet\s[a-z][a-z0-9_]*\s([0-9:\-+]*)/
+      # The email address of the submitter of the sheet.
+      @submitter = nil
+      # The resource ID of the submitter.
+      @resourceId = nil
+      # The stdout content from tj3client
+      @report = nil
+      # The stderr content from tj3client
+      @warnings = nil
+
+      # The extracted sheet text.
+      @sheet = nil
+      # Will indicate whether the sheet was attached or in mail body
+      @sheetWasAttached = true
+      # The end date of the reporting period.
+      @date = nil
+      # The id of the incomming message.
+      @messageId = nil
+    end
+
+    # Read the sheet from $stdin in email format. Extract the sheet from the
+    # attachments or body and check it. If ok, send back a summary, otherwise
+    # the error message.
+    # The actual check is done by a tj3 server process that is accessed via
+    # tj3client.
+    def processEmail
+      setWorkingDir
+
+      createDirectories
+
+      mail = Mail.new($stdin.read)
+
+      # Who sent this email?
+      @submitter = mail.from.respond_to?('[]') ? mail.from[0] : mail.from
+      # Getting the message ID.
+      @messageId = mail.message_id || 'unknown'
+      @idDigest = Digest::MD5.hexdigest(@messageId)
+      info("Processing #{@sheetType} mail from #{@submitter} " +
+           "with ID #{@messageId} (#{@idDigest})")
+
+      # Store the mail in the failedMailsDir in case something goes wrong.
+      File.open("#{@failedMailsDir}/#{@idDigest}", 'w') do |f|
+        f.write(mail)
+      end
+
+      # First we search the attachments and then the body.
+      mail.attachments.each do |attachment|
+        # We are looking for an attached file with a .tji extension.
+        fileName = attachment.filename
+        next unless fileName && fileName[-4..-1] == '.tji'
+
+        # Further inspect the attachment. If we could process it, we are done.
+        return true if processSheet(attachment.body.decoded)
+      end
+      # None of the attachements worked, so let's try the mail body.
+      @sheetWasAttached = false
+      return true if processSheet(mail.body.decoded)
+
+      error(<<"EOT"
+No #{@sheetType} sheet found in email. Please make sure the header syntax is
+correct and contained in a single line that starts at the begining of the
+line. If you had the #{@sheetType} sheet attached, the file name must have a
+'.tji' extension to be found.
+EOT
+           )
+    end
+
+    private
+
+    # Isolate the actual syntax from _sheet_ and process it.
+    def processSheet(sheet)
+      # Store the detected sheet so we can include it with error reports if
+      # needed.
+      @sheet = cutOut(fixLineBreaks(sheet))
+      # A valid sheet must have the poper header line.
+      if @sheetHeader.match(@sheet)
+        checkSignature(@sheet)
+        # Extract the resource ID and the end date from the sheet.
+        matches = @sheetHeader.match(@sheet)
+        @resourceId, @date = matches[1..2]
+        # Email answers will only go the email address on file!
+        @submitter = getResourceEmail(@resourceId)
+        info("Found #{@sheetWasAttached ? 'attached ' : ''}sheet for " +
+             "#{@resourceId} dated #{@date}")
+        # Ok, found. Now check the full sheet.
+        if checkSheet(@sheet)
+          # Everything is fine. Store it away.
+          fileSheet(@sheet)
+          # Remove the mail from the failedMailsDir
+          File.delete("#{@failedMailsDir}/#{@idDigest}")
+          info("Accepted sheet for #{@resourceId} dated #{@date}")
+          return true
+        end
+      end
+    end
+
+    def checkSheet(sheet)
+      err = ''
+      status = nil
+      begin
+        # Save a copy of the sheet for debugging purposes.
+        File.open("#{@failedSheetsDir}/#{@resourceId}-#{@date}.tji", 'w') do |f|
+          f.write(sheet)
+        end
+        command = "tj3client --silent #{@tj3clientOption} #{@projectId} ."
+        status = Open4.popen4(command) do |pid, stdin, stdout, stderr|
+          # Send the report to the tj3client process via stdin.
+          stdin.write(sheet)
+          stdin.close
+          @report = stdout.read
+          @warnings = stderr.read
+        end
+      rescue
+        fatal("Cannot check #{@sheetType} sheet: #{$!}")
+      end
+      if status.exitstatus == 0
+        File.delete("#{@failedSheetsDir}/#{@resourceId}-#{@date}.tji")
+        return true
+      end
+
+      # The exit status was not 0. The stderr output should not be empty and
+      # will contain error and warning messages.
+      error(@warnings)
+    end
+
+    def fileSheet(sheet)
+      # Create the appropriate directory structure if it doesn't exist.
+      dir = "#{@sheetDir}/#{@date}"
+      fileName = "#{dir}/#{@resourceId}_#{@date}.tji"
+      newDir = false
+      begin
+        unless File.directory?(dir)
+          Dir.mkdir(dir)
+          addToScm('Adding new directory', dir)
+          newDir = true
+        end
+        File.open(fileName, 'w') { |f| f.write(sheet) }
+        addToScm("Adding/updating #{fileName}", fileName)
+      rescue
+        fatal("Cannot store #{@sheetType} sheet #{fileName}: #{$!}")
+        return
+      end
+
+      # Create or update the file that includes all *.tji in the directory.
+      generateInclusionFile(dir)
+
+      if newDir
+        # Add the new directory to the parent all.tji file.
+        allFile = "#{@sheetDir}/all.tji"
+        File.open(allFile, 'a') do |f|
+          f.write("\ninclude '#{@date}/all.tji' { }")
+        end
+        addToScm('Adding new directory to all.tji', allFile)
+      end
+
+      text = <<"EOT"
+Report from #{getResourceName} for the period ending #{@date}:
+
+EOT
+
+      # Add warnings if we had any.
+      unless @warnings.empty?
+        text += <<"EOT"
+Your report does contain some issues that you may want to fix or address with
+your manager or project manager:
+
+#{@warnings}
+
+EOT
+      end
+
+      # Append the pretty printed version of the submitted status sheet.
+      text += @report
+
+      # Send out the email.
+      sendEmail(@submitter, "Report from #{getResourceName} for #{@date}", text,
+                nil, nil, @messageId)
+      true
+    end
+
+    # Generate or update a file the contains 'include' statements for all the
+    # .tji files in the provided directory. The generated file will be in this
+    # directory as well.
+    def generateInclusionFile(dir)
+      pwd = Dir.pwd
+      begin
+        Dir.chdir(dir)
+        File.open('all.tji', 'w') do |file|
+          Dir.glob('*.tji').each do |tji|
+            file.puts("include '#{tji}' { }") unless tji == 'all.tji'
+          end
+        end
+      rescue
+        error("Can't create inclusion file: #{$!}")
+      ensure
+        Dir.chdir(pwd)
+      end
+      # Report the change to the SCM handler.
+      addToScm('Adding/updating summary include file.', "#{dir}/all.tji")
+    end
+
+    def checkSignature(sheet)
+      if matches = @signatureFilter.match(sheet)
+        interval = matches[1]
+      else
+        fatal("No #{@sheetType}sheet header found")
+      end
+
+      acceptedSignatures = []
+      if File.exist?(@signatureFile)
+        File.open(@signatureFile, 'r') do |file|
+          acceptedSignatures = file.readlines
+        end
+        acceptedSignatures.map! { |s| s.chomp }
+        acceptedSignatures.delete_if { |s| s.chomp.empty? }
+      else
+        error("#{@signatureFile} does not exist yet.")
+      end
+
+      unless acceptedSignatures.include?(interval)
+        error(<<"EOT"
+The reporting period #{interval}
+was not accepted!  Either you have modified the sheet header,
+you are submitting the sheet too late or too early.
+EOT
+             )
+      end
+    end
+
+    def createDirectories
+      [ @sheetDir, @failedMailsDir, @failedSheetsDir ].each do |dir|
+        unless File.directory?(dir)
+          info("Creating directory #{dir}")
+          Dir.mkdir(dir)
+        end
+      end
+    end
+
+    def error(message)
+      $stderr.puts message if @outputLevel >= 1
+
+      log('ERROR', "#{message}") if @logLevel >= 1
+
+      # Append the submitted sheet for further tries. We may run into encoding
+      # errors here. In this case we send the answer without the incoming time
+      # sheet.
+      begin
+        message += "\n" + @sheet if @sheet && !@sheetWasAttached
+      rescue
+      end
+
+      sendEmail(@submitter, 'Your time sheet submission failed!', message)
+
+      exit 1
+    end
+
+    def fatal(message)
+      log('FATAL', "#{message}")
+
+      # Append the submitted sheet for further tries.
+      message += "\n" + @sheet if @sheet
+
+      sendEmail(@submitter, 'Temporary server error', <<"EOT"
+We are sorry! The #{@sheetType} sheet server detected a configuration
+problem and is temporarily out of service. The administrator
+has been notified and will try to rectify the situation as
+soon as possible. Please re-submit your #{@sheetType} sheet later!
+EOT
+               )
+      exit 1
+    end
+
+
+    # Load tye resources.yml YAML file into the @resourceList variable.
+    # The format is Array with one entry per resource. The entry is an Array
+    # with 3 fields: ID, name and email. All fields are String objects.
+    def getResourceList
+      fatal('@date not set') unless @date
+
+      fileName = "#{@templateDir}/#{@date}/resources.yml"
+      begin
+        @resourceList = YAML.load(File.read(fileName))
+        info("#{@resourceList.length} resources loaded")
+      rescue
+        error("Cannot read resource file #{fileName}: #{$!}")
+      end
+      @resourceList
+    end
+
+    def getResourceEmail(id = @resourceId)
+      getResourceList unless @resourceList
+
+      @resourceList.each do |resource|
+        return resource[2] if resource[0] == id
+      end
+      error("Resource ID '#{id}' not found in list")
+    end
+
+    def getResourceName(id = @resourceId)
+      getResourceList unless @resourceList
+
+      @resourceList.each do |resource|
+        return resource[1] if resource[0] == id
+      end
+      error("Resource ID '#{id}' not found in list")
+    end
+
+  end
+
+end

data/lib/SheetSender.rb

@@ -0,0 +1,264 @@
+#!/usr/bin/env ruby -w
+# encoding: UTF-8
+#
+# = SheetSender.rb -- The TaskJuggler III Project Management Software
+#
+# Copyright (c) 2006, 2007, 2008, 2009, 2010 by Chris Schlaeger <cs@kde.org>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+#
+
+require 'open4'
+require 'mail'
+require 'yaml'
+require 'SheetHandlerBase'
+
+class TaskJuggler
+
+  # A base class for sheet senders.
+  class SheetSender < SheetHandlerBase
+
+    attr_accessor :force, :intervalDuration
+
+    def initialize(appName, type)
+      super(appName)
+
+      @sheetType = type
+      # The following settings must be provided by the deriving class.
+      # This is a LogicalExpression string that controls what resources should
+      # not be getting a report sheet template.
+      @hideResource = nil
+      # This file contains the signature (date or interval) that the
+      # SheetReceiver will accept as a valid signature.
+      @signatureFile = nil
+      # The base directory of the sheet templates.
+      @templateDir = nil
+      # When true, existing templates will be regenerated and send out again.
+      # Otherwise the existing template will not be send out again.
+      @force = false
+
+      @signatureFilter = nil
+      @introText = nil
+
+      # The end date of the reported interval.
+      @date = Time.new.strftime('%Y-%m-%d')
+      # Determines the length of the reported interval.
+      @intervalDuration = '1w'
+      # We need this to determine if we already sent out a report.
+      @timeStamp = Time.new
+    end
+
+    # Send out report templates to a list of project resources. The resources
+    # are selected by the @hideResource filter expression and can be further
+    # limited with a list of resource IDs passed by _resourceList_.
+    def sendTemplates(resourceList)
+      setWorkingDir
+      createDirectories
+
+      resources = genResourceList(resourceList)
+      genTemplates(resources)
+      sendReportTemplates(resources)
+    end
+
+    private
+
+    def createDirectories
+      unless File.directory?(@templateDir)
+        warning("Creating directory #{@templateDir}")
+        Dir.mkdir(@templateDir)
+      end
+      @templateDir += "/#{@date}"
+      unless File.directory?(@templateDir)
+        Dir.mkdir(@templateDir)
+      end
+    end
+
+    def genResourceList(resourceList)
+      list = []
+      info('Retrieving resource list...')
+      reportDef = <<"EOF"
+resourcereport rl_21497214 '.' {
+  formats csv
+  columns id, name, email, effort, freework
+  hideresource #{@hideResource}
+  sortresources id.up
+  loadunit days
+  period %{#{@date} - 1w} +1w
+}
+EOF
+      report = generateReport('rl_21497214', reportDef)
+      first = true
+      report.each_line do |line|
+        if first
+          first = false
+          next
+        end
+        id, name, email, effort, free = line.split(';')
+        if email.empty?
+          error("Resource '#{id}' must have a valid email address")
+        end
+        # Convert effort and free values into Float objects.
+        effort = effort.to_f
+        free = free.to_f
+
+        # Ignore resources that are on vacation for the whole period.
+        if effort == 0.0 && free == 0.0
+          info("Resource '#{id}' was on vacation the whole period")
+          next
+        end
+
+        list << [ id, name, email, effort, free ]
+      end
+
+      # Save the resource list to a file. We'll need it in the receiver again.
+      begin
+        fileName = @templateDir + '/resources.yml'
+        File.open(fileName, 'w') do |file|
+          YAML.dump(list, file)
+        end
+      rescue
+        error("Saving of #{fileName} failed: #{$!}")
+      end
+
+      unless resourceList.empty?
+        # When the user specified resource list is empty, we generate templates
+        # for all users that don't match the @hideResource filter. Otherwise we
+        # only generate templates for those in the list and that are not hidden
+        # by the filter.
+        list.delete_if { |item| !resourceList.include?(item[0]) }
+      end
+
+      error('genResourceList: list is empty') if list.empty?
+
+      info("#{list.length} resources found")
+      list
+    end
+
+    def genTemplates(resources)
+      firstTemplateFile = nil
+      resources.each do |resInfo|
+        res = resInfo[0]
+        info("Generating template for #{res}...")
+        reportId = "sheet_template_#{res}"
+        templateFile = "#{@templateDir}/#{res}_#{@date}"
+        # We use the first template file to get the sheet interval.
+        firstTemplateFile = templateFile + '.tji' unless firstTemplateFile
+
+        # Don't re-generate already existing templates unless we are in force
+        # mode. We probably have sent them out earlier with a manual trigger.
+        if !@force && File.exist?(templateFile + '.tji')
+          info("Skipping already existing #{templateFile}.tji.")
+          next
+        end
+
+        reportDef = <<"EOT"
+#{@sheetType}sheetreport #{reportId} \"#{templateFile}\" {
+  hideresource ~(plan.id = \"#{res}\")
+  period %{#{@date} - #{@intervalDuration}} +#{@intervalDuration}
+  sorttasks id.up
+}
+EOT
+        generateReport(reportId, reportDef)
+      end
+      enableSignatureForReporting(firstTemplateFile)
+    end
+
+    def sendReportTemplates(resources)
+      resources.each do |id, name, email|
+        attachment = "#{@templateDir}/#{id}_#{@date}.tji"
+        unless File.exist?(attachment)
+          error("sendReportTemplates: " +
+                "#{@sheetType} sheet #{attachment} for #{name} not found")
+        end
+        # Don't send out old templates again. @timeStamp has a higher
+        # resolution. We add 1s to avoid truncation errors.
+        if (File.mtime(attachment) + 1) < @timeStamp
+          info("Old template #{attachment} found. Not sending it out.")
+          next
+        end
+
+        message = " Hello #{name}!\n\n#{@introText}" + File.read(attachment)
+
+        sendEmail(email, "Your weekly report template for #{@date}",
+                  message, attachment)
+      end
+    end
+
+    def enableSignatureForReporting(templateFile)
+      signature = nil
+      # That's a pretty bad hack to make reasonably certain that the tj3 server
+      # process has put the complete file into the file system.
+      i = 0
+      begin
+        if File.exist?(templateFile)
+          File.open(templateFile, 'r') do |file|
+            while (line = file.gets)
+              if matches = @signatureFilter.match(line)
+                signature = matches[1]
+              end
+            end
+          end
+        end
+        i += 1
+        # If the file doesn't exist yet or the cannot yet be read, wait for
+        # 300ms. We try this 100 times.
+        sleep(0.3) unless signature
+      end while signature.nil? && i < 100
+      unless signature
+        error("enableSignatureForReporting: Cannot find signature in file " +
+              "#{templateFile}")
+      end
+
+      acceptedSignatures = []
+      if File.exist?(@signatureFile)
+        File.open(@signatureFile, 'r') do |file|
+          acceptedSignatures = file.readlines
+        end
+        acceptedSignatures.map! { |s| s.chomp }
+        acceptedSignatures.delete_if { |s| s.chomp.empty? }
+      else
+        info("#{@signatureFile} does not exist yet.")
+      end
+      unless acceptedSignatures.include?(signature)
+        # Add the new signature
+        info("Adding #{signature} to #{@signatureFile}")
+        acceptedSignatures << signature
+        # And write back the adapted file.
+        File.open(@signatureFile, 'w') do |file|
+          acceptedSignatures.each do |iv|
+            file.write("#{iv}\n")
+          end
+        end
+      else
+        info("Signature #{signature} is already listed in #{@signatureFile}")
+      end
+    end
+
+    def generateReport(id, reportDef)
+      out = ''
+      err = ''
+      begin
+        command = "tj3client --silent report #{@projectId} #{id} = ."
+        status = Open4.popen4(command) do |pid, stdin, stdout, stderr|
+          # Send the report definition to the tj3client process via stdin.
+          stdin.write(reportDef)
+          stdin.close
+          # Retrieve the output
+          out = stdout.read
+          err = stderr.read
+        end
+        if status.exitstatus != 0
+          error("generateReport: #{err}")
+        end
+      rescue
+        error("generateReport: Report generation failed: #{$!}")
+      end
+      out
+    end
+
+  end
+
+end
+