Module: AutotaskRuby::Entity

Includes:
Association, Constants
Included in:
Account, AccountToDo, ActionType, Appointment, Contact, Project, Resource, ServiceCall, ServiceCallTicket, ServiceCallTicketResource, Task, Ticket
Defined in:
lib/autotask_ruby/entity.rb

Overview

The base type for all objects represented by AutotaskRuby. This module should extend any object type being used with AutoTask.

Constant Summary collapse

FIELDS = 
%i[id].freeze

Constants included from Constants

Constants::AUTOTASK_TIME_FORMAT

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Association

#belongs_to, #has_many, #has_one

Class Method Details

.included(base) ⇒ Object 



12
13
14
 
# File 'lib/autotask_ruby/entity.rb', line 12

def self.included(base)
  base.const_set :FIELDS, Entity::FIELDS unless base.const_defined?(:FIELDS)
end

Instance Method Details

#build(entity) ⇒ Object

Iterates the fields of a Entity Class Type. The fields are turned into instance variables. Fields could include id, StartDateTime, Title, etc.



34
35
36
37
38
 
# File 'lib/autotask_ruby/entity.rb', line 34

def build(entity)
  self.class.const_get(:FIELDS).each do |field|
    instance_variable_set("@#{field}".underscore, field_set(entity, field))
  end
end

#create ⇒ Object

creates an entity in AutoTask.



49
50
51
52
 
# File 'lib/autotask_ruby/entity.rb', line 49

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

#field_set(entity, field) ⇒ Object

Converts the specified field in the AutoTask XML response to the entity object field/attribute.

  • entity

  • field

Parameters:



64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/autotask_ruby/entity.rb', line 64

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

#fields_to_xml ⇒ Object

converts the entity attributes to XML representation. This is used when sending the object to the AutoTask API.



88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/autotask_ruby/entity.rb', line 88

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

#format_field_to_xml(field_name, field_value) ⇒ Object

Returns the specified field as an XML element for the XML Body. I.E. <id>xxx</id>

Parameters:

  • field_name —

    the field name

  • field_value —

    the field value.



106
107
108
109
110
111
112
 
# File 'lib/autotask_ruby/entity.rb', line 106

def format_field_to_xml(field_name, field_value)
  if field_value.instance_of?(ActiveSupport::TimeWithZone)
    return "<#{field_name}>#{field_value.strftime(AUTOTASK_TIME_FORMAT)}</#{field_name}>"
  end

  "<#{field_name}>#{field_value}</#{field_name}>"
end

#initialize(options = {}) ⇒ Object 



16
17
18
19
20
21
22
23
24
25
 
# File 'lib/autotask_ruby/entity.rb', line 16

def initialize(options = {})
  @client = options if options.instance_of?(Client)
  return unless options.is_a?(Hash)

  options.each do |k, v|
    instance_variable_set("@#{k}", v)
  end

  post_initialize
end

#post_initialize ⇒ Object

default post_initialize methods. Other classes that implement the Entity Class may override this.



29
 
# File 'lib/autotask_ruby/entity.rb', line 29

def post_initialize; end

#to_bool(arg) ⇒ Object

Raises:

  • (ArgumentError) 


79
80
81
82
83
84
 
# File 'lib/autotask_ruby/entity.rb', line 79

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, "invalid value for Boolean: \"#{arg}\""
end

#to_date_time(arg) ⇒ Object

converts the AutoTask dateTime string value to a ActiveSupport::TimeWithZone object. All dateTimes in AutoTask are in the Eastern Timezone.



56
57
58
 
# File 'lib/autotask_ruby/entity.rb', line 56

def to_date_time(arg)
  Time.find_zone!('Eastern Time (US & Canada)').parse(arg)
end

#update ⇒ Object

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.



44
45
46
 
# File 'lib/autotask_ruby/entity.rb', line 44

def update
  @client.soap_client.call(:update, message: "<Entity xsi:type=\"#{self.class.to_s.demodulize}\">#{fields_to_xml}</Entity>")
end