README.md in global-registry-bindings-0.0.6 vs README.md in global-registry-bindings-0.1.0

- old
+ new

@@ -47,36 +47,94 @@ ## 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. +* `:binding`: Type of Global Registry binding. Either `:entity` or `:relationship`. +(default: `:entity`) + +* `:id_column`: Column used to track the Global Registry ID for the model instance or relationship entity. +Can be a :string or :uuid column. (default: `:global_registry_id`) **[`:entity`, `:relationship`]** + +* `:type`: Global Registry entity type. Accepts a Symbol or a Proc. Symbol is the name of the entity type, Proc +is passed the model instance and must return a symbol which is the entity type. Default value is underscored +name of the model. Ex: ```type: proc { |model| model.name.to_sym }```. When used in a `:relationship`, `:type` +is a unique name to identify the relationship. **[`:entity`, `:relationship`]** + * `:push_on`: Array of Active Record lifecycle events used to push changes to Global Registry. -(default: `[:create, :update, :delete]`) +(default: `[:create, :update, :destroy]`) **[`:entity`]** + * `: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`) +global_registry_bindings in order to determine foreign_key for use in exclude_fields. Used to create a +hierarchy or to push child entity types. (Ex: person -> address) (default: `nil`) **[`:entity`]** + * `:parent_association_class`: Class name of the parent model. Required if `:parent_association` can not be used - to determine the parent class. This can happen if parent is defined by another gem, like `has_ancestry`. - (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`) +to determine the parent class. This can happen if parent is defined by another gem, like `ancestry`. +(default: `nil`) **[`:entity`]** + +* `:primary_association`: Name of the Active Record primary association. Must be defined before calling +global_registry_bindings in order to determine foreign_key for use in exclude_fields. (default: `nil`) +**[`:relationship`]** + +* `:primary_association_class`: Class name of the primary model. Required if `:primary_association` can not be +used to determine the parent class. This can happen if parent is defined by another gem, like `ancestry`. +(default: `self.class`) **[`:relationship`]** + +* `:primary_association_foreign_key`: Foreign Key column for the primary association. Used if foreign_key can +not be determined from `:primary_association`. (default: `:primary_association.foreign_key`) +**[`:relationship`]** + +* `:related_association`: Name of the Active Record related association. Active Record association must be +defined before calling global_registry_bindings in order to determine the foreign key. +(default: `nil`) **[`:relationship`]** + * `:related_association_class`: Class name of the related model. Required if `:related_association` can not be - used to determine the related class. (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. +used to determine the related class. (default: `nil`) **[`:relationship`]** + +* `:related_association_foreign_key`: Foreign Key column for the related association. Used if foreign_key can +not be determined from `:primary_association`. (default: `:primary_association.foreign_key`) +**[`:relationship`]** + +* `:primary_relationship_name`: Name of primary relationship role. Required if `:ensure_relationship_type` is +`true`. (default: `nil`) **[`:relationship`]** + +* `:related_relationship_name`: Name of the related relationship role. Required if `:ensure_relationship_type` +is `true`. (default: `nil`) **[`:relationship`]** + +* `:related_association_type`: Name of the related association entity_type. Required if unable to determined +`:type` from related. (default: `nil`) **[`:relationship`]** + +* `:related_global_registry_id`: Global Registry ID of a remote related entity. Proc or Symbol. Implementation +should cache this as it may be requested multiple times. (default: `nil`) **[`:relationship`]** + +* `:ensure_relationship_type`: Ensure Global Registry RelationshipType exists and is up to date. +(default: `true`) **[`:relationship`]** + +* `:ensure_entity_type`: Ensure Global Registry Entity Type exists and is up to date. +(default: `true`) **[`:entity`]** + +* `:client_integration_id`: Client Integration ID for relationship. Proc or Symbol. +(default: `:primary_association.id`) **[`:relationship`]** + +* `:exclude_fields`: Array, Proc or Symbol. Array of Model fields (as symbols) to exclude when pushing to Global +Registry. Array Will additionally include `:mdm_id_column` and `:parent_association` foreign key when defined. +If Proc, is passed type and model instance and should return an Array of the fields to exclude. If Symbol, +this should be a method name the Model instance responds to. It is passed the type and should return an Array +of fields to exclude. When Proc or Symbol are used, you must explicitly return the standard defaults. +(default: `[:id, :created_at, :updated_at, :global_registry_id]`) **[`:entity`, `:relationship`]** + +* `:extra_fields`: Additional fields to send to Global Registry. Hash, Proc or Symbol. As a Hash, names are the +keys and :type attributes are the values. Ex: `{language: :string}`. Name is a symbol and type is an +ActiveRecord column type. As a Proc, it is passed the type and model instance, and should return a Hash. +As a Symbol, the model should respond to this method, is passed the type, and should return a Hash. +**[`:entity`, `:relationship`]** + +* `: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`) **[`:entity`]** + * `:mdm_timeout`: Only pull mdm information at most once every `:mdm_timeout`. (default: `1.minute`) +**[`:entity`]** ## 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` @@ -103,23 +161,9 @@ 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).