Class: AtlasRb::Person

Inherits:
Resource show all
Defined in:
lib/atlas_rb/person.rb

Overview

A neutral curatorial identity in Atlas, distinct from the auth-side users directory. A Person correlates the several users rows that share a NUID and carries the authoritative, librarian-editable display_name (the SSO users.name is frequently wrong and is clobbered on every login), plus community affiliations.

Addressed by NOID (like Work/Collection) — the staff-facing NUID is kept server-side and never put in a public URL. So the positional id argument below is the person's NOID, and the nuid: / on_behalf_of: keywords keep their usual gem meaning (the acting principal). NUID stays the key only for Person.create (one Person per NUID — and there nuid: is the new person's NUID, acting principal coming from the ambient AtlasRb.config.default_nuid) and Person.resolve (the server-side name-resolution batch). Person.list is the NOID-keyed People-index source.

Create / update / affiliation writes are :system + admin on the server; a non-privileged caller gets a 403.

Constant Summary collapse

ROUTE = 
"/people/"

Constants included from FaradayHelper

FaradayHelper::ASSERTION_AUDIENCE, FaradayHelper::ASSERTION_ISSUER, FaradayHelper::ASSERTION_TTL

Class Method Summary collapse

Methods inherited from Resource

find_many, history, mods_version, mods_versions, permissions, preview

Methods included from FaradayHelper

#connection, #multipart, #system_connection, #with_file_part

Class Method Details

.add_affiliation(id, community_id, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Add a community affiliation (idempotent; audited server-side).

Parameters:

  • id (String) —

    the person's NOID.

  • community_id (String) —

    the community's NOID.

  • nuid (String, nil) (defaults to: nil) —

    acting principal.

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:

  • (AtlasRb::Mash) —

    the unwrapped "person" object, with the updated affiliated_community_ids.



111
112
113
114
115
116
 
# File 'lib/atlas_rb/person.rb', line 111

def self.add_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .post(ROUTE + id + "/affiliations", JSON.dump(community_id: community_id))&.body
  ))["person"]
end

.create(nuid:, display_name:, bio: nil, orcid: nil, title: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Create a Person. One Person per NUID — a duplicate NUID is a 409.

Parameters:

  • nuid (String) —

    the new person's NUID (the subject, not the actor).

  • display_name (String) —

    authoritative display name.

  • bio (String, nil) (defaults to: nil)
  • orcid (String, nil) (defaults to: nil)
  • title (String, nil) (defaults to: nil)
  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target (the acting principal itself comes from the ambient AtlasRb.config.default_nuid).

Returns:



78
79
80
81
82
83
 
# File 'lib/atlas_rb/person.rb', line 78

def self.create(nuid:, display_name:, bio: nil, orcid: nil, title: nil, on_behalf_of: nil)
  body = { nuid: nuid, display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nil, on_behalf_of: on_behalf_of).post(ROUTE, JSON.dump(body))&.body
  ))["person"]
end

.find(id, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Fetch a Person by NOID.

Parameters:

  • id (String) —

    the person's NOID.

  • nuid (String, nil) (defaults to: nil) —

    acting principal (signed into the assertion sub).

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:

  • (AtlasRb::Mash) —

    the unwrapped "person" object (carries the server-side nuid for callers that need it, e.g. depositor gating).



31
32
33
34
35
 
# File 'lib/atlas_rb/person.rb', line 31

def self.find(id, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id)&.body
  ))["person"]
end

.list(page: nil, per_page: nil, nuid: nil, on_behalf_of: nil) ⇒ Array<AtlasRb::Mash>

List people — the NOID-keyed People-index source. Returns the page's Persons (each with noid, display_name, and the server-side nuid), so a consumer builds the index and profiles entirely through atlas_rb without routing People through the catalog/Solr or exposing a NUID publicly.

Parameters:

  • page (Integer, nil) (defaults to: nil) —

    1-based page (server default when nil).

  • per_page (Integer, nil) (defaults to: nil) —

    page size (server default when nil; capped server-side).

  • nuid (String, nil) (defaults to: nil) —

    acting principal.

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:

  • (Array<AtlasRb::Mash>) —

    one unwrapped "person" per row on the page.



48
49
50
51
52
53
 
# File 'lib/atlas_rb/person.rb', line 48

def self.list(page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
  params = { page: page, per_page: per_page }.compact
  JSON.parse(
    connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body
  )["people"].map { |entry| AtlasRb::Mash.new(entry["person"]) }
end

.remove_affiliation(id, community_id, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Remove a community affiliation (tolerant; audited server-side).

Parameters:

  • id (String) —

    the person's NOID.

  • community_id (String) —

    the community's NOID.

  • nuid (String, nil) (defaults to: nil) —

    acting principal.

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:



125
126
127
128
129
130
 
# File 'lib/atlas_rb/person.rb', line 125

def self.remove_affiliation(id, community_id, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .delete(ROUTE + id + "/affiliations/" + community_id)&.body
  ))["person"]
end

.resolve(nuids, nuid: nil, on_behalf_of: nil) ⇒ Array<AtlasRb::Mash>

Batch-resolve people to their authoritative display_name in one call (supersedes the SSO users directory's resolve). Unresolved NUIDs drop.

Parameters:

  • nuids (Array<String>) —

    the NUIDs to resolve.

  • nuid (String, nil) (defaults to: nil) —

    acting principal.

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:

  • (Array<AtlasRb::Mash>) —

    one unwrapped "person" per resolved NUID.



62
63
64
65
66
 
# File 'lib/atlas_rb/person.rb', line 62

def self.resolve(nuids, nuid: nil, on_behalf_of: nil)
  JSON.parse(
    connection({ nuids: Array(nuids).join(",") }, nuid, on_behalf_of: on_behalf_of).get(ROUTE)&.body
  )["people"].map { |entry| AtlasRb::Mash.new(entry["person"]) }
end

.update(id, display_name: nil, bio: nil, orcid: nil, title: nil, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Edit a Person's authority fields. NUID is immutable and not patchable. Only supplied fields are changed.

Parameters:

  • id (String) —

    the person's NOID.

  • display_name (String, nil) (defaults to: nil)
  • bio (String, nil) (defaults to: nil)
  • orcid (String, nil) (defaults to: nil)
  • title (String, nil) (defaults to: nil)
  • nuid (String, nil) (defaults to: nil) —

    acting principal.

  • on_behalf_of (String, nil) (defaults to: nil) —

    acting-as target.

Returns:



96
97
98
99
100
101
 
# File 'lib/atlas_rb/person.rb', line 96

def self.update(id, display_name: nil, bio: nil, orcid: nil, title: nil, nuid: nil, on_behalf_of: nil)
  body = { display_name: display_name, bio: bio, orcid: orcid, title: title }.compact
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid, on_behalf_of: on_behalf_of).patch(ROUTE + id, JSON.dump(body))&.body
  ))["person"]
end