dynamics_crm 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDYyNmExNWY0NTlhOGZmZTA2NzMyYWUzM2U2MjFlNjM2MWIxZGRiNQ==
+  data.tar.gz: !binary |-
+    NmNiMjM2OGMxNGYxMTcyNmE2MTg5YjUxMjkwZmQ2Yzc5ZWFkNGY4OQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZDJkMTRhM2YxZjgxYmJmZWRkODlhZjE3YzZhOTQzNjZhNTJhNzgwZTk5NzE5
+    Mzk1MjJmZTIxZThjYjQyN2MwYTAwZmI2YTVhMTQyYzVkNjU0M2FlOTAyMjAw
+    MTc4NjQ5MjM1YzE1YTg2ZmFhODYwN2M1MzBjODZiNzdmNmM2NjQ=
+  data.tar.gz: !binary |-
+    MjgyOGVjMzA5ZDI2YzI3MGFkYzdkN2EwZjg5OTJiZjJhMzAwMmVmYTBjM2U1
+    ZTAwMjM3Mjg2MThiMzRmMjk1N2NlZWFhOTkwY2Q5MmE5N2YzZjliMjA1MWVj
+    OTYwOGUwNjc2OTdmMjQ3MjIxZGI1YjA4MTM2NTYxZDlhNWYyNmI=

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3
+notifications:
+  email:
+    recipients:
+      - joeheth@gmail.com
+    on_success: never
+    on_failure: always

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in dynamics_crm.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Joe Heth
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# DynamicsCRM
+
+[![Build Status](https://travis-ci.org/TinderBox/dynamics_crm.png)](https://travis-ci.org/TinderBox/dynamics_crm)
+
+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
+
+```ruby
+client = DynamicsCRM::Client.new
+client.authenticate('user@orgname.onmicrosoft.com', 'password')
+```
+
+### retrieve
+
+```ruby
+client.retrieve('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60')
+# => #<DynamicsCRM::XML::Entity ... >
+```
+
+### retrieve_multiple
+
+```ruby
+client.retrieve_multiple('account', ["name", "Equal", "Test Account"])
+# => [#<DynamicsCRM::XML::Entity ... >]
+
+client.retrieve_multiple('account', ["name", "Equal", "Test Account"], ["Name, "CreatedBy"])
+# => [#<DynamicsCRM::XML::Entity ... >]
+```
+
+
+### create
+
+```ruby
+# Add a new account
+client.create('Account', name: 'Foobar Inc.')
+# => {id: '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'}
+```
+
+### update
+
+```ruby
+# Update the Account with id '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'
+client.update('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60', name: 'Whizbang Corp')
+# => {}
+```
+
+### delete
+
+```ruby
+# Delete the Account with id '53291AAB-4A9A-E311-B097-6C3BE5A8DD60'
+client.delete('account', '53291AAB-4A9A-E311-B097-6C3BE5A8DD60')
+# => {}
+```
+
+### retrieve_all_entities
+
+```ruby
+# get the list of organization entities
+client.retrieve_all_entities
+# => [#<DynamicsCRM::Metadata::EntityMetadata>, ...]
+```
+
+### retrieve_entity
+
+```ruby
+# get the entity metadata for the account object
+client.retrieve_entity('account')
+# => DynamicsCRM::Metadata::EntityMetadata
+```
+
+### retrieve_attribute
+
+```ruby
+# get AttributeMetadata for 'name' field on the account object
+client.retrieve_attribute('account', 'name')
+# => [#<DynamicsCRM::Metadata::AttributeMetadata>, ...]
+```
+
+
+## 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

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+task :default => [:spec]
+
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end

data/dynamics_crm.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'dynamics_crm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "dynamics_crm"
+  spec.version       = DynamicsCRM::VERSION
+  spec.authors       = ["Joe Heth"]
+  spec.email         = ["joeheth@gmail.com"]
+  spec.description   = %q{Ruby API for integrating with MS Dynamics 2011/2013 SOAP API}
+  spec.summary       = %q{Ruby gem for integrating with MS Dynamics 2011/2013 SOAP API}
+  spec.homepage      = "https://github.com/TinderBox/dynamics_crm"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'curb', '~> 0.8', '>= 0.8.5'
+  spec.add_runtime_dependency 'mimemagic', '~> 0.2', '>= 0.2.1'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency 'rake', '~> 10.1'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'simplecov', '~> 0.7'
+end

data/lib/dynamics_crm/client.rb

@@ -0,0 +1,295 @@
+# SOAP Only Walk through
+# http://code.msdn.microsoft.com/CRM-Online-2011-WebServices-14913a16
+#
+# PHP starting point: 
+# http://crmtroubleshoot.blogspot.com.au/2013/07/dynamics-crm-2011-php-and-soap-using.html
+# 
+# OCP: Open Commerce Platform
+# https://community.dynamics.com/crm/b/crmgirishraja/archive/2012/09/04/authentication-with-dynamics-crm-online-on-ocp-office-365.aspx
+module DynamicsCRM
+
+  class Client
+    extend Forwardable
+    include XML::MessageBuilder
+
+    # The Login URL and Region are located in the client's Organization WSDL.
+    # https://tinderboxdev.api.crm.dynamics.com/XRMServices/2011/Organization.svc?wsdl=wsdl0
+    # 
+    # Login URL: Policy -> Issuer -> Address
+    # Region: SecureTokenService -> AppliesTo
+    LOGIN_URL = "https://login.microsoftonline.com/RST2.srf"
+    REGION = 'urn:crmna:dynamics.com'
+
+    attr_accessor :logger, :caller_id
+
+    # Initializes Client instance.
+    # Requires: organization_name
+    # Optional: hostname
+    def initialize(config={organization_name: nil, hostname: nil, caller_id: nil})
+      raise RuntimeError.new("organization_name is required") if config[:organization_name].nil?
+
+      @organization_name = config[:organization_name]
+      @hostname = config[:hostname] || "#{@organization_name}.api.crm.dynamics.com"
+      @organization_endpoint = "https://#{@hostname}/XRMServices/2011/Organization.svc"
+      @caller_id = config[:caller_id]
+    end
+
+    # Public: Authenticate User
+    #
+    # Examples
+    #
+    #   client.authenticate('test@orgnam.onmicrosoft.com', 'password')
+    #   # => true || raised Fault
+    #
+    # Returns true on success or raises Fault
+    def authenticate(username, password)
+
+      @username = username
+      @password = password
+
+      soap_response = post(LOGIN_URL, build_ocp_request(username, password))
+
+      document = REXML::Document.new(soap_response)
+      # Check for Fault
+      fault_xml = document.get_elements("//[local-name() = 'Fault']")
+      raise XML::Fault.new(fault_xml) if fault_xml.any?
+
+      cipher_values = document.get_elements("//CipherValue")
+
+      if cipher_values && cipher_values.length > 0
+        @security_token0 = cipher_values[0].text
+        @security_token1 = cipher_values[1].text
+        # Use local-name() to ignore namespace.
+        @key_identifier = document.get_elements("//[local-name() = 'KeyIdentifier']").first.text
+      else
+        raise RuntimeError.new(soap_response)
+      end
+
+      true
+    end
+
+    # These are all the operations defined by the Dynamics WSDL.
+    # Tag names are case-sensitive.
+    def create(entity_name, attributes)
+
+      entity = XML::Entity.new(entity_name)
+      entity.attributes = XML::Attributes.new(attributes)
+
+      xml_response = post(@organization_endpoint, create_request(entity))
+      return Response::CreateResult.new(xml_response)
+    end
+
+    # http://crmtroubleshoot.blogspot.com.au/2013/07/dynamics-crm-2011-php-and-soap-calls.html
+    def retrieve(entity_name, guid, columns=[])
+
+      column_set = XML::ColumnSet.new(columns)
+      request = retrieve_request(entity_name, guid, column_set)
+
+      xml_response = post(@organization_endpoint, request)
+      return Response::RetrieveResult.new(xml_response)
+    end
+
+    def rollup(target_entity, query, rollup_type="Related")
+        self.execute("Rollup", {
+          Target: target_entity,
+          Query: query,
+          RollupType: rollup_type
+        })
+    end
+
+    def retrieve_multiple(entity_name, criteria=[], columns=[])
+
+      query = XML::Query.new(entity_name)
+      query.columns = columns
+      query.criteria = XML::Criteria.new(criteria)
+
+      request = retrieve_multiple_request(query)
+      xml_response = post(@organization_endpoint, request)
+      return Response::RetrieveMultipleResult.new(xml_response)
+    end
+
+    def fetch(fetchxml)
+      response = self.execute("RetrieveMultiple", {
+        Query: XML::FetchExpression.new(fetchxml)
+      })
+    end
+
+    # Update entity attributes
+    def update(entity_name, guid, attributes)
+
+      entity = XML::Entity.new(entity_name)
+      entity.id = guid
+      entity.attributes = XML::Attributes.new(attributes)
+
+      request = update_request(entity)
+      xml_response = post(@organization_endpoint, request)
+      return Response::UpdateResponse.new(xml_response)
+    end 
+
+    def delete(entity_name, guid)
+      request = delete_request(entity_name, guid)
+
+      xml_response = post(@organization_endpoint, request)
+      return Response::DeleteResponse.new(xml_response)
+    end
+
+    def execute(action, parameters={}, response_class=nil)
+      request = execute_request(action, parameters)
+      xml_response = post(@organization_endpoint, request)
+
+      response_class ||= Response::ExecuteResult
+      return response_class.new(xml_response)
+    end
+
+    def associate(entity_name, guid, relationship, related_entities)
+      request = associate_request(entity_name, guid, relationship, related_entities)
+      xml_response = post(@organization_endpoint, request)
+      return Response::AssociateResponse.new(xml_response)
+    end
+
+    def disassociate(entity_name, guid, relationship, related_entities)
+      request = disassociate_request(entity_name, guid, relationship, related_entities)
+      xml_response = post(@organization_endpoint, request)
+      return Response::DisassociateResponse.new(xml_response)
+    end
+
+    def create_attachment(entity_name, entity_id, options={})
+      raise "options must contain a document entry" unless options[:document]
+
+      file_name = options[:filename]
+      document = options[:document]
+      subject = options[:subject]
+      text = options[:text] || ""
+
+      if document.is_a?(String) && File.exists?(document)
+        file = File.new(document)
+      elsif document.is_a?(String) && document.start_with?("http")
+        require 'open-uri'
+        file = open(document)
+      else
+        file = document
+      end
+
+      if file.respond_to?(:base_uri)
+        file_name ||= File.basename(file.base_uri.path)
+        mime_type = MimeMagic.by_path(file.base_uri.path)
+      elsif file.respond_to?(:path)
+        file_name ||= File.basename(file.path)
+        mime_type = MimeMagic.by_path(file.path)
+      else
+        raise "file must be a valid File object, file path or URL"
+      end
+
+      documentbody = file.read
+      attributes = {
+        objectid: {id: entity_id, logical_name: entity_name},
+        subject: subject || file_name,
+        notetext: text || "",
+        filename: file_name,
+        isdocument: true,
+        documentbody: ::Base64.encode64(documentbody),
+        filesize: documentbody.length,
+        mimetype: mime_type
+      }
+
+      self.create("annotation", attributes)
+    end
+
+    def retrieve_attachments(entity_id, columns=["filename", "documentbody", "mimetype"])
+      self.retrieve_multiple("annotation", [["objectid", "Equal", entity_id], ["isdocument", "Equal", true]], columns)
+    end
+
+    # Metadata Calls
+    # EntityFilters Enum: Default, Entity, Attributes, Privileges, Relationships, All
+    def retrieve_all_entities
+      response = self.execute("RetrieveAllEntities", {
+        EntityFilters: "Entity",
+        RetrieveAsIfPublished: true
+        },
+        Metadata::RetrieveAllEntitiesResponse)
+    end
+
+    # EntityFilters Enum: Default, Entity, Attributes, Privileges, Relationships, All
+    def retrieve_entity(logical_name, entity_filter="Attributes")
+      self.execute("RetrieveEntity", {
+        LogicalName: logical_name,
+        MetadataId: "00000000-0000-0000-0000-000000000000",
+        EntityFilters: entity_filter,
+        RetrieveAsIfPublished: true
+        },
+        Metadata::RetrieveEntityResponse)
+    end
+
+    def retrieve_attribute(entity_logical_name, logical_name)
+      self.execute("RetrieveAttribute", {
+        EntityLogicalName: entity_logical_name,
+        LogicalName: logical_name,
+        MetadataId: "00000000-0000-0000-0000-000000000000",
+        RetrieveAsIfPublished: true
+        },
+        Metadata::RetrieveAttributeResponse)
+    end
+
+    def who_am_i
+      self.execute('WhoAmI')
+    end
+
+    def load_entity(logical_name, id)
+      case logical_name
+      when "opportunity"
+        Model::Opportunity.new(id, self)
+      else
+        Model::Entity.new(logical_name, id, self)
+      end
+    end
+
+    protected
+
+    def post(url, request)
+
+      log_xml("REQUEST", request)
+
+      c = Curl::Easy.new(url) do |http|
+        # Set up headers.
+        http.headers["Connection"] = "Keep-Alive"
+        http.headers["Content-type"] = "application/soap+xml; charset=UTF-8"
+        http.headers["Content-length"] = request.length
+
+        http.ssl_verify_peer = false
+        http.timeout = 60
+        http.follow_location = true
+        http.ssl_version = 3
+        # http.verbose = 1
+      end
+
+      if c.http_post(request)
+        response = c.body_str
+      else
+
+      end
+
+      log_xml("RESPONSE", response)
+
+      response
+    end
+
+    def log_xml(title, xml)
+      return unless logger
+
+      logger.puts(title)
+      doc = REXML::Document.new(xml)
+      formatter.write(doc.root, logger)
+      logger.puts
+    end
+
+    def formatter
+      unless @formatter
+        @formatter = REXML::Formatters::Pretty.new(2)
+        @formatter.compact = true # This is the magic line that does what you need!
+      end
+      @formatter
+    end
+
+  end
+
+end

data/lib/dynamics_crm/metadata/attribute_metadata.rb

@@ -0,0 +1,42 @@
+module DynamicsCRM
+  module Metadata
+
+    # AttributeMetadata
+    # ManagedPropertyAttributeMetadata
+    # IntegerAttributeMetadata
+    # BooleanAttributeMetadata
+    # DateTimeAttributeMetadata
+    # DecimalAttributeMetadata
+    # DoubleAttributeMetadata
+    # EntityNameAttributeMetadata
+    # MoneyAttributeMetadata
+    # StringAttributeMetadata
+    # LookupAttributeMetadata
+    # MemoAttributeMetadata
+    # BigIntAttributeMetadata
+    # PicklistAttributeMetadata
+    # StateAttributeMetadata
+    # StatusAttributeMetadata
+    #
+    # http://msdn.microsoft.com/en-us/library/microsoft.xrm.sdk.metadata.attributemetadata.aspx
+    class AttributeMetadata < XmlDocument
+
+      # Only applicable to PicklistAttributeMetadata
+      def picklist_options
+        return @picklist_options if @picklist_options
+
+        @picklist_options = {}
+        option_metadata = "./d:OptionSet/d:Options/d:OptionMetadata"
+        @document.get_elements(option_metadata).each do |option|
+          numeric_value = option.elements["d:Value"].text
+          label = option.elements["d:Label/b:UserLocalizedLabel/b:Label"].text
+          @picklist_options[numeric_value.to_i] = label
+        end
+
+        @picklist_options
+      end
+
+    end
+
+  end
+end

data/lib/dynamics_crm/metadata/entity_metadata.rb

@@ -0,0 +1,24 @@
+module DynamicsCRM
+  module Metadata
+    # Represents EntityMetdata XML fragment.
+    # Optionally contains list of AttributeMetadata
+    class EntityMetadata < XmlDocument
+      attr_reader :attributes
+
+      def initialize(document)
+        super
+      end
+
+      def attributes
+        return if @attributes.is_a?(Array)
+
+        @attributes = document.get_elements("//d:Attributes/d:AttributeMetadata").collect do |attr_metadata|
+          AttributeMetadata.new(attr_metadata)
+        end
+
+        return @attributes
+      end
+
+    end
+  end
+end

data/lib/dynamics_crm/metadata/retrieve_all_entities_response.rb

@@ -0,0 +1,21 @@
+module DynamicsCRM
+  module Metadata
+
+    # Retrieve All Entities returns a list of EntityMetadata
+    class RetrieveAllEntitiesResponse < DynamicsCRM::Response::ExecuteResult
+      attr_reader :entities
+
+      def initialize(xml)
+        super
+        @entities = []
+        # Single KeyValuePair of EntityMetadata -> [EntityMetdata,...]
+        self.delete("EntityMetadata").each do |em_xml|
+          @entities << EntityMetadata.new(em_xml)
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/dynamics_crm/metadata/retrieve_attribute_response.rb

@@ -0,0 +1,16 @@
+module DynamicsCRM
+  module Metadata
+    # Retrieve Attribute returns a single AttributeMetadata.
+    class RetrieveAttributeResponse < DynamicsCRM::Response::ExecuteResult
+      attr_reader :attribute
+
+      def initialize(xml)
+        super
+
+        # Single KeyValuePair containing 1 value type of AttributeMetadata
+        @attribute = AttributeMetadata.new(self.delete("AttributeMetadata"))
+      end
+
+    end
+  end
+end

data/lib/dynamics_crm/metadata/retrieve_entity_response.rb

@@ -0,0 +1,17 @@
+module DynamicsCRM
+  module Metadata
+
+    # RetrieveEntity returns a single EntityMetadata element.
+    class RetrieveEntityResponse < DynamicsCRM::Response::ExecuteResult
+      attr_reader :entity, :attributes
+
+      def initialize(xml)
+        super
+
+        # Single KeyValuePair containing 1 value type of EntityMetadata
+        @entity = EntityMetadata.new(self["EntityMetadata"])
+      end
+
+    end
+  end
+end

data/lib/dynamics_crm/metadata/xml_document.rb

@@ -0,0 +1,39 @@
+module DynamicsCRM
+  module Metadata
+
+    class XmlDocument
+
+      attr_reader :document
+      def initialize(document)
+        @document = document
+      end
+
+      # Allows access to attributes in underlying XML document.
+      def method_missing(method, *args, &block)
+        value = nil
+        return value if @document.nil?
+
+        camel_name = method.to_s
+        element = @document.get_elements("./[local-name() = '#{camel_name}']").first
+
+        if element && element.children.size == 1 && element.children.first.is_a?(REXML::Text)
+          value = element.text
+        elsif element
+          value = XmlDocument.new(element)
+        else
+          # This returns if no XML element was found to avoid nil errors.
+          value = OpenStruct.new
+        end
+
+        # Return wrapper to support method_method missing.
+        return value
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        camel_name = method_name.to_s
+        @document.get_elements("d:#{camel_name}").any? || super
+      end
+    end
+
+  end
+end