maestrano-connector-rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2df2109ee451552dfa445e1887b5048b7a457906
+  data.tar.gz: b85fbd4b76831b51093c99c757be09b722ae673b
+SHA512:
+  metadata.gz: aeb87f7f7db0490289fa878b39cc90c94be00ed471112420005da481b974fb7432820427cceb6725187de0b1fad87fb2c36a9d2cc3fce01ce667b02da27206cc
+  data.tar.gz: fba4495fb0e7510eb329232668f5f0e8a789b531be03f09be3f90476777315fe323752e9ea6ea6864b9f224869baa378a8225b3a517999da62f6514d6774c75d

data/.rspec

@@ -0,0 +1 @@
+--colour

data/DEVELOPER.md

@@ -0,0 +1,10 @@
+## Release gem
+
+Release the gem using jeweler
+
+``` bash
+gem install jeweler
+bundle exec rake version:bump:minor
+bundle exec rake gemspec:release
+bundle exec rake release
+```

data/Gemfile

@@ -0,0 +1,18 @@
+source "http://rubygems.org"
+
+# Add dependencies required to use your gem here.
+gem 'maestrano-rails', '~> 0.14.0'
+gem 'hash_mapper', '~> 0.2.1'
+
+# Add dependencies to develop your gem here.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.0"
+  gem "jeweler", "~> 2.0.1"
+  gem "simplecov", ">= 0"
+  gem 'rspec-rails'
+  gem 'factory_girl_rails'
+  gem 'sqlite3'
+  gem 'shoulda-matchers'
+end

data/Gemfile.lock

@@ -0,0 +1,222 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (4.2.5)
+      actionpack (= 4.2.5)
+      actionview (= 4.2.5)
+      activejob (= 4.2.5)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+    actionpack (4.2.5)
+      actionview (= 4.2.5)
+      activesupport (= 4.2.5)
+      rack (~> 1.6)
+      rack-test (~> 0.6.2)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (4.2.5)
+      activesupport (= 4.2.5)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 1.0, >= 1.0.5)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    activejob (4.2.5)
+      activesupport (= 4.2.5)
+      globalid (>= 0.3.0)
+    activemodel (4.2.5)
+      activesupport (= 4.2.5)
+      builder (~> 3.1)
+    activerecord (4.2.5)
+      activemodel (= 4.2.5)
+      activesupport (= 4.2.5)
+      arel (~> 6.0)
+    activesupport (4.2.5)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    addressable (2.4.0)
+    arel (6.0.3)
+    builder (3.2.2)
+    concurrent-ruby (1.0.0)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    domain_name (0.5.25)
+      unf (>= 0.0.5, < 1.0.0)
+    erubis (2.7.0)
+    factory_girl (4.5.0)
+      activesupport (>= 3.0.0)
+    factory_girl_rails (4.5.0)
+      factory_girl (~> 4.5.0)
+      railties (>= 3.0.0)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.2.9.1)
+    github_api (0.13.1)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      multi_json (>= 1.7.5, < 2.0)
+      oauth2
+    globalid (0.3.6)
+      activesupport (>= 4.1.0)
+    hash_mapper (0.2.1)
+      activesupport (~> 4)
+    hashie (3.4.3)
+    highline (1.7.8)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    httparty (0.13.7)
+      json (~> 1.8)
+      multi_xml (>= 0.5.2)
+    i18n (0.7.0)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    jquery-rails (4.1.0)
+      rails-dom-testing (~> 1.0)
+      railties (>= 4.2.0)
+      thor (>= 0.14, < 2.0)
+    json (1.8.3)
+    jwt (1.5.2)
+    loofah (2.0.3)
+      nokogiri (>= 1.5.9)
+    macaddr (1.7.1)
+      systemu (~> 2.6.2)
+    maestrano (0.12.2)
+      httparty (~> 0.13)
+      json (~> 1.8)
+      mime-types (~> 1.25)
+      nokogiri (>= 1.5.0)
+      rest-client (~> 1.4)
+      uuid (~> 2.3)
+    maestrano-rails (0.14.0)
+      jquery-rails
+      maestrano (~> 0.12.2)
+      rails
+    mail (2.6.3)
+      mime-types (>= 1.16, < 3)
+    mime-types (1.25.1)
+    mini_portile2 (2.0.0)
+    minitest (5.8.3)
+    multi_json (1.11.2)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    netrc (0.11.0)
+    nokogiri (1.6.7.2)
+      mini_portile2 (~> 2.0.0.rc2)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.6.4)
+    rack-test (0.6.3)
+      rack (>= 1.0)
+    rails (4.2.5)
+      actionmailer (= 4.2.5)
+      actionpack (= 4.2.5)
+      actionview (= 4.2.5)
+      activejob (= 4.2.5)
+      activemodel (= 4.2.5)
+      activerecord (= 4.2.5)
+      activesupport (= 4.2.5)
+      bundler (>= 1.3.0, < 2.0)
+      railties (= 4.2.5)
+      sprockets-rails
+    rails-deprecated_sanitizer (1.0.3)
+      activesupport (>= 4.2.0.alpha)
+    rails-dom-testing (1.0.7)
+      activesupport (>= 4.2.0.beta, < 5.0)
+      nokogiri (~> 1.6.0)
+      rails-deprecated_sanitizer (>= 1.0.1)
+    rails-html-sanitizer (1.0.2)
+      loofah (~> 2.0)
+    railties (4.2.5)
+      actionpack (= 4.2.5)
+      activesupport (= 4.2.5)
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.5.0)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    rspec-core (3.4.1)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-rails (3.4.0)
+      actionpack (>= 3.0, < 4.3)
+      activesupport (>= 3.0, < 4.3)
+      railties (>= 3.0, < 4.3)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    shoulda (3.5.0)
+      shoulda-context (~> 1.0, >= 1.0.1)
+      shoulda-matchers (>= 1.4.1, < 3.0)
+    shoulda-context (1.2.1)
+    shoulda-matchers (2.8.0)
+      activesupport (>= 3.0.0)
+    simplecov (0.11.1)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    sprockets (3.5.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.0.0)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.11)
+    systemu (2.6.5)
+    thor (0.19.1)
+    thread_safe (0.3.5)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.1)
+    uuid (2.3.8)
+      macaddr (~> 1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  factory_girl_rails
+  hash_mapper (~> 0.2.1)
+  jeweler (~> 2.0.1)
+  maestrano-rails (~> 0.14.0)
+  rdoc (~> 3.12)
+  rspec-rails
+  shoulda
+  shoulda-matchers
+  simplecov
+  sqlite3
+
+BUNDLED WITH
+   1.10.6

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Maestrano
+
+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,138 @@
+<p align="center">
+  <img src="https://raw.github.com/berardpi/maestrano-connector-rails/master/maestrano.png" alt="Maestrano Logo">
+  <br/>
+  <br/>
+</p>
+
+Maestrano Connector Engine to implements data syncrhonization between an external application API and Connec!.
+
+Maestrano Connector Integration is currently in closed beta. Want to know more? Send us an email to <contact@maestrano.com>.
+
+- - -
+
+1. [Getting Setup](#getting-setup)
+2. [Getting Started](#getting-started)
+  * [Integration with Maestrano](#integration-with-maestrano)
+  * [Integration with the external application](#integration-with-the-external-application)
+3. [Preparing synchronizations](#preparing-synchronizations)
+  * [External.rb](#external.rb)
+  * [Entity.rb](#entity.rb)
+  * [Mapping entities](#mapping-entities)
+4. [Pages controllers and views](#pages-controllers-and-views)
+5. [Complex entities](#complex-entities)
+
+- - -
+
+## Getting Setup
+Before integrating with us you will need an Connec!™ API ID and Connec!™ API Key. You'll also need to have the connector application created on Maestrano in order to realize the authentication with Maestrano.
+
+## Getting Started
+Create a new rails application using the connector template
+```console
+rails new <project_name> -m https://raw.githubusercontent.com/Berardpi/maestrano-connector-template/master/maestrano-connector-template.rb
+```
+
+If and only if you have an error in the template's rails generate step, you'll need to re-run the following command in your project folder:
+```console
+bundle
+rails g connector:install
+rails g delayed_job:active_record
+rake db:migrate
+```
+
+### Integration with Maestrano
+
+First thing to do is to put your Connec!™ API keys in the config/application.yml:
+```ruby
+connec_api_id: 'API_ID'
+connec_api_key: 'API_KEY'
+```
+
+The only other thing you need to do is to set your configuration in config/initializers/maestrano.rb. The one line you need to look for and change is:
+```ruby
+config.app.host = 'http://path_to_app'
+```
+The rest of the config has default values, so you can take a look but you don't really need to change anything else.
+
+Please note that the connectors support multi-tenancy, so you may have to set up configuration for tenant other than Maestrano (the default one).
+
+Those configuration are automatically retrieve by Maestrano via a metadata endpoint that is provided by the gem, so you're all setup as it is.
+
+Time to test! If your launch your application (please make sure that you launch the application on the same path as the one in the config file). If you click on the 'Link your Maestrano account' link on your connector home page, you should be able to do a full sso process with Maestrano.
+
+### Integration with the external application
+
+Now that you're all setup with Maestrano, it's time to take a look at the external application you are integrating with. Hopefully it has one or several gems for both the authentication process and the API calls. In any case, you'll need to take a look at their documentation.
+
+You will probably have to request API keys and adds them to the application.yml alongside the Maestrano's ones.
+
+The connector engine is thought to be able to use oauth authentication processes, and an oauth_controller is provided as an example. Please note that it is only an example and you will have to implements most of it, and to create the needed routes, and use them in the provided view.
+
+If all went well, you should now be able to use the 'Link this company to...' link on the home page. Congrats!
+
+## Preparing synchronizations
+
+The aim of the connector is to perform synchronizations between Connec!™ and the external application, meaning fetching data on both ends, process them, and push the result to the relevant end. The Connec!™ part and the synchronization process itself is handle by the engine, so all you have to do is to implements some methods to work with the external application.
+
+### External.rb
+
+First file to look for is the external.rb class (in models/maestrano/connector/rails/). It contains two methods that you need to implements:
+
+* external_name, which is used fr logging purpose only, and should only return the name of the external application, e.g.
+```ruby
+def self.external_name
+  'This awesome CRM'
+end
+```
+* get_client, which should return either the external application gem api client, or, in the worst case, a custom HTTParty client.
+
+
+### Entity.rb
+
+The second important file is the entity.rb class (in the same folder). It contains a method to declare the entity synchronizable by your connector (more on that later), some methods to get and push data to the external application api, and lastly two methods to extract id and update date from the entity format sent by the external application.
+
+The details of each methods are explained in the entity.rb file provided.
+
+### Mapping entities
+
+Now that you're all setup with both Connec!™ and the external application, it's time to decide which entities (contacts, accounts, events, ...) you want to synchronize. For each type of entity your connector will synchronize, you will need to create a class that inherits from Maestrano::Connector::Rails::Entity.
+
+An example of such a class in provided in the models/entities/ folder, and demonstrates which methods you'll need to implements for each entity. The main thing to do is the mapping between the external entity and the Connec!™ entity. For the mapping, we use the hash_mapper gem (<https://github.com/ismasan/hash_mapper>).
+
+This type of entity class enable 1 to 1 model correspondance. For more complex needs, please refer to the complex entity section below.
+
+You'll find the connec API documentation here: <http://maestrano.github.io/connec/>, and should also refer to the external application API documentation.
+
+Also don"t forget that each entity your connector synchronize should be declare in the entity.rb class, and, because the synchronizable entities are stored in th db for each organization, you'll need to create a migration for exisiting organization if you add an entity.
+
+#### Overriding methods
+
+To fit each entity specific need, you can overide all methods define in the entity class, including those implemented by the engine.
+
+In particular, you will probably need to override the mapping methods to realize reference between entities (this can't be done during the mapping because it requires the organization id).
+
+For example:
+```ruby
+def map_to_connec(entity, organization)
+  if id = entity['AccountId']
+    idmap = Maestrano::Connector::Rails::IdMap.find_by(external_entity: 'account', external_id: id, organization_id: organization.id, connec_entity: 'organization')
+    entity['AccountId'] = idmap ? idmap.connec_id : ''
+  end
+  self.mapper_class.denormalize(entity)
+end
+```
+
+## Pages controllers and views
+
+The home and admin pages views and controllers are provided as example, but you are free to customize them and the styling is left for you to do.
+
+## Complex entities
+
+For more complex correspondances, like 1 to many or many to many ones, you can use the complex entity workflow. To see how it works, you can run
+```console
+rails g connector:complex_entity
+```
+
+This will generate some example files demonstrating a 1 to 2 correspondance between Connec!™ person and external contact and lead data models.
+
+The complex entities workflow uses two methods to pre-process data which you have to implements for each complex entity (see contact_and_lead.rb). They are called before the mapping step, and you can use them to perform any data model specific operations.

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = "maestrano-connector-rails"
+  gem.homepage = "http://github.com/maestrano/maestrano-connector-rails"
+  gem.license = "MIT"
+  gem.summary = "Rails framework to build connector with Maestrano"
+  gem.description = "Maestrano is the next generation marketplace for SME applications. See https://maestrano.com for details."
+  gem.email = "pierre.berard@maestrano.com"
+  gem.authors = ["Pierre Berard"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+
+task :default => :spec