Class: AtlasRb::Community

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

Overview

A top-level grouping in the Atlas hierarchy.

Communities are organizational containers — they hold Collections and, optionally, sub-Communities. Most institutional structure (departments, programs, projects) is modeled as a tree of Communities with Collections at the leaves.

See also: Collection, Work.

Constant Summary collapse

ROUTE =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Atlas REST endpoint prefix for this resource.

"/communities/"

Class Method Summary collapse

Methods inherited from Resource

permissions, preview

Methods included from FaradayHelper

#connection, #multipart

Class Method Details

.children(id, nuid: nil) ⇒ Array<String>

List the immediate children (sub-Communities and Collections) of a Community.

The endpoint returns just the noids; resolve each through Resource.find (which dispatches by type) when richer payloads are needed.

Examples:

AtlasRb::Community.children("c-123")
# => ["fn106x926", "kw52j804p"]

Parameters:

  • id (String) —

    the parent Community ID.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Array<String>) —

    child noids from GET /communities/<id>/children.



126
127
128
 
# File 'lib/atlas_rb/community.rb', line 126

def self.children(id, nuid: nil)
  JSON.parse(connection({}, nuid).get(ROUTE + id + '/children')&.body)
end

.create(id = nil, xml_path = nil, nuid: nil) ⇒ Hash

Create a new Community, optionally seeded with MODS metadata.

Pass id = nil to create a top-level Community; pass a Community ID to nest the new Community beneath an existing one.

Examples:

Top-level community, no metadata

AtlasRb::Community.create(nil)

Sub-community seeded from MODS

AtlasRb::Community.create("c-parent", "/tmp/dept-mods.xml")

Parameters:

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

    the parent Community ID, or nil for a top-level Community.

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

    optional path to a MODS XML file. When given, the Community is created and immediately patched with the metadata in the file; the returned Hash reflects the patched state.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Hash) —

    the created Community payload (post-update if xml_path was supplied).



54
55
56
57
58
59
60
 
# File 'lib/atlas_rb/community.rb', line 54

def self.create(id = nil, xml_path = nil, nuid: nil)
  result = AtlasRb::Mash.new(JSON.parse(connection({ parent_id: id }, nuid).post(ROUTE)&.body))["community"]
  return result unless xml_path.present?

  update(result["id"], xml_path, nuid: nuid)
  find(result["id"], nuid: nuid)
end

.destroy(id, nuid: nil) ⇒ Faraday::Response

Delete a Community.

Examples:

AtlasRb::Community.destroy("c-123")

Parameters:

  • id (String) —

    the Community ID.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Faraday::Response) —

    the raw delete response.



72
73
74
 
# File 'lib/atlas_rb/community.rb', line 72

def self.destroy(id, nuid: nil)
  connection({}, nuid).delete(ROUTE + id)
end

.find(id, nuid: nil) ⇒ Hash

Fetch a single Community by ID.

Examples:

AtlasRb::Community.find("c-123")
# => { "id" => "c-123", "title" => "College of Engineering", ... }

Parameters:

  • id (String) —

    the Community ID.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Hash) —

    the "community" object from the JSON response, already unwrapped.



29
30
31
 
# File 'lib/atlas_rb/community.rb', line 29

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

.metadata(id, values, nuid: nil) ⇒ Hash

Patch individual descriptive-metadata fields without uploading a full MODS document.

Scoped to user-authored descriptive metadata only. Programmatic writes of machine-set Delegate URIs (thumbnails) have their own purpose-specific endpoint — see set_thumbnails.

Examples:

AtlasRb::Community.metadata("c-123", title: "New Name")

Parameters:

  • id (String) —

    the Community ID.

  • values (Hash) —

    field-level metadata updates (shape determined by the Atlas server, typically a mapping from MODS field name to value).

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Hash) —

    the parsed JSON response.



165
166
167
 
# File 'lib/atlas_rb/community.rb', line 165

def self.metadata(id, values, nuid: nil)
  AtlasRb::Mash.new(JSON.parse(connection({ metadata: values }, nuid).patch(ROUTE + id)&.body))
end

.mods(id, kind = nil, nuid: nil) ⇒ String

Fetch the Community's MODS representation in the requested format.

Examples:

HTML rendering for display

AtlasRb::Community.mods("c-123", "html")

Parameters:

  • id (String) —

    the Community ID.

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

    one of "json" (default when omitted), "html", or "xml". When nil, Atlas returns its default representation.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (String) —

    the raw response body (JSON, HTML, or XML serialized as a string).



213
214
215
216
217
218
 
# File 'lib/atlas_rb/community.rb', line 213

def self.mods(id, kind = nil, nuid: nil)
  # json default, html, xml
  connection({}, nuid).get(
    ROUTE + id + '/mods' + (kind.present? ? ".#{kind}" : '')
    )&.body
end

.restore(id, nuid:) ⇒ Faraday::Response

Restore a previously tombstoned Community.

Operator-only. Restoration is intentionally not exposed in any end-user UI; call this from a Rails console session (or a future admin panel) when the library has decided an object should come back.

Examples:

Operator restoring from bundle exec rails console

AtlasRb::Community.restore("c-123", nuid: "000000002")

Parameters:

  • id (String) —

    the Community ID.

  • nuid (String) —

    the acting user's NUID.

Returns:

  • (Faraday::Response) —

    the raw response.



107
108
109
 
# File 'lib/atlas_rb/community.rb', line 107

def self.restore(id, nuid:)
  connection({}, nuid).post(ROUTE + id + '/restore')
end

.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil) ⇒ AtlasRb::Mash

Attach the three thumbnail/preview Delegate URIs to a Community.

Community-level mirror of Work.set_thumbnails. Atlas dispatches each non-blank URI to its matching Delegate role (thumbnail_image / thumbnail_image_2x / preview_image) via DelegateUpdater. Missing keys are left untouched.

Examples:

AtlasRb::Community.set_thumbnails(
  "c-123",
  thumbnail:    "https://iiif.example.edu/iiif/3/m.jp2/full/!85,85/0/default.jpg",
  thumbnail_2x: "https://iiif.example.edu/iiif/3/m.jp2/full/!170,170/0/default.jpg",
  preview:      "https://iiif.example.edu/iiif/3/m.jp2/full/500,/0/default.jpg"
)

Parameters:

  • id (String) —

    the Community ID.

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

    IIIF URI for the ~85² thumbnail.

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

    IIIF URI for the ~170² 2x thumbnail.

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

    IIIF URI for the ~500w preview image.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:



192
193
194
195
196
197
 
# File 'lib/atlas_rb/community.rb', line 192

def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil, nuid: nil)
  body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid).patch(ROUTE + id + '/thumbnails', JSON.dump(body))&.body
  ))
end

.tombstone(id, nuid:) ⇒ Faraday::Response

Tombstone (withdraw) a Community.

The Community remains in Atlas storage but is marked as withdrawn: search and show pages return a withdrawn stub for every user. Atlas rejects the request with 422 has_live_children if the Community still has live (non-tombstoned) members.

Examples:

AtlasRb::Community.tombstone("c-123", nuid: "000000002")

Parameters:

  • id (String) —

    the Community ID.

  • nuid (String) —

    the acting user's NUID, stamped on the resource as tombstoned_by for audit purposes.

Returns:

  • (Faraday::Response) —

    the raw response. 200/204 on success; 422 with {"code":"has_live_children"} if the Community is not empty.



91
92
93
 
# File 'lib/atlas_rb/community.rb', line 91

def self.tombstone(id, nuid:)
  connection({}, nuid).post(ROUTE + id + '/tombstone')
end

.update(id, xml_path, nuid: nil) ⇒ Hash

Replace a Community's metadata by uploading a MODS XML document.

Examples:

AtlasRb::Community.update("c-123", "/tmp/community-mods.xml")

Parameters:

  • id (String) —

    the Community ID.

  • xml_path (String) —

    path to a MODS XML file on disk.

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

    optional acting user's NUID, forwarded as the User: header. Required for cerberus-token requests; legacy bearer tokens still resolve without it.

Returns:

  • (Hash) —

    the parsed JSON response from the patch.



141
142
143
144
145
146
 
# File 'lib/atlas_rb/community.rb', line 141

def self.update(id, xml_path, nuid: nil)
  payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                       "application/xml",
                                                       File.basename(xml_path)) }
  AtlasRb::Mash.new(JSON.parse(multipart(nuid).patch(ROUTE + id, payload)&.body))
end