Class: AtlasRb::Work

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

Overview

The bibliographic unit in Atlas — an article, thesis, dataset, image, etc.

A Work belongs to exactly one Collection and aggregates one or more FileSets, each of which holds binary content via a Blob. MODS metadata is attached at the Work level.

See also: Collection, FileSet, Blob.

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.

"/works/"

Class Method Summary collapse

Methods inherited from Resource

permissions, preview

Methods included from FaradayHelper

#connection, #multipart

Class Method Details

.assets(id, nuid: nil) ⇒ Array<AtlasRb::Mash>

List the assets attached to a Work — Blobs and Delegates alike.

Useful for building download UIs — the response includes enough to render each entry's display name, size or uri, and download URL. The shape is polymorphic: Blob-backed entries carry fields like size, while Delegate-backed entries carry uri. Callers should duck-type on the field they need rather than expecting a single schema.

Examples:

AtlasRb::Work.assets("w-789").each { |a| puts a.label }

Parameters:

  • id (String) —

    the Work 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<AtlasRb::Mash>) —

    the listing from GET /works/<id>/assets, one entry per attached asset.



292
293
294
 
# File 'lib/atlas_rb/work.rb', line 292

def self.assets(id, nuid: nil)
  JSON.parse(connection({}, nuid).get(ROUTE + id + '/assets')&.body).map { |entry| AtlasRb::Mash.new(entry) }
end

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

Mark a Work complete.

Cerberus's bulk-deposit job calls this once it has confirmed all expected children (FileSets / Blobs) are deposited. Atlas's monitoring query GET /works?in_progress=true then drops this Work from the "stuck" list.

Idempotent on the server: calling complete on an already-complete Work is a no-op — Atlas simply re-saves with in_progress: false. Atlas does not currently stamp a completed_by audit field; the nuid: parameter is plumbed through for parity with the other lifecycle bindings and in case Atlas adds completion audit later.

Examples:

AtlasRb::Work.complete("w-789")

Parameters:

  • id (String) —

    the Work ID.

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

    optional NUID of the acting user.

Returns:

  • (Faraday::Response) —

    the raw response. Status 200 on success.



151
152
153
 
# File 'lib/atlas_rb/work.rb', line 151

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

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

Create a new Work in an existing Collection.

Note: unlike Community.create and Collection.create, the id parameter here is the parent Collection ID. The underlying request uses the collection_id query param rather than parent_id.

Examples:

Empty work, metadata to be added later

AtlasRb::Work.create("col-456")

Work seeded from MODS

AtlasRb::Work.create("col-456", "/tmp/work-mods.xml")

Retry-safe bulk-deposit create

key = SecureRandom.uuid
AtlasRb::Work.create("col-456", idempotency_key: key)

Parameters:

  • id (String) —

    the parent Collection ID.

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

    optional path to a MODS XML file. When given, the Work is created and immediately patched with the metadata in the file.

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

    optional UUID. A repeat call with the same key returns the originally-created Work instead of creating a new one (or 410 if it has since been tombstoned, or 410 with no body if it has been hard-deleted). Keys are scoped to the acting user and only apply to the initial POST /works — the optional follow-up PATCH/GET when xml_path is given do not carry the key. The caller (e.g. Cerberus's Solid Queue job) generates and persists the UUID; this gem does not mint keys.

  • 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 Work payload (post-update if xml_path was supplied).



92
93
94
95
96
97
98
99
100
 
# File 'lib/atlas_rb/work.rb', line 92

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

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

.destroy(id) ⇒ Faraday::Response

Delete a Work.

Examples:

AtlasRb::Work.destroy("w-789")

Parameters:

  • id (String) —

    the Work ID.

Returns:

  • (Faraday::Response) —

    the raw delete response.



109
110
111
 
# File 'lib/atlas_rb/work.rb', line 109

def self.destroy(id)
  connection({}).delete(ROUTE + id)
end

.find(id, nuid: nil) ⇒ Hash

Fetch a single Work by ID.

Examples:

AtlasRb::Work.find("w-789")
# => { "id" => "w-789", "title" => "An Article", ... }

Parameters:

  • id (String) —

    the Work 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 "work" object, already unwrapped from the JSON response.



28
29
30
 
# File 'lib/atlas_rb/work.rb', line 28

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

.list(in_progress: nil, page: nil, per_page: nil) ⇒ AtlasRb::Mash

List Works, paginated.

Wraps GET /works. Returns the full pagination envelope rather than a bare array so callers can page through results — the shape matches Community.children and Collection.children.

Examples:

Find stuck deposits

AtlasRb::Work.list(in_progress: true)

Page through all works

AtlasRb::Work.list(page: 2, per_page: 50)

Parameters:

  • in_progress (Boolean, nil) (defaults to: nil) —

    when set, filter to Works whose in_progress flag matches. Omit (or pass nil) for "all works".

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

    1-indexed page number.

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

    page size override.

Returns:

  • (AtlasRb::Mash) —

    { "works" => [...], "pagination" => {...} }. Each entry in "works" is a Work summary (id, title, description, in_progress).



51
52
53
54
55
56
57
 
# File 'lib/atlas_rb/work.rb', line 51

def self.list(in_progress: nil, page: nil, per_page: nil)
  params = {}
  params[:in_progress] = in_progress unless in_progress.nil?
  params[:page]        = page        if page
  params[:per_page]    = per_page    if per_page
  AtlasRb::Mash.new(JSON.parse(connection(params).get(ROUTE)&.body))
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, image derivatives) have their own purpose-specific endpoints — see set_thumbnails and set_image_derivatives.

Examples:

AtlasRb::Work.metadata("w-789", title: "Revised Title")

Parameters:

  • id (String) —

    the Work ID.

  • values (Hash) —

    field-level metadata updates.

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



206
207
208
 
# File 'lib/atlas_rb/work.rb', line 206

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 Work's MODS representation in the requested format.

Examples:

AtlasRb::Work.mods("w-789", "html")

Parameters:

  • id (String) —

    the Work ID.

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

    one of "json" (default), "html", or "xml".

  • 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 in the requested format.



308
309
310
311
312
313
 
# File 'lib/atlas_rb/work.rb', line 308

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

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::Work.restore("w-789", nuid: "000000002")

Parameters:

  • id (String) —

    the Work ID.

  • nuid (String) —

    the acting user's NUID.

Returns:

  • (Faraday::Response) —

    the raw response.



167
168
169
 
# File 'lib/atlas_rb/work.rb', line 167

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

.set_image_derivatives(id, small: nil, medium: nil, large: nil, nuid: nil) ⇒ AtlasRb::Mash

Attach the three image-derivative Delegate URIs to a Work.

Sibling of set_thumbnails for the small_image / medium_image / large_image Delegate roles. Atlas dispatches each URI to its matching role via DelegateUpdater. The resulting Delegates are downloadable and surface through assets for the downloads UI. Missing keys are left untouched server-side; only the URIs you pass are upserted.

Examples:

AtlasRb::Work.set_image_derivatives(
  "w-789",
  small:  "https://iiif.example.edu/iiif/3/abc.jp2/full/800,/0/default.jpg",
  medium: "https://iiif.example.edu/iiif/3/abc.jp2/full/1600,/0/default.jpg",
  large:  "https://iiif.example.edu/iiif/3/abc.jp2/full/full/0/default.jpg"
)

Parameters:

  • id (String) —

    the Work ID.

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

    IIIF URI for the small derivative.

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

    IIIF URI for the medium derivative.

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

    IIIF URI for the large derivative.

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



267
268
269
270
271
272
 
# File 'lib/atlas_rb/work.rb', line 267

def self.set_image_derivatives(id, small: nil, medium: nil, large: nil, nuid: nil)
  body = { small: small, medium: medium, large: large }.compact
  AtlasRb::Mash.new(JSON.parse(
    connection({}, nuid).patch(ROUTE + id + '/image_derivatives', JSON.dump(body))&.body
  ))
end

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

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

Purpose-specific PATCH for the thumbnail_image / thumbnail_image_2x / preview_image Delegate roles. Atlas dispatches each URI to its matching role via DelegateUpdater. Distinct from metadata — these are machine-set IIIF URIs, not user-authored descriptive content. Missing keys are left untouched server-side; only the URIs you pass are upserted.

Examples:

AtlasRb::Work.set_thumbnails(
  "w-789",
  thumbnail:    "https://iiif.example.edu/iiif/3/abc.jp2/full/!85,85/0/default.jpg",
  thumbnail_2x: "https://iiif.example.edu/iiif/3/abc.jp2/full/!170,170/0/default.jpg",
  preview:      "https://iiif.example.edu/iiif/3/abc.jp2/full/500,/0/default.jpg"
)

Parameters:

  • id (String) —

    the Work 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:



235
236
237
238
239
240
 
# File 'lib/atlas_rb/work.rb', line 235

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

The Work remains in Atlas storage along with its FileSets and Blobs, but is marked as withdrawn: search and show pages return a withdrawn stub for every user. Unlike Communities and Collections, Works are always tombstoneable regardless of how many files they hold — the FileSets and Blobs ride along.

Examples:

AtlasRb::Work.tombstone("w-789", nuid: "000000002")

Parameters:

  • id (String) —

    the Work ID.

  • nuid (String) —

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

Returns:

  • (Faraday::Response) —

    the raw response.



128
129
130
 
# File 'lib/atlas_rb/work.rb', line 128

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

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

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

Examples:

AtlasRb::Work.update("w-789", "/tmp/work-mods.xml")

Parameters:

  • id (String) —

    the Work 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.



182
183
184
185
186
187
 
# File 'lib/atlas_rb/work.rb', line 182

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