ebeigarts / exchanger

Ruby client for Exchange Web Services

Exchanger

Ruby library for accessing Microsoft Exchange using Exchange Web Services. This library tries to make creating and updating items as easy as possible. It will keep track of changed properties and will update only them.

Supported operations

• FindItem, GetItem, CreateItem, UpdateItem, DeleteItem, MoveItem
• FindFolder, GetFolder
• ResolveNames, ExpandDL
• GetUserAvailability
• GetAttachment, CreateAttachment, DeleteAttachment

Installing

gem install exchanger

Configuration

Exchanger.configure do |config|
  config.endpoint = "https://domain.com/EWS/Exchanger.asmx"
  config.username = "username"
  config.password = "password"
  config.debug = true # show Exchange request/response info
end

or configure from YAML

Exchanger::Config.instance.from_hash(YAML.load_file("#{Rails.root}/config/exchanger.yml")[Rails.env])

Examples

Creating and updating contacts

folder = Exchanger::Folder.find(:contacts)
contact = folder.new_contact
contact.given_name = "Edgars"
contact.surname = "Beigarts"
contact.email_addresses = [ Exchanger::EmailAddress.new(:key => "EmailAddress1", :text => "[email protected]") ]
contact.phone_numbers = [ Exchanger::PhoneNumber.new(:key => "MobilePhone", :text => "[phone]") ]
contact.save # CreateItem operation
contact.company_name = "Example Inc."
contact.save # UpdateItem operation
contact.destroy # DeleteItem operation

Searching in Global Address Book

mailboxes = Exchanger::Mailbox.search("John")

Searching for Calendar items

More specific Exchange calendar documentation can be found here.

1. Return all Calendar items with recurring master appointments (without recurring). Also called as non-expanded view.

folder = Exchanger::Folder.find(:calendar, "[email protected]")
folder.items # return Exchanger::CalendarItem items

2. Return Calendar items providing CalendarView (with recurring).

Supported CalendarView options/attributes:

• max_entries_returned
• start_date
• end_date

folder = Exchanger::Folder.find(:calendar, "[email protected]")
calendar_view_options = {
  start_date: (DateTime.now - 1.week),
  end_date:   DateTime.now,
}
folder.expanded_items(calendar_view_options) # return Exchanger::CalendarItem items

Running specs with Exchange Server

The easiest way is to sign up for a Microsoft Office 365 free trial. Please not that this needs to be the "Professional" version in order to be able to access the distribution lists. You also need to finish the setup, including e-mail, to be able to execute the steps below. Provisioning mail boxes can take up to 24 hours.

1. Create a random calendar entry in July 2016
2. Create a distribution list named 'Test'
   • This is available under the app "People" > "New group"
3. Create spec/config.yml with your Exchange credentials
4. Create spec/fixtures/get_user_availability.yml with your Exchange email address
5. Clear the recorded VCR cassettes by removing spec/cassettes
6. Run the specs rake spec

It looks like Office 365 trial has some rate limits, so you may have to record the VCR cassettes for each spec separately.

Exchanger::Operation::ResponseError:
  An internal server error occurred. Try again later.

Alternatives

• Exchange Clients in Ruby Toolbox

exchanger's Issues

How to get 'Out of office' user status

Hi Ebeigarts,

At first, Kindly thank you for such great gem :)
I have a small question about opportunity to get 'Out of office' user status from exchange,
I found in MSDN documentation this API: http://msdn.microsoft.com/en-us/library/aa493825.aspx

I think it should be a cool possibility to check is user in office and free to communication or are absent today.

So, have your gem opportunity to get 'Out of office' user status?
Thanks a lot

Change message attribute

Hi,

Through EWS API I'm marking one of the email as read. For which I'm using Item.is_read attribute.
I'm creating object of Exchanger::UpdateItem. However after sending the request to edit the is_read property. I'm getting ResponseError as "MessageDisposition attribute is required".

The only way to fix it, is to add one more attribute in UpdateItem class, similar to send_meeting_invitations_or_cancellations, having name message_disposition and have a if check in
update_item_attributes method similar to the above field.

If you are fine with this approach I will submit a Pull Request to fix this issue.

Can't retrieve events body

Hi,

First, thanks for developing this gem, it's been very handy! 😄

I'm retrieving some events from a calendar and everything works fine except that I can't retrieve events body (long description). The attribute is there, but it does not have any content.

I'm trying to debug this placing debuggers in several points, like in operation.rb to examine the received XMLs:

def run
  @request = self.class::Request.new(options)
  @response = self.class::Response.new(
    Exchanger::Client.new.request(@request.body, @request.headers)
   )
   debugger
   # Here if I examine the XML returned by @response.body I can't see the event body anywhere.
   @response
end

Some other insights about the @request object at this point:

(byebug) @request
#<Exchanger::FindItem::Request:0x00007ff6d36d3360 @folder_id="something123", @traversal=:shallow, @base_shape=:all_properties, @email_address=nil, @calendar_view=#<Exchanger::CalendarView start_date: Thu, 25 Jan 2018 11:41:52 +0100, end_date: Wed, 30 Jan 2019 11:41:52 +0100>>
(byebug) @request.body
"<?xml version=\"1.0\"?>\n<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">\n  <soap:Body>\n    <FindItem xmlns=\"http://schemas.microsoft.com/exchange/services/2006/messages\" xmlns:t=\"http://schemas.microsoft.com/exchange/services/2006/types\" Traversal=\"Shallow\">\n      <ItemShape>\n        <t:BaseShape>AllProperties</t:BaseShape>\n      </ItemShape>\n      <CalendarView StartDate=\"2018-01-25T11:41:52+01:00\" EndDate=\"2019-01-30T11:41:52+01:00\"/>\n      <ParentFolderIds>\n        <t:FolderId Id=\"something123\"/>\n      </ParentFolderIds>\n    </FindItem>\n  </soap:Body>\n</soap:Envelope>\n"

I've made a quick test with the https://github.com/WinRb/Viewpoint gem and i can see the descriptions there, so the event bodies are there, but I rather not change the gem now.

¿Any clue about how to solve this? ¿Am I missing something?

Any help is really appreciated!

expanded_items method returns 'The request is invalid.'

I have a client that upgraded to Office 365. cal = folder.items seems to work fine still, but it maxes out at 1000 results it looks like. I don't remember having that issue before. Tried the folder.expanded_items method to define start and end times to return less records, but it returns 'The request is invalid' when I try the example in the README.

Exchanger::Operation::ResponseError creating calendar items

Hello, I'm trying to create a calendar event but when saving it complains I need to specify a "SendMeetingInvitations" attribute.
I cannot find where to set it up, is that an issue or do i miss to configure anything?

I'm connected to a MS Exchange 2010 server.

Here is the error description: <Exchanger::Operation::ResponseError: The SendMeetingInvitations attribute is required for calendar items.>

Here is my code:

Exchanger::Client.new
cal = Exchanger::Folder.find(:calendar,'[email protected]')

@item = cal.new_calendar_item
@item.subject = "Launch time!!"
@item.start = Time.parse('2012-06-27 13:00:00')
@item.end = Time.parse('2012-06-27 14:00:00')
@item.is_all_day_event = false
@item.location = 'Room 1'
@item.is_meeting = false

@item.save()

Thank you in advance,
Davide

tzinfo is marked as dev dependency

The gem tzinfo is marked as a development dependency, but for me it was a run time dep.

TimeZone sets to UTC on all_day_events

I am seeing this behavior when creating all_day_events as described here:

http://stackoverflow.com/questions/7828823/exchange-2010-web-services-creation-of-an-all-day-event-appointment

I am guessing this is because the Exchange server I am using is on Office365 (hosted Exchange) and therefore has a default server time of UTC.

Would adding StartTimeZone and EndTimeZone to CalendarItem as well as creating an Entry of TimeZone with and :id and :name (as described here http://msdn.microsoft.com/en-us/library/exchange/ff406132(v=exchg.140).aspx) be the best way to go?

Thanks!

Add to rails application

Hello,

This is probably a stupid question but i can't include the library in my rails application.

I added this to my Gemfile

gem 'exchanger'
and after running bundle, it got installed properly.

But when i try to do this :

folder = Exchanger::Folder.find(:calendar)
folder.items # return Exchanger::CalendarItem items

It tells me : uninitialized constant Exchanger

I added a require 'exchanger' in the controller where i put the code above. So i don't know what to do.

Please help, thanks!

Incorrect UTC support

When I'm using the CalendarItem, EWS is returning CalendarEvents like this:

          <CalendarEvent>
            <StartTime>2013-08-26T06:43:53</StartTime>
            <EndTime>2013-08-26T06:53:53</EndTime>
            <BusyType>Busy</BusyType>
          </CalendarEvent>

The exchanger library is calling Time.xmlschema on these times.
The problem is that they are not in the correct xmlschema format. These times are UTC. But the xmlschema specification is clear, for UTC times you need to add a Z at the end of it.

See:

2.0.0-p247 :003 > Time.xmlschema '2013-08-26T06:43:53'
=> 2013-08-26 06:43:53 +0900 
2.0.0-p247 :004 > Time.xmlschema '2013-08-26T06:43:53Z'
 => 2013-08-26 06:43:53 UTC 

The first one is converted to my local timezone. The second one is correct.
So basically, if you book meetings in UTC, you'll have a bad time when you get them back.
Am I wrong?

Can this be used to send email?

Is there anyway to send an authenticated email using this? An example would be great.

Recurring Event

I am having trouble creating a recurring event. What parameters must be set? I keep getting invalid elements when I try to set parameters such as

calendar_item_type => 'RecurringMaster'

Can someone provide an example

Cannot get folder

Hello when i try to execute this code :

I have put this code

require 'exchanger'

Exchanger.configure do |config|
  config.endpoint = "https://domain.com/EWS/Exchanger.asmx"
  config.username = "username"
  config.password = "password"
  config.debug = true # show Exchange request/response info
end

in exchanger.rb in initializers folders and then when i try this code in my controller :

folder = Exchanger::Folder.find(:contacts)
contact = folder.new_contact
contact.given_name = "Edgars"
contact.surname = "Beigarts"
contact.email_addresses = [ Exchanger::EmailAddress.new(:key => "EmailAddress1", :text => "[email protected]") ]
contact.phone_numbers = [ Exchanger::PhoneNumber.new(:key => "MobilePhone", :text => "[phone]") ]
contact.save # CreateItem operation
contact.company_name = "Example Inc."
contact.save # UpdateItem operation
contact.destroy # DeleteItem operation

It tells me that folder is nil...I've already configured the endpoint and login/password. I've also tried with the office 365 ews endpoint : https://outlook.office365.com/EWS/Exchange.asmx

List Email

Hi there,

Thanks for this gem!

Unfortunately I couldn't figure out how to get a user's list list of emails as well as how to retrieve their content?

Thanks in advance!

Contact photo

Hello, is it possible to get user photo?
like that /ews/Exchange.asmx/s/GetUserPhoto?email=XXXX&size=HR648x648

Can this work with SAML/SSO?

I've been playing around with this gem and it appears to work as expected for my personal Outlook.com email account, but not for my corporate account which runs on Exchange but uses my corporate SSO credentials: I get 401 Unauthorized responses instead.

Apple's macOS Calendar app seems to handle this just fine: once you try to add the new Exchange account, it redirects you to log in via SSO the first time, after which point the calendar works seamlessly thereafter, so I'm assuming there should be some way to do the same via this gem. (Unless our corporate server can somehow detect the end client and is only accepting integrations with Apple Calendar?) Any thoughts here? Thank you!