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 NUID, not NOID — the NUID is the correlation key consumers hold. So the positional id argument below is the person's NUID, and the nuid: / on_behalf_of: keywords keep their usual gem meaning (the acting principal). The one exception is Person.create, whose nuid: keyword is the new person's NUID (matching the gap's signature); the acting principal there comes from the ambient AtlasRb.config.default_nuid.

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 NUID.

  • 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.



90
91
92
93
94
95
 
# File 'lib/atlas_rb/person.rb', line 90

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:



57
58
59
60
61
62
 
# File 'lib/atlas_rb/person.rb', line 57

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 NUID.

Parameters:

  • id (String) —

    the person's NUID.

  • 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:



28
29
30
31
32
 
# File 'lib/atlas_rb/person.rb', line 28

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

.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 NUID.

  • 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:



104
105
106
107
108
109
 
# File 'lib/atlas_rb/person.rb', line 104

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.



41
42
43
44
45
 
# File 'lib/atlas_rb/person.rb', line 41

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 NUID.

  • 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:



75
76
77
78
79
80
 
# File 'lib/atlas_rb/person.rb', line 75

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