stephenkiers / dynamics_crm

Ruby library for interacting with Microsoft Dynamics CRM SOAP API

DynamicsCRM

Ruby library for accessing Microsoft Dynamics CRM Online 2011/2013 via their SOAP API.

Installation

Add this line to your application's Gemfile:

gem 'dynamics_crm'

And then execute:

$ bundle

Or install it yourself as:

$ gem install dynamics_crm

Usage

Username/Password authentication

client = DynamicsCRM::Client.new({organization_name: "orgname"})
client.authenticate('[email protected]', 'password')

retrieve

client.retrieve('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60')
# => #<DynamicsCRM::XML::Entity ... >

retrieve_multiple

client.retrieve_multiple('account', [["name", "Equal", "Test Account"]])
# => [#<DynamicsCRM::XML::Entity ... >]

client.retrieve_multiple('account', [["name", "Equal", "Test Account"], ["Name, "CreatedBy"]])
# => [#<DynamicsCRM::XML::Entity ... >]

fetch (FetchXml)

# Raw XML Support
xml = %Q{<fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
  <entity name="opportunityproduct">
    <attribute name="opportunityproductid" />
    <attribute name="productdescription" />
    <attribute name="priceperunit" />
    <attribute name="quantity" />
    <order attribute="productid" descending="false" />
    <link-entity name="product" from="productid" to="productid" alias="product" link-type="inner">
      <attribute name="name" />
      <attribute name="producttypecode" />
      <attribute name="price" />
      <attribute name="standardcost" />
    </link-entity>
    <filter type="and">
      <condition attribute="opportunityid" operator="eq" value="02dd7344-d04a-e411-a9d3-9cb654950300" />
    </filter>
  </entity>
</fetch>}

result = client.fetch(xml)
# => #<DynamicsCRM::XML::EntityCollection>
# result.entity_name => 'opportunityproduct'
# result.entities => [DynamicsCRM::XML::Entity, ...]

# Using FetchXml::Builder
builder = DynamicsCRM::FetchXml::Builder.new()

entity = builder.entity('opportunityproduct').add_attributes(
  ['productdescription', 'priceperunit', 'quantity', 'opportunityproductid']
).order('productid')

entity.link_entity('product', to: 'productid', from: 'productid', :alias => 'product').add_attributes(
  ['name', 'producttypecode', 'price', 'standardcost']
)

entity.add_condition('opportunityid', 'eq', '02dd7344-d04a-e411-a9d3-9cb654950300')

result = client.fetch(builder.to_xml)
# => #<DynamicsCRM::XML::EntityCollection>
# result.entity_name => 'opportunityproduct'
# result.entities => [DynamicsCRM::XML::Entity, ...]

create

# Add a new account
client.create('account', name: 'Foobar Inc.')
# => {id: '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'}

# Add a new contact
client.create('contact', firstname: 'John', lastname: 'Doe', emailaddress1: "[email protected]")
# => {id: '71ef2416-50f7-e311-93fc-6c3be5a8c054'}

update

# Update the Account with id '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'
client.update('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60', name: 'Whizbang Corp')
# => {}

delete

# Delete the Account with id '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'
client.delete('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60')
# => {}

retrieve_all_entities

# get the list of organization entities
client.retrieve_all_entities
# => [#<DynamicsCRM::Metadata::EntityMetadata>, ...]

retrieve_entity

# get the entity metadata for the account object
client.retrieve_entity('account')
# => DynamicsCRM::Metadata::EntityMetadata

retrieve_attribute

# get AttributeMetadata for 'name' field on the account object
client.retrieve_attribute('account', 'name')
# => [#<DynamicsCRM::Metadata::AttributeMetadata>, ...]

associate a contact to an account

contacts = [ DynamicsCRM::XML::EntityReference.new("contact", contact["id"])]
client.associate("account", account["id"], "contact_customer_accounts", contacts)

Logging

If you want to log the REQUEST and RESPONSE, you can do through Logger class of Ruby.

client.logger = Logger.new(STDOUT)

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request