Class: Viewpoint::EWS::CalendarItem

Inherits:
Message show all
Defined in:
lib/model/calendar_item.rb

Constant Summary

Constants included from ItemFieldUriMap

ItemFieldUriMap::FIELD_URIS

Instance Attribute Summary

Attributes inherited from Item

#change_key, #item_id, #parent_folder_id

Attributes included from Model

#ews_methods, #ews_methods_undef

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Message

#headers, send, #to_mail

Methods inherited from Item

add_attachments, #attachments, #clear_updates!, #copy, #deepen!, get_item, #mark_read!, #mark_unread!, #move!, #parent_folder, #save!, #text_only=, #text_only?, #update_attribs, #update_attribs!

Constructor Details

#initialize(ews_item, opts = {}) ⇒ CalendarItem

Initialize an Exchange Web Services item of type CalendarItem



105
106
107
 
# File 'lib/model/calendar_item.rb', line 105

def initialize(ews_item, opts={})
  super(ews_item, opts)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Viewpoint::EWS::Item

Class Method Details

.create_item(v_start, v_end, subject, body = nil, location = nil, required_attendees = [], optional_attendees = [], resources = []) {|opts| ... } ⇒ Object

Create a new CalendarItem. If a block is given it is passed an opts hash with the keys :folder_id and :send_invites.

See ::create_item_from_hash for details

Parameters:

  • v_start (DateTime) —

    The date and time when the CalendarItem begins

  • v_end (DateTime) —

    The date and time when the CalendarItem ends

  • subject (String) —

    The subject of this Item

  • body (String, optional) (defaults to: nil) —

    The body of this object

  • location (String, optional) (defaults to: nil) —

    The location where this calendar item will ocurr

  • required_attendees (Array<String,MailboxUser,Attendee>, optional) (defaults to: []) —

    An Array of e-mail addresses of required attendees

  • optional_attendees (Array<String,MailboxUser,Attendee>, optional) (defaults to: []) —

    An Array of e-mail addresses of optional attendees

  • resources (Array<String,MailboxUser,Attendee>, optional) (defaults to: []) —

    An Array of e-mail addresses of resources

Yields:

  • (opts) 


86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/model/calendar_item.rb', line 86

def self.create_item(v_start, v_end, subject, body = nil, location = nil, required_attendees=[], optional_attendees=[], resources=[])
  item = {}
  opts = {:folder_id => :calendar, :send_invites => 'SendToAllAndSaveCopy'}
  yield opts if block_given?
  item[:start] = {:text => v_start.to_s}
  item[:end] = {:text => v_end.to_s}
  item[:subject] = {:text => subject}
  item[:body] = {:text => body, :body_type => 'Text'} unless body.nil?
  item[:location] = {:text => location} unless location.nil?
  item.merge!(self.format_attendees(required_attendees)) unless required_attendees.empty?
  item.merge!(self.format_attendees(optional_attendees, :optional_attendees)) unless optional_attendees.empty?
  resources.each do |a|
    item[:resources] = [] unless item[:resources].is_a?(Array)
    item[:resources] << {:attendee => {:mailbox => {:email_address => {:text => a}}}}
  end
  self.create_item_from_hash(item, opts[:folder_id], opts[:send_invites])
end

.create_item_from_hash(item, folder_id = :calendar, send_invites = 'SendToAllAndSaveCopy') ⇒ Object

This is a class method that creates a new CalendarItem in the Exchange Data Store.

Examples:

Typical Usage

item = { :subject => {:text => 'Planning'},
  :body => {:body_type => 'Text', :text => 'This is a test'},
  :start => {:text => '2010-07-29T14:00:00'},
  :end => {:text => '2010-07-29T15:00:00'},
  :is_all_day_event => {:text => 'false'},
  :location => {:text => 'Room 234'},
  :required_attendees => {:attendee => {:mailbox => {:email_address => {:text => '[email protected]'}}}}
}

Minimal Usage

item = { :subject => {:text => 'Planning'},
  :start => {:text => '2010-07-29T14:00:00'},
  :end => {:text => '2010-07-29T15:00:00'}
}

Parameters:



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/model/calendar_item.rb', line 44

def self.create_item_from_hash(item, folder_id = :calendar, send_invites = 'SendToAllAndSaveCopy')
  conn = Viewpoint::EWS::EWS.instance
  resp = conn.ews.create_calendar_item(folder_id, item, send_invites)
  if(resp.status == 'Success')
    resp = resp.items.shift
    self.new(resp[resp.keys.first])
  else
    raise EwsError, "Could not create CalendarItem. #{resp.code}: #{resp.message}"
  end
end

.format_attendees(attendees, type = :required_attendees) ⇒ Object

Format attendees (usually called from #add_attendees!

Parameters:

  • attendees (Array, String, Hash, MailboxUser)
  • type (Symbol) (defaults to: :required_attendees) —

    the type of the attendees :required_attendees/:optional_attendees/:resources



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/model/calendar_item.rb', line 58

def self.format_attendees(attendees, type=:required_attendees)
  case attendees.class.to_s
  when 'String'
    return {type => [{:attendee => {:mailbox => {:email_address => {:text => attendees}}}}]}
  when /Attendee|MailboxUser/
    return {type => [{:attendee => {:mailbox => [{:name => {:text => attendees.name}}, {:email_address => {:text => attendees.email_address}}]}}]}
  when 'Hash'
    return {type => [{:attendee => {:mailbox => [{:name => {:text => attendees[:name]}}, {:email_address => {:text => attendees[:email_address]}}]}}]}
  when 'Array'
    as = {type => []}
    attendees.each do |a|
      as.merge!(format_attendees(a, type)) {|k,v1,v2| v1 + v2}
    end
    return as
  end
end

Instance Method Details

#add_attendees(required, optional = [], resources = []) ⇒ Boolean

TODO:

add ability to add resources

Add attendees to this CalendarItem. This does not commit the changes so you will have to use #save! to

commit them back. If you want to commit them at once look at the #add_attendees! method.

Examples:

['[email protected]', '[email protected]']
or
[{:name => 'User1', :email_address => '[email protected]'}, {:name => 'User2', :email_address => '[email protected]'}]
or
['[email protected]', '[email protected]'], ['[email protected]', '[email protected]']
or
[{:name => 'User1', :email_address => '[email protected]'}, {:name => 'User2', :email_address => '[email protected]'}],
  [{:name => 'User3', :email_address => '[email protected]'}, {:name => 'User4', :email_address => '[email protected]'}]

Parameters:

  • required (Array) —

    Required attendees to add to this object Array values of attendees may be simple email strings, MailboxUser items or Hashes in the form => ‘email@test’, :name => ‘My Name’.

  • optional (Array) (defaults to: []) —

    Optional attendees to add to this object see the notes for the ‘required’ parameter.

Returns:

  • (Boolean) —

    true on success, false otherwise



127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/model/calendar_item.rb', line 127

def add_attendees(required, optional = [], resources = [])
  update = {}
  update.merge!(self.class.format_attendees(required)) unless required.empty? || required.nil?
  update.merge!(self.class.format_attendees(optional, :optional_attendees)) unless optional.empty? || optional.nil?

  return false if update.empty?

  @required_attendees, @optional_attendees = nil, nil
  changes = update_attribs(update, :append)
  @updates.merge!({:preformatted => changes}) {|k,v1,v2| v1 + v2}
  true
end

#add_attendees!(required, optional = [], resources = []) ⇒ Object

This is the same as the #add_attendees method, but it actually commits the change back to Exchange

See Also:



142
143
144
145
 
# File 'lib/model/calendar_item.rb', line 142

def add_attendees!(required, optional = [], resources = [])
  add_attendees(required, optional, resources)
  save!
end

#delete!(soft = false, cancel_type = 'SendOnlyToAll') ⇒ Boolean

TODO:

Add exception handling for failed deletes

Delete this item

Parameters:

  • soft (Boolean) (defaults to: false) —

    Whether or not to do a soft delete. By default EWS will do a hard delete of this item. See the MSDN docs for more info: msdn.microsoft.com/en-us/library/aa562961.aspx

  • cancel_type (String) (defaults to: 'SendOnlyToAll') —

    “SendToNone/SendOnlyToAll/SendToAllAndSaveCopy” Default is SendOnlyToAll

Returns:

  • (Boolean) —

    Whether or not the item was deleted



226
227
228
229
230
231
 
# File 'lib/model/calendar_item.rb', line 226

def delete!(soft=false, cancel_type='SendOnlyToAll')
  deltype = soft ? 'SoftDelete' : 'HardDelete'
  resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], deltype, cancel_type)
  self.clear_object!
  resp.status == 'Success'
end

#recycle!(cancel_type = 'SendOnlyToAll') ⇒ Boolean

TODO:

Add exception handling for failed deletes

Delete this item by moving it to the Deleted Items folder

Returns:

  • (Boolean) —

    Whether or not the item was deleted

See Also:



237
238
239
240
241
 
# File 'lib/model/calendar_item.rb', line 237

def recycle!(cancel_type='SendOnlyToAll')
  resp = (Viewpoint::EWS::EWS.instance).ews.delete_item([@item_id], 'MoveToDeletedItems', cancel_type)
  self.clear_object!
  resp.status == 'Success'
end

#remove_attendees(attendees) ⇒ Boolean

Remove the attendees from the attendee list. This does not commit the changes so you will have to use

#save! to commit them back. If you want to commit them at once look at the #remove_attendees! method.

Parameters:

  • attendees (Array) —

    the attendees to remove from this CalendarItem

    Viewpoint::EWS::Attendee<user1>, Viewpoint::EWS::Attendee<user2>

    or

    ‘[email protected]’, ‘[email protected]’

Returns:

  • (Boolean) —

    false if the object is not updated, true otherwise



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/model/calendar_item.rb', line 153

def remove_attendees(attendees)
  return false if attendees.empty?

  emails = attendees.is_a?(Array) ? attendees : attendees.values
  emails = emails.collect do |v|
    case v.class.to_s
    when 'String'
      v
    when /MailboxUser|Attendee/
      v.email_address
    when 'Hash'
      v[:email_address]
    end
  end

  update = {}
  [:required_attendees, :optional_attendees].each do |type|
    ivar = self.send(type.to_s)
    next if ivar.nil?

    required_a = ivar.select {|v| !emails.include?(v.email_address) }
    formatted_a = self.class.format_attendees(required_a, type)
    if formatted_a[type].empty?
      update[:preformatted] ||= []
      update[:preformatted] << {:delete_item_field => [{:field_uRI => {:field_uRI=>FIELD_URIS[type][:text]}}]}
      self.instance_eval "undef #{type}"
    else
      update.merge!(formatted_a)
    end
  end

  return false if update.empty?

  @required_attendees, @optional_attendees = nil, nil
  @updates.merge!(update) {|k,v1,v2| v1 + v2}
  true
end

#remove_attendees!(attendees) ⇒ Object

This is the same as the #remove_attendees method, but it actually commits the change back to Exchange

See Also:



193
194
195
196
 
# File 'lib/model/calendar_item.rb', line 193

def remove_attendees!(attendees)
  remove_attendees(attendees)
  save!
end

#update!(updates) ⇒ Object

Call UpdateItem for this item with the passed updates TODO: This is a stand-in for the Item#update! method until I can firm it up a bit. It is neccessary for the SendMeetingInvitationsOrCancellations attrib

Examples:

:set_item_field=>{:field_u_r_i=>{:field_u_r_i=>“message:IsRead”, :message=>:is_read=>{:text=>“true”}}}

Parameters:

  • updates (Hash) —

    a well-formed update hash



202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/model/calendar_item.rb', line 202

def update!(updates)
  conn = Viewpoint::EWS::EWS.instance
  resp = conn.ews.update_item([{:id => @item_id, :change_key => @change_key}], {:updates => updates},
                              {:message_disposition => 'SaveOnly', :conflict_resolution => 'AutoResolve', :send_meeting_invitations_or_cancellations => 'SendOnlyToChanged'})
  if resp.status == 'Success'
    @item_id = resp.items.first[resp.items.first.keys.first][:item_id][:id]
    @change_key = resp.items.first[resp.items.first.keys.first][:item_id][:change_key]
    @shallow = true
    deepen!
  else
    raise EwsError, "Trouble updating Item. #{resp.code}: #{resp.message}"
  end

end