autotask_ruby 0.1.0

data/autotask_ruby.gemspec

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'autotask_ruby/version'
+
+Gem::Specification.new do |spec|
+    spec.name = 'autotask_ruby'
+    spec.version = AutotaskRuby::VERSION
+    spec.authors = ['Jared L Jennings']
+    spec.email = ['jared@jaredjennings.org']
+
+    spec.summary = 'A ruby client for the Autotask API'
+    spec.description = 'A ruby client for the Autotask API. The client tries to use a full-featured approach.'
+    spec.homepage = 'https://github.com/trepidity/autotask_ruby'
+    spec.license = 'MIT'
+
+    # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+    # to allow pushing to a single host or delete this section to allow pushing to any host.
+    if spec.respond_to?(:metadata)
+        spec.metadata['homepage_uri'] = spec.homepage
+        spec.metadata['source_code_uri'] = 'https://github.com/trepidity/autotask_ruby'
+    else
+        raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+    end
+
+    # Specify which files should be added to the gem when it is released.
+    # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+    spec.files = Dir.chdir(File.expand_path(__dir__)) do
+        `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    end
+    spec.bindir = 'exe'
+    spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+    spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+    spec.require_paths = ['lib']
+
+    spec.add_runtime_dependency 'activesupport', '~> 5.2'
+    spec.add_runtime_dependency 'savon', '~> 2.12'
+
+    spec.add_development_dependency 'awesome_print', '~> 1.8'
+    spec.add_development_dependency 'bundler', '~> 1.17'
+    spec.add_development_dependency 'byebug', '~> 10.0'
+    spec.add_development_dependency 'dotenv', '~> 2.5'
+    spec.add_development_dependency 'guard', '~> 2.15'
+    spec.add_development_dependency 'guard-rspec', '~> 4.7'
+    spec.add_development_dependency 'rubocop-rspec', '~> 1.31'
+    spec.add_development_dependency 'rake', '~> 12.3'
+    spec.add_development_dependency 'rspec', '~> 3.8'
+    spec.add_development_dependency 'rubocop', '~> 0.62'
+    spec.add_development_dependency 'webmock', '~> 3.5'
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'autotask_ruby'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/autotask_ruby.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/hash'
+require 'savon'
+require 'nokogiri'
+require 'autotask_ruby/configuration'
+require 'autotask_ruby/constants'
+require 'autotask_ruby/query'
+require 'autotask_ruby/association'
+require 'autotask_ruby/response'
+require 'autotask_ruby/query_response'
+require 'autotask_ruby/create_response'
+require 'autotask_ruby/delete_response'
+require 'autotask_ruby/zone_info'
+require 'autotask_ruby/entity'
+require 'autotask_ruby/client'
+require 'autotask_ruby/resource'
+require 'autotask_ruby/account'
+require 'autotask_ruby/contact'
+require 'autotask_ruby/account_to_do'
+require 'autotask_ruby/appointment'
+require 'autotask_ruby/task'
+require 'autotask_ruby/ticket'
+require 'autotask_ruby/project'
+require 'autotask_ruby/service_call'
+require 'autotask_ruby/service_call_ticket'
+require 'autotask_ruby/service_call_ticket_resource'

data/lib/autotask_ruby/account.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+    # Represents the Autotask Account Entity
+    class Account
+        include Entity
+
+        FIELDS = %i[id Address1 City Country CreateDate AccountName AccountNumber Phone PostalCode State Active].freeze
+        .each do |field|
+            self.attr_accessor :"#{field.to_s.underscore}"
+        end
+
+    end
+end

data/lib/autotask_ruby/account_to_do.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+    # Represents the Autotask AccountToDo entity
+    class AccountToDo
+        include AutotaskRuby::Entity
+        include AutotaskRuby::Query
+
+        FIELDS = %i[id AccountID ContactID ActivityDescription StartDateTime EndDateTime
+                    AssignedToResourceID ActionType CreateDateTime LastModifiedDate].freeze
+        .each do |field|
+            self.attr_accessor :"#{field.to_s.underscore}"
+        end
+
+        def post_initialize
+            belongs_to :resource
+            belongs_to :account
+        end
+    end
+end

data/lib/autotask_ruby/action_type.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+    # Represents the Autotask Entity Action Type
+    class ActionType
+        include Entity
+
+        FIELDS = %i[id Name View Active SystemActionType].freeze
+        .each do |field|
+            self.attr_accessor :"#{field.to_s.underscore}"
+        end
+    end
+end

data/lib/autotask_ruby/appointment.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+
+    # Represents an AutoTask Appointment Entity
+    class Appointment
+        include Entity
+
+        FIELDS = %i[id Title Description ResourceID StartDateTime EndDateTime CreateDateTime UpdateDateTime].freeze
+        .each do |field|
+            self.attr_accessor :"#{field.to_s.underscore}"
+        end
+
+        def post_initialize
+            belongs_to :resource
+        end
+
+    end
+
+end

data/lib/autotask_ruby/association.rb

@@ -0,0 +1,38 @@
+module AutotaskRuby
+    # handles loading associated entities.
+    module Association
+        # loads parent entity.
+        # Thanks to scoop for this example.
+        def belongs_to(name, options = {})
+            name = name.to_s
+            klass = "#{(options[:class_name] || name).to_s.classify}"
+            foreign_key = name.foreign_key
+            define_singleton_method(name) do
+                find(klass, send(foreign_key))
+            end
+        end
+
+        # Example, an appointment can have one contact.
+        # Thanks to scoop for this example.
+        def has_one(name, options = {})
+            name = name.to_s
+            options.reverse_merge! foreign_key: self.to_s.foreign_key.camelize
+            klass = "#{(options[:class_name] || name).to_s.classify}"
+            define_singleton_method(name) do
+                find(klass, options[:foreign_key], id).first
+            end
+        end
+
+        # loads child entities.
+        # Example: A project can have many tasks.
+        # Thanks to scoop for this example.
+        def has_many(name, options = {})
+            name = name.to_s
+            options.reverse_merge! foreign_key: self.to_s.foreign_key.camelize
+            klass = "#{(options[:class_name] || name).to_s.classify}"
+            define_singleton_method(name) do
+                query(klass, options[:foreign_key], id)
+            end
+        end
+    end
+end

data/lib/autotask_ruby/client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'autotask_ruby/version'
+require 'autotask_ruby/resource'
+
+module AutotaskRuby
+
+    # the primary client that interfaces with the SOAP Client that will interface with AutoTask.
+    class Client
+        attr_accessor :soap_client, :headers, :logger
+
+        def initialize(options = {})
+            @version = options[:version] || AutotaskRuby.configuration.version
+            integration_code = options[:integration_code] || AutotaskRuby.configuration.integration_code
+            @headers = {
+                'tns:AutotaskIntegrations' =>
+                    {
+                        'tns:IntegrationCode' => integration_code
+                    }
+            }
+
+            @ssl_version = options[:ssl_version] || :TLSv1_2
+
+            @host = options[:host] || 'webservices.autotask.net'
+            @endpoint = options[:endpoint] || "https://#{@host}/ATServices/#{@version}/atws.asmx"
+
+            # Override optional Savon attributes
+            savon_options = {}
+            %w[read_timeout open_timeout proxy raise_errors log_level basic_auth log raise_errors].each do |prop|
+                key = prop.to_sym
+                savon_options[key] = options[key] if options.key?(key)
+            end
+
+            @soap_client = Savon.client({
+                wsdl: './atws.wsdl',
+                soap_header: @headers,
+                namespaces: { xmlns: AutotaskRuby.configuration.namespace },
+                logger: Logger.new($stdout),
+                raise_errors: false,
+                log: true,
+                endpoint: @endpoint,
+                ssl_version: @ssl_version # Sets ssl_version for HTTPI adapter
+            }.update(savon_options))
+        end
+
+        # Public: Get the names of all wsdl operations.
+        # List all available operations from the atws.wsdl
+        def operations
+            @soap_client.operations
+        end
+
+        # @param entity, id
+        #   pass in the entity_type, I.E. AccountToDo, Resource, etc. and the ID of the entity.
+        # @return Entity
+        # Returns a single Entity if a match was found.
+        # Returns nil if no match is found.
+        def find(entity, id)
+            response = query(entity.to_s, id)
+
+            return nil if response.entities.empty?
+
+            response.entities.first
+        end
+
+        # @param entity_type and value
+        # Other parameters, are optional.
+        #   full set of parameters include entity_type, field, operation, value.
+        # Queries the Autotask QUERY API. Returns a QueryResponse result set.
+        # @return AutotaskRuby::Response.
+        def query(entity_type, field = 'id', operation = 'equals', value)
+            result = @soap_client.call(:query, message: "<sXML><![CDATA[<queryxml><entity>#{entity_type}</entity><query><field>#{field}<expression op=\"#{operation}\">#{value}</expression></field></query></queryxml>]]></sXML>")
+            AutotaskRuby::QueryResponse.new(self, result)
+        end
+
+        # @param entity_type
+        #   include the entity type. ServiceCall, Appointment, etc.
+        # @param ids
+        #   One or more entity ID's that should be deleted.
+        # @return
+        #   AutotaskRuby::DeleteResponse
+        def delete(entity_type, *ids)
+            entities = ++''
+            ids.each do |id|
+                entities << "<Entity xsi:type=\"#{entity_type}\"><id xsi:type=\"xsd:int\">#{id}</id></Entity>"
+            end
+            resp = @soap_client.call(:delete, message: "<Entities>#{entities.to_s}</Entities>")
+            AutotaskRuby::DeleteResponse.new(@client, resp)
+        end
+
+    end
+end

data/lib/autotask_ruby/configuration.rb

@@ -0,0 +1,25 @@
+module AutotaskRuby
+
+    class Configuration
+        attr_accessor :integration_code
+        attr_accessor :version
+        attr_accessor :namespace
+
+        def initialize
+            @integration_code = nil
+            @version = 1.5
+            @namespace = 'http://autotask.net/ATWS/v1_5/'
+        end
+    end
+
+    class << self
+        def configuration
+            @configuration ||= Configuration.new
+        end
+
+        def configure
+            yield(configuration)
+        end
+    end
+
+end

data/lib/autotask_ruby/constants.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+    module Constants
+        AUTOTASK_TIME_FORMAT = '%Y-%m-%dT%H:%M:%S'
+    end
+end

data/lib/autotask_ruby/contact.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+
+    # Represents the Autotask Entity Contact
+    class Contact
+        include Entity
+
+        FIELDS = %i[id Active AddressLine City Country CreateDate EMailAddress Extension FirstName AccountID LastName MobilePhone Phone State Title ZipCode].freeze
+        .each do |field|
+            self.attr_accessor :"#{field.to_s.underscore}"
+        end
+
+        def post_initialize
+            belongs_to :account
+        end
+
+        def full_name
+            [@first_name, @last_name].join(' ')
+        end
+
+        def email
+            @e_mail_address
+        end
+    end
+end

data/lib/autotask_ruby/create_response.rb

@@ -0,0 +1,5 @@
+module AutotaskRuby
+    class CreateResponse
+        include Response
+    end
+end

data/lib/autotask_ruby/delete_response.rb

@@ -0,0 +1,5 @@
+module AutotaskRuby
+    class DeleteResponse
+        include Response
+    end
+end

data/lib/autotask_ruby/entity.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module AutotaskRuby
+    # The base type for all objects represented by AutotaskRuby.
+    # This module should extend any object type being used with AutoTask.
+    module Entity
+        include AutotaskRuby::Constants
+        include AutotaskRuby::Association
+
+        FIELDS = %i[id].freeze
+
+        def self.included(base)
+            base.const_set :FIELDS, Entity::FIELDS unless base.const_defined?(:FIELDS)
+        end
+
+        def initialize(options = {})
+            @client = options if options.instance_of?(Client)
+            return unless options.kind_of?(Hash)
+
+            options.each do |k, v|
+                instance_variable_set("@#{k}", v)
+            end
+
+            post_initialize
+        end
+
+        # default post_initialize methods.
+        # Other classes that implement the Entity Class may override this.
+        def post_initialize
+
+        end
+
+        # Iterates the fields of a Entity Class Type.
+        # The fields are turned into instance variables.
+        # Fields could include id, StartDateTime, Title, etc.
+        def build(entity)
+            self.class.const_get(:FIELDS).each do |field|
+                instance_variable_set("@#{field}".underscore, field_set(entity, field))
+            end
+        end
+
+        # updates the entity in the AutoTask API.
+        # All fields are iterated and this builds the XML message that is sent to AutoTask.
+        # Any field that is not filled out will be sent as empty. This means that it will wipe
+        # any value that AutoTask has for that field.
+        def update
+            @client.soap_client.call(:update, message: "<Entity xsi:type=\"#{self.class.to_s.demodulize}\">#{fields_to_xml}</Entity>")
+        end
+
+        # creates an entity in AutoTask.
+        def create
+            result = @client.soap_client.call(:create, message: "<Entity xsi:type=\"#{self.class.to_s.demodulize}\">#{fields_to_xml}</Entity>")
+            CreateResponse.new(@client, result)
+        end
+
+        # converts the AutoTask dateTime string value to a ActiveSupport::TimeWithZone object.
+        # All dateTimes in AutoTask are in the Eastern Timezone.
+        def to_date_time(arg)
+            Time.find_zone!('Eastern Time (US & Canada)').parse(arg)
+        end
+
+        # Converts the specified field in the AutoTask XML response to the entity object field/attribute.
+        # @param
+        # - entity
+        # - field
+        def field_set(entity, field)
+            node = entity.xpath("Autotask:#{field}", Autotask: AutotaskRuby.configuration.namespace)
+
+            # entity may not contain all fields that are possible.
+            # Example: The entity may not have a contact specified.
+            return if node.blank?
+
+            return node.text.to_i if node.attr('type').blank? || node.attr('type').text.eql?('xsd:int')
+            return to_date_time(node.text) if node.attr('type').text.eql?('xsd:dateTime')
+            return node.text.to_f if node.attr('type').text.eql?('xsd:double')
+            return node.text.to_f if node.attr('type').text.eql?('xsd:decimal')
+
+            node.text
+        end
+
+        def to_bool(arg)
+            return true if arg == true || arg =~ (/(true|t|yes|y|1)$/i)
+            return false if arg == false || arg.empty? || arg =~ (/(false|f|no|n|0)$/i)
+            raise ArgumentError.new("invalid value for Boolean: \"#{arg}\"")
+        end
+
+        # converts the entity attributes to XML representation.
+        # This is used when sending the object to the AutoTask API.
+        def fields_to_xml
+            str = ++''
+
+            self.class.const_get(:FIELDS).each do |field|
+                obj = instance_variable_get("@#{field}".underscore)
+                next unless obj
+
+                str << format_field_to_xml(field, obj)
+            end
+            str
+        end
+
+        # Returns the specified field as an XML element for the XML Body.
+        # I.E. <id>xxx</id>
+        # @param field_name
+        #   the field name
+        # @param field_value
+        #   the field value.
+        def format_field_to_xml(field_name, field_value)
+            return "<#{field_name}>#{field_value.strftime(AUTOTASK_TIME_FORMAT)}</#{field_name}>" if field_value.instance_of?(ActiveSupport::TimeWithZone)
+
+            "<#{field_name}>#{field_value}</#{field_name}>"
+        end
+    end
+end