global-registry-bindings 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 70066ac805a72a8e4cd636ef0ae96c987d68900f
+  data.tar.gz: 1e2db15b8712f76b2cc51cfe1dfca72725b6ac2a
+SHA512:
+  metadata.gz: cf361f3f9f6a0d0d9f33c3f1ac287a7eeae6f5750d90a5d1d8308f9ca807dbc82568e1bb22afa946b9367a39fc39386435a65ee53bc2ddbccdaba6203e234f34
+  data.tar.gz: b121644f0d8fc5c50a10e803a9c3941349813e76926f42ebe92dc8316112f569713f444923dec4d0c1919f8ba0d956922140b6d60480e84f8e4c13c11f4fd2e1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2017 Cru
+
+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,126 @@
+# Global Registry Bindings
+
+Global Registry Bindings are a set of bindings to push ActiveRecord models to the Global Registry.
+
+
+## Installation
+
+Add to your Gemfile:
+```ruby
+gem 'global-registry-bindings'
+```
+
+Add a Global Registry initializer.
+`config/initializers/global_registry.rb`
+```ruby
+require 'global_registry'
+GlobalRegistry.configure do |config|
+  config.access_token = ENV['GLOBAL_REGISTRY_TOKEN'] || 'fake'
+  config.base_url = ENV['GLOBAL_REGISTRY_URL'] || 'https://backend.global-registry.org'
+end
+```
+
+Make sure sidekiq is configured. See [Using Redis](https://github.com/mperham/sidekiq/wiki/Using-Redis) for information.
+
+## Usage
+
+To make use of `global-registry-bindings` your model will need a few additional columns.
+To push models to Global Registry, you will need a `global_registry_id` column. You additionally need a
+`global_registry_mdm_id` to pull a Global Registry MDM (master data model) id. These columns should be of type 
+`:string` or `:uuid` and allow null values. Column names are customizable through options.
+```ruby
+class CreatePeople < ActiveRecord::Migration
+  def self.up
+    create_table :people do |t|
+      t.string :name
+      t.string :global_registry_id, :null => true, :index => true
+      t.string :global_registry_mdm_id, :null => true, :index => true
+    end
+  end
+
+  def self.down
+    drop_table :people
+  end
+end
+```
+
+Enable `global-registry-bindings` functionality by declaring `global_registry_bindings` on your model.
+```ruby
+class Person < ActiveRecord::Base
+  global_registry_bindings mdm_id_column: :global_registry_mdm_id
+end
+```
+
+## Options
+
+You can pass various options to the `global_registry_bindings` method. Configuration options are:
+
+* `:id_column`: Column used to track the Global Registry ID for the model instance. Can be a :string or :uuid column.
+(default: `:global_registry_id`) 
+* `:mdm_id_column`: Column used to enable MDM tracking and set the name of the column. MDM is disabled when this
+option is nil or empty. (default: `nil`)
+* `:type`: Global Registry entity type. Default value is underscored name of the model.
+* `:push_on`: Array of Active Record lifecycle events used to push changes to Global Registry.
+(default: `[:create, :update, :delete]`) 
+* `:parent_association`: Name of the Active Record parent association. Must be defined before calling
+global_registry_bindings in order to determine foreign_key field. (default: `nil`)
+* `:related_association`: Name of the Active Record related association. Setting this option changes the
+   global registry binding from entity to relationship. Active Record association must be defined before calling
+   global_registry_bindings in order to determine the foreign key. `:parent_relationship_name` and
+   `:related_relationship_name` must be set for relationship binding to work. (default: `nil`)
+* `:parent_relationship_name`: Name of parent relationship role. (default: `nil`)
+* `:related_relationship_name`: Name of the related relationship role. (default: `nil`)
+* `:exclude_fields`: Model fields to exclude when pushing to Global Registry. Will additionally include `:mdm_id_column`
+and `:parent_association` foreign key when defined. 
+(default:  `[:id, :created_at, :updated_at, :global_registry_id]`)
+* `:extra_fields`: Additional fields to send to Global Registry. This should be a hash with name as the key
+and :type attributes as the value. Ex: `{language: :string}`. Name is a symbol and type is an ActiveRecord column type.
+* `:mdm_timeout`: Only pull mdm information at most once every `:mdm_timeout`. (default: `1.minute`)
+
+## Values for `extra_fields`
+
+Values sent to Global Registry are calculated by sending the field `name` to the model. They can be overidden by
+aliasing an existing method, adding a new method to the model or by overriding the `entity_attributes_to_push`
+method. If a model does not respond to a name or raises a `NoMethodError`, the field will be omitted from the request.
+
+```ruby
+class Person < ActiveRecord::Base
+  # Person has first_name, last_name and guid columns
+  global_registry_bindings extra_fields: {full_name: :string, identity: :uuid, blargh: :integer},
+                           exclude_fields: %i[guid]
+  
+  # Person doesn't respond to 'blargh' so it is omitted from the attributes to push
+ 
+  alias_attribute :identity, :guid # Value for identity is aliased to guid
+  
+  # Value for full_name
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+  
+  # Override entity_attributes_to_push to add or modify fields and values
+  def entity_attributes_to_push
+    entity_attributes = super
+    entity_attributes[:authentication] = { guid: guid }
+    entity_attributes
+  end
+end
+```
+
+## Relationships
+
+Global Registry allows for relating two entities together (many-to-many) through a relationship. An example of this
+could be a Person to Person relationship. This relationship could be described as husband/spouse, or even
+leader/employee. You could also relate a Person to an Organization through an assignment. The assignment can track
+specific fields about the relationship.
+
+`global-registry-bindings` supports this through the `:parent_association` and `:related_association` options.
+Relationship roles, like husband/wife, are defined through the `:parent_relationship_name` and
+`:related_relationship_name` options.
+
+More information on Global Registry relationships and relationship types can be found
+[here](https://github.com/CruGlobal/global_registry_docs/wiki/About-Relationships)
+
+## Example Models
+
+Example models can be found in the [specs](https://github.com/CruGlobal/global-registry-bindings/tree/master/spec/internal/app/models).

data/lib/global_registry_bindings.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'active_support/lazy_load_hooks'
+require 'global_registry_bindings/global_registry_bindings'
+
+ActiveSupport.on_load(:active_record) do
+  ActiveRecord::Base.send :extend, GlobalRegistry::Bindings
+end

data/lib/global_registry_bindings/entity/delete_entity_methods.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'global_registry_bindings/workers/delete_gr_entity_worker'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module DeleteEntityMethods
+        extend ActiveSupport::Concern
+
+        included do
+          after_commit :delete_entity_from_global_registry_async, on: :destroy
+        end
+
+        def delete_entity_from_global_registry_async
+          return unless global_registry.id_value?
+          ::GlobalRegistry::Bindings::Workers::DeleteGrEntityWorker.perform_async(global_registry.id_value)
+        end
+      end
+    end
+  end
+end

data/lib/global_registry_bindings/entity/entity_methods.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'global_registry'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module EntityMethods
+        extend ActiveSupport::Concern
+
+        def entity_attributes_to_push
+          entity_attributes = self.class.columns_to_push.map do |name, type|
+            value_for_global_registry(name, type)
+          end.compact.to_h
+          entity_attributes[:client_integration_id] = id unless global_registry.exclude_fields
+                                                                               .include?(:client_integration_id)
+          entity_attributes[:client_updated_at] = updated_at.to_s(:db) if respond_to?(:updated_at)
+          entity_attributes[:parent_id] = global_registry.parent_id_value if global_registry.parent_is_self?
+          entity_attributes
+        end
+
+        def value_for_global_registry(name, type)
+          value = send(name)
+          return [name, value] if value.nil?
+          value = case type
+                  when :datetime, :date
+                    value.to_s(:db)
+                  when :boolean
+                    value ? 'true' : 'false'
+                  else
+                    value.to_s.strip
+                  end
+          [name, value]
+        rescue NoMethodError
+          nil
+        end
+
+        module ClassMethods
+          def columns_to_push
+            @columns_to_push ||= columns
+                                 .collect { |c| { c.name.underscore.to_sym => normalize_column_type(c.type, c.name) } }
+                                 .reduce(&:merge)
+                                 .reject { |k, _v| global_registry.exclude_fields.include? k }
+                                 .merge(global_registry.extra_fields)
+          end
+
+          protected
+
+          def normalize_column_type(type, name)
+            if type.to_s == 'text'
+              :string
+            elsif name.ends_with?('_id')
+              :uuid
+            else
+              type
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/global_registry_bindings/entity/entity_type_methods.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'global_registry'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module EntityTypeMethods
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          def push_entity_type
+            parent_entity_id = parent_entity_type_id
+            entity_type = Rails.cache.fetch(entity_type_cache_key, expires_in: 1.hour) do
+              GlobalRegistry::EntityType.get('filters[name]' => global_registry.type,
+                                             'filters[parent_id]' => parent_entity_id)['entity_types']&.first
+            end
+
+            unless entity_type
+              entity_type = GlobalRegistry::EntityType.post(entity_type: { name: global_registry.type,
+                                                                           parent_id: parent_entity_id,
+                                                                           field_type: 'entity' })['entity_type']
+            end
+
+            push_entity_type_fields(entity_type)
+            entity_type
+          end
+
+          def push_entity_type_fields(entity_type)
+            existing_fields = entity_type['fields']&.collect { |f| f['name'].to_sym } || []
+            columns_to_push
+              .reject { |k, _v| existing_fields.include? k }
+              .each do |name, type|
+              GlobalRegistry::EntityType.post(entity_type: { name: name,
+                                                             parent_id: entity_type['id'],
+                                                             field_type: type })
+            end
+          end
+
+          def parent_entity_type_id
+            parent_type = global_registry&.parent_type
+            return if parent_type.blank? || global_registry.parent_is_self?
+            parent_entity_type = global_registry.parent_class.send :push_entity_type
+            parent_entity_type&.dig('id')
+          end
+
+          def entity_type_cache_key
+            "GlobalRegistry::Bindings::EntityType::#{global_registry.type}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/global_registry_bindings/entity/mdm_methods.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'global_registry_bindings/workers/pull_mdm_id_worker'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module MdmMethods
+        extend ActiveSupport::Concern
+
+        included do
+          GlobalRegistry::Bindings::Workers.mdm_worker_class(self)
+          after_commit :pull_mdm_id_from_global_registry_async, on: %i[create update]
+        end
+
+        def pull_mdm_id_from_global_registry_async
+          "::GlobalRegistry::Bindings::Workers::#{global_registry.mdm_worker_class_name}".constantize
+                                                                                         .perform_async(self.class, id)
+        end
+
+        def pull_mdm_id_from_global_registry
+          unless global_registry.id_value?
+            raise GlobalRegistry::Bindings::RecordMissingGlobalRegistryId,
+                  "#{self.class.name} #{id} has no #{global_registry.id_column}; will retry"
+          end
+          entity = GlobalRegistry::Entity.find(global_registry.id_value, 'filters[owned_by]' => 'mdm')
+          mdm_entity_id = dig_global_registry_mdm_id_from_entity(entity, global_registry.type.to_s)
+          unless mdm_entity_id
+            raise GlobalRegistry::Bindings::EntityMissingMdmId,
+                  "GR entity #{global_registry.id_value} for #{self.class.name} #{id} has no mdm id; will retry"
+          end
+          update_column(global_registry.mdm_id_column, mdm_entity_id) # rubocop:disable Rails/SkipsModelValidations
+        end
+
+        def dig_global_registry_mdm_id_from_entity(entity, type)
+          Array.wrap(entity.dig('entity', type, "master_#{type}:relationship"))
+               .first # although there should not be more than one
+               .try(:[], "master_#{type}")
+        end
+      end
+    end
+  end
+end

data/lib/global_registry_bindings/entity/push_entity_methods.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'global_registry_bindings/workers/push_gr_entity_worker'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module PushEntityMethods
+        extend ActiveSupport::Concern
+
+        included do
+          after_commit :push_entity_to_global_registry_async, on: (global_registry.push_on - %i[delete])
+        end
+
+        def push_entity_to_global_registry_async
+          ::GlobalRegistry::Bindings::Workers::PushGrEntityWorker.perform_async(self.class, id)
+        end
+
+        def push_entity_to_global_registry
+          self.class.push_entity_type
+
+          if global_registry.parent_type.present? && !global_registry.parent_is_self?
+            create_dependent_entity_in_global_registry
+          elsif global_registry.id_value?
+            update_entity_in_global_registry
+          else
+            create_entity_in_global_registry
+          end
+        rescue RestClient::ResourceNotFound
+          global_registry.id_value = nil
+          push_entity_to_global_registry
+        end
+
+        def update_entity_in_global_registry
+          entity_attributes = { global_registry.type => entity_attributes_to_push }
+          GlobalRegistry::Entity.put(global_registry.id_value, entity: entity_attributes)
+        end
+
+        def create_entity_in_global_registry
+          if global_registry.parent_is_self? && global_registry.parent_id_value.blank?
+            # Push parent entity if it exists and is missing global_registry_id
+            global_registry.parent&.create_entity_in_global_registry
+          end
+          entity_attributes = { global_registry.type => entity_attributes_to_push }
+          entity = GlobalRegistry::Entity.post(entity: entity_attributes)
+          global_registry.id_value = dig_global_registry_id_from_entity(entity['entity'], global_registry.type)
+          update_column(global_registry.id_column, # rubocop:disable Rails/SkipsModelValidations
+                        global_registry.id_value)
+        end
+
+        # Create or Update a child entity (ex: :email_address is a child of :person)
+        def create_dependent_entity_in_global_registry # rubocop:disable Metrics/AbcSize
+          return if global_registry.parent.blank?
+          global_registry.parent.push_entity_to_global_registry if global_registry.parent_id_value.blank?
+          entity_attributes = {
+            global_registry.parent_type => {
+              client_integration_id: global_registry.parent.id,
+              global_registry.type => entity_attributes_to_push
+            }
+          }
+          entity = GlobalRegistry::Entity.put(global_registry.parent_id_value, entity: entity_attributes)
+          global_registry.id_value = dig_global_registry_id_from_entity(entity['entity'],
+                                                                        global_registry.type,
+                                                                        global_registry.parent_type)
+          update_column(global_registry.id_column, # rubocop:disable Rails/SkipsModelValidations
+                        global_registry.id_value)
+        end
+
+        def dig_global_registry_id_from_entity(entity, type, parent_type = nil)
+          return entity&.dig(type.to_s, 'id') unless parent_type
+          Array.wrap(entity&.dig(parent_type.to_s, type.to_s)).detect do |item|
+            item['client_integration_id'] == id.to_s
+          end&.dig('id')
+        end
+      end
+    end
+  end
+end

data/lib/global_registry_bindings/entity/push_relationship_methods.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'global_registry'
+require 'global_registry_bindings/workers/push_relationship_worker'
+
+module GlobalRegistry #:nodoc:
+  module Bindings #:nodoc:
+    module Entity #:nodoc:
+      module PushRelationshipMethods
+        extend ActiveSupport::Concern
+
+        included do
+          after_commit :push_relationship_to_global_registry_async, on: (global_registry.push_on - %i[delete])
+        end
+
+        def push_relationship_to_global_registry_async
+          ::GlobalRegistry::Bindings::Workers::PushRelationshipWorker.perform_async(self.class, id)
+        end
+
+        def push_relationship_to_global_registry
+          ensure_related_entities_have_global_registry_ids!
+          self.class.push_global_registry_relationship_type
+
+          if global_registry.id_value?
+            update_relationship_in_global_registry
+          else
+            create_relationship_in_global_registry
+          end
+        end
+
+        def update_relationship_in_global_registry
+          GlobalRegistry::Entity.put(global_registry.id_value, entity: entity_attributes_to_push)
+        end
+
+        def create_relationship_in_global_registry # rubocop:disable Metrics/AbcSize
+          entity = GlobalRegistry::Entity.put(global_registry.parent_id_value,
+                                              { entity:  { global_registry.parent_type => {
+                                                "#{global_registry.related_relationship_name}:relationship" =>
+                                                  entity_attributes_to_push.merge(global_registry.related_type =>
+                                                                                    global_registry.related_id_value)
+                                              }, client_integration_id: global_registry.parent.id } },
+                                              params: {
+                                                full_response: true,
+                                                fields: "#{global_registry.related_relationship_name}:relationship"
+                                              })
+          global_registry.id_value = global_registry_relationship_entity_id_from_entity entity
+          update_column(global_registry.id_column, # rubocop:disable Rails/SkipsModelValidations
+                        global_registry.id_value)
+          # Update relationship to work around bug in Global Registry
+          # - If current system doesn't own a copy of the parent entity, then creating a new relationship in the same
+          #   request will not add the relationship entity_type properties.
+          update_relationship_in_global_registry if global_registry.id_value?
+        end
+
+        def global_registry_relationship_entity_id_from_entity(entity)
+          relationships = Array.wrap entity.dig('entity', global_registry.parent_type.to_s,
+                                                "#{global_registry.related_relationship_name}:relationship")
+          relationships.detect do |rel|
+            cid = rel['client_integration_id']
+            cid = cid['value'] if cid.is_a?(Hash)
+            cid == id.to_s
+          end&.dig('relationship_entity_id')
+        end
+
+        def ensure_related_entities_have_global_registry_ids!
+          return if global_registry.parent_id_value.present? && global_registry.related_id_value.present?
+          # Enqueue push_entity worker for related entities missing global_registry_id and retry relationship push
+          names = []
+          [global_registry.parent, global_registry.related].each do |model|
+            next if model.global_registry.id_value?
+            names << "#{model.class.name}(#{model.id})"
+            model.push_entity_to_global_registry_async
+          end
+          raise GlobalRegistry::Bindings::RelatedEntityMissingGlobalRegistryId,
+                "#{self.class.name}(#{id}) has related entities [#{names.join ', '}] missing global_registry_id;" \
+                  ' will retry.'
+        end
+      end
+    end
+  end
+end