mais_person_client 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b872fec73c13f1df1ab4cb1fec9cf729502eafb10b5924d0082347e1258b7eb
-  data.tar.gz: 9e13fe7906ba9c46ed96fea26434c290349f27b5f7caf4f5c9f8b6035223f12c
+  metadata.gz: 7de338a07f3f6851a28604ddc6375e38928965e1a8a6d6647d0286a1cb6eb078
+  data.tar.gz: d1d6381bfeb5896caf46407522a699537bbee3c32247d46b9ad7618f3c8f1de4
 SHA512:
-  metadata.gz: 9ab061800050aaa112c0205ce54cbec61f8bdb257a95bb753a0b392ef13c7293c4abe4ac4e03f925e55e3e2f5bf0a8197d63b97ded760e77ea16ac4650262eb2
-  data.tar.gz: 788c40c60b666ddcc582a7168f7aa85309b7004db61b253efdcf727f19b1281925665023f37951e73ec1a99bf1490cc812493a746f723b303b2a832cd92a6920
+  metadata.gz: fa6af950fe76d47022e45f1694b29fe6ad9813613bf78debd3f3749fddfbc47abf5744e07f61182778c9e5903b3c24bbc26a6370e71ea1c387487ff1c953f30d
+  data.tar.gz: 1392a6fcc0e3672339d863171ba590d1ded0e8761c1798780e33cd3e62034b4f950b1de2139e1e562803cb822a7ab603c8c5bd148e056e609114639693405bf1

data/.rubocop.yml

@@ -450,22 +450,27 @@ RSpec/IncludeExamples: # new in 3.6
 Metrics/ClassLength:
   Exclude:
     - 'lib/mais_person_client/person.rb'
+    - 'lib/mais_person_client/affiliations.rb'
 
 Metrics/AbcSize:
   Exclude:
     - 'lib/mais_person_client/person.rb'
+    - 'lib/mais_person_client/affiliations.rb'
 
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/mais_person_client/person.rb'
+    - 'lib/mais_person_client/affiliations.rb'
 
 Metrics/MethodLength:
   Exclude:
     - 'lib/mais_person_client/person.rb'
+    - 'lib/mais_person_client/affiliations.rb'
 
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/mais_person_client/person.rb'
+    - 'lib/mais_person_client/affiliations.rb'
 
 # Allow longer examples in spec files for comprehensive testing
 RSpec/ExampleLength:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mais_person_client (0.0.2)
+    mais_person_client (0.0.4)
       activesupport (>= 4.2)
       faraday
       faraday-retry

data/README.md

@@ -42,9 +42,16 @@ result = client.fetch_user('nataliex') # get a single user by sunet, returns an
 person = MaisPersonClient::Person.new(result) # returns a class with the XML parsed
 person.sunetid
 => 'donaldduck'
-```
-
 
+result = client.fetch_affiliations('nataliex') # get a single users organization affiliations, returns an XML doc as a string
+affiliations = MaisPersonClient::Affiliations.new(result) # returns a class with the XML parsed
+# Get all affiliations
+affiliations_list = affiliations.affiliations
+active_faculty = affiliations.faculty_affiliations
+primary = affiliations.primary_affiliation
+primary_org_id = affiliations.primary_org_id
+all_org_ids = affiliations.org_ids
+```
 
 You can also invoke methods directly on the client class, which is useful in a Rails application environment where you might initialize the client in an
 initializer and then invoke client methods in many other contexts where you want to be sure configuration has already occurred, e.g.:
@@ -77,7 +84,7 @@ VCR gem is used to record the results of the API calls for the tests.  If you ne
 
 To record new cassettes:
 1. Join VPN.
-2. Temporarily adjust the configuration (api_key, api_cert for the MaIS UAT URL) at the top of `spec/mais_person_client_spec.rb` so it matches the real MaIS UAT environment.
+2. Temporarily adjust the configuration (fake_api_key, fake_api_cert for the MaIS UAT URL) at the top of `spec/spec_helper.rb` so it matches the real MaIS UAT environment.
 3. Add your new spec with a new cassette name (or delete a previous cassette to re-create it).
 4. Run just that new spec (important: else previous specs may use cassettes that have redacted credentials, causing your new spec to fail).
 5. You should get a new cassette with the name you specified in the spec.

data/lib/mais_person_client/affiliations.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+class MaisPersonClient
+  # Model for Affiliations from the MAIS Person API
+  class Affiliations
+    # Struct definitions for complex nodes
+    Department = Struct.new(:affnum, :name, :organization)
+    Organization = Struct.new(:acadid, :adminid, :level2orgid, :level2orgname, :regid, :name)
+    AffData = Struct.new(:affnum, :type, :code, :value)
+    Address = Struct.new(:affnum, :type, :visibility, :full_address, :line, :city, :state, :state_code,
+                         :postal_code, :country, :country_alpha2, :country_alpha3, :country_numeric)
+    Telephone = Struct.new(:affnum, :type, :visibility, :full_number, :icc, :area, :number)
+    Place = Struct.new(:affnum, :type, :address, :telephone)
+    AffiliationRecord = Struct.new(:affnum, :effective, :organization, :type, :visibility, :name,
+                                   :department, :description, :affdata, :place)
+
+    attr_reader :xml
+
+    def initialize(xml)
+      @xml = Nokogiri::XML(xml)
+      @xml.remove_namespaces!
+    end
+
+    # Root person attributes
+    def card
+      xml.root['card']
+    end
+
+    def listing
+      xml.root['listing']
+    end
+
+    def name_attr
+      xml.root['name']
+    end
+
+    def regid
+      xml.root['regid']
+    end
+
+    def relationship
+      xml.root['relationship']
+    end
+
+    def source
+      xml.root['source']
+    end
+
+    def sunetid
+      xml.root['sunetid']
+    end
+
+    def univid
+      xml.root['univid']
+    end
+
+    # Affiliations (multiple possible)
+    def affiliations
+      xml.xpath('//affiliation').map { |aff_node| build_affiliation(aff_node) }
+    end
+
+    # Convenience methods
+    def faculty_affiliations
+      affiliations.select { |aff| aff.type&.include?('faculty') }
+    end
+
+    def student_affiliations
+      affiliations.select { |aff| aff.type&.include?('student') }
+    end
+
+    def active_affiliations
+      affiliations.reject { |aff| aff.type&.include?('nonactive') }
+    end
+
+    def primary_affiliation
+      affiliations.find { |aff| aff.affnum == '1' }
+    end
+
+    def org_ids
+      xml.xpath('//organization/@adminid').map(&:value).uniq.compact
+    end
+
+    def primary_org_code
+      org_node = xml.at_xpath("//affiliation[@affnum='1']//organization")
+      org_node ? org_node['adminid'] : nil
+    end
+
+    private
+
+    def build_affiliation(aff_node)
+      department = build_department(aff_node.at_xpath('department'))
+      affdata = build_affdata_array(aff_node)
+      places = build_places_for_affiliation(aff_node)
+
+      AffiliationRecord.new(
+        aff_node['affnum'],
+        aff_node['effective'],
+        aff_node['organization'],
+        aff_node['type'],
+        aff_node['visibility'],
+        aff_node.children.first&.text&.strip,
+        department,
+        aff_node.at_xpath('description')&.text,
+        affdata,
+        places
+      )
+    end
+
+    def build_department(dept_node)
+      return nil unless dept_node
+
+      org_node = dept_node.at_xpath('organization')
+      organization = build_organization(org_node) if org_node
+
+      Department.new(
+        dept_node['affnum'],
+        dept_node.children.first&.text&.strip,
+        organization
+      )
+    end
+
+    def build_organization(org_node)
+      return nil unless org_node
+
+      Organization.new(
+        org_node['acadid'],
+        org_node['adminid'],
+        org_node['level2orgid'],
+        org_node['level2orgname'],
+        org_node['regid'],
+        org_node.text&.gsub(/\s+/, ' ')&.strip
+      )
+    end
+
+    def build_affdata_array(aff_node)
+      aff_node.xpath('affdata').map do |data_node|
+        AffData.new(
+          data_node['affnum'],
+          data_node['type'],
+          data_node['code'],
+          data_node.text&.strip
+        )
+      end
+    end
+
+    def build_places_for_affiliation(aff_node)
+      aff_node.xpath('place').map { |place_node| build_place(place_node) }
+    end
+
+    def build_place(place_node)
+      addresses = place_node.xpath('address').map { |addr_node| build_address(addr_node) }
+      telephones = place_node.xpath('telephone').map { |tel_node| build_telephone(tel_node) }
+
+      Place.new(
+        place_node['affnum'],
+        place_node['type'],
+        addresses,
+        telephones
+      )
+    end
+
+    def build_address(addr_node)
+      lines = addr_node.xpath('line').map { |line| line.text&.gsub(/\s+/, ' ')&.strip }
+      Address.new(
+        addr_node['affnum'],
+        addr_node['type'],
+        addr_node['visibility'],
+        addr_node.children.first&.text&.strip,
+        lines.length == 1 ? lines.first : lines,
+        addr_node.at_xpath('city')&.text,
+        addr_node.at_xpath('state')&.text,
+        addr_node.at_xpath('state')&.[]('code'),
+        addr_node.at_xpath('postalcode')&.text,
+        addr_node.at_xpath('country')&.text,
+        addr_node.at_xpath('country')&.[]('alpha2'),
+        addr_node.at_xpath('country')&.[]('alpha3'),
+        addr_node.at_xpath('country')&.[]('numeric')
+      )
+    end
+
+    def build_telephone(tel_node)
+      Telephone.new(
+        tel_node['affnum'],
+        tel_node['type'],
+        tel_node['visibility'],
+        tel_node.children.first&.text&.strip,
+        tel_node.at_xpath('icc')&.text&.strip,
+        tel_node.at_xpath('area')&.text&.strip,
+        tel_node.at_xpath('number')&.text&.strip
+      )
+    end
+  end
+end

data/lib/mais_person_client/person.rb

@@ -178,6 +178,30 @@ class MaisPersonClient
       xml.xpath('//affiliation').map { |aff_node| build_affiliation(aff_node) }
     end
 
+    # returns the primary role/type for the person (from affiliation with affnum 1)
+    def primary_role
+      affiliations.find { |aff| aff.affnum == '1' }&.type
+    end
+
+    # returns the org_id for the primary affiliation (affnum == '1')
+    def primary_org_code
+      # Find the affiliation with affnum == '1' and return the department's organization adminid
+      aff = affiliations.find { |a| a.affnum == '1' }
+      return nil unless aff
+
+      # department may be nil; department.adminid holds the org code
+      aff.department&.adminid
+    end
+
+    # indicates if a person is a member of the academic council
+    def academic_council?
+      affiliations.none? do |affiliation|
+        affiliation.affdata.any? do |affdata|
+          affdata.type == 'academic_council' && affdata.value&.downcase == 'non-member'
+        end
+      end
+    end
+
     # Identifiers (multiple)
     def identifiers
       xml.xpath('//identifier').map do |id_node|

data/lib/mais_person_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class MaisPersonClient
-  VERSION = '0.0.2'
+  VERSION = '0.0.4'
 end

data/lib/mais_person_client.rb

@@ -17,6 +17,25 @@ Zeitwerk::Loader.for_gem.setup
 class MaisPersonClient
   include Singleton
 
+  # Allowed tag values that can be requested from the API
+  ALLOWED_TAGS = %w[
+    name
+    title
+    biodemo
+    address
+    telephone
+    email
+    url
+    location
+    place
+    affiliation
+    identifier
+    privgroup
+    profile
+    emergency
+    visibility
+  ].freeze
+
   class << self
     # @param api_key [String] the api_key provided by MAIS
     # @param api_cert [String] the api_cert provided by MAIS
@@ -35,7 +54,7 @@ class MaisPersonClient
       self
     end
 
-    delegate :config, :fetch_user, to: :instance
+    delegate :config, :fetch_user, :fetch_user_affiliations, to: :instance
   end
 
   attr_accessor :config
@@ -43,14 +62,41 @@ class MaisPersonClient
   # Fetch a user details
   # @param [string] sunet to fetch
   # @return [<Person>, nil] user or nil if not found
-  def fetch_user(sunetid)
-    get_response("/doc/person/#{sunetid}", allow404: true)
+  # Fetch user details. Optionally accepts `tags:` which may be a String (comma
+  # separated) or an Array of tag names. Only tags listed in `ALLOWED_TAGS` are
+  # permitted; otherwise an ArgumentError is raised.
+  def fetch_user(sunetid, tags: nil)
+    params = build_tag_params(tags)
+
+    get_response("/doc/person/#{sunetid}", allow404: true, params: params)
+  end
+
+  # Fetch a user's affiliations
+  # @param [string] sunet to fetch
+  # @return [Array<Affiliation>, nil] affiliations or nil if not found
+  def fetch_user_affiliations(sunetid)
+    get_response("/doc/person/#{sunetid}/affiliation", allow404: true)
   end
 
   private
 
-  def get_response(path, allow404: false)
-    response = conn.get(path)
+  def build_tag_params(tags)
+    return nil unless tags
+
+    tags_array = if tags.is_a?(String)
+                   tags.split(',').map(&:strip)
+                 else
+                   Array(tags).map(&:to_s)
+                 end
+
+    invalid = tags_array - ALLOWED_TAGS
+    raise ArgumentError, "Invalid tag(s): #{invalid.join(', ')}" if invalid.any?
+
+    { tags: tags_array.join(',') }
+  end
+
+  def get_response(path, allow404: false, params: nil)
+    response = conn.get(path, params)
 
     return if allow404 && response.status == 404
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mais_person_client
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Peter Mangiafico
@@ -304,6 +304,7 @@ files:
 - README.md
 - Rakefile
 - lib/mais_person_client.rb
+- lib/mais_person_client/affiliations.rb
 - lib/mais_person_client/person.rb
 - lib/mais_person_client/unexpected_response.rb
 - lib/mais_person_client/version.rb