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) ⇒ 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.

Returns:

  • (Array<AtlasRb::Mash>) —

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



271
272
273
 
# File 'lib/atlas_rb/work.rb', line 271

def self.assets(id)
  JSON.parse(connection({}).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.



145
146
147
 
# File 'lib/atlas_rb/work.rb', line 145

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

.create(id, xml_path = nil, idempotency_key: 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.

Returns:

  • (Hash) —

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



86
87
88
89
90
91
92
93
94
 
# File 'lib/atlas_rb/work.rb', line 86

def self.create(id, xml_path = nil, idempotency_key: nil)
  result = AtlasRb::Mash.new(JSON.parse(
    connection({ collection_id: id }, nil, 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.



103
104
105
 
# File 'lib/atlas_rb/work.rb', line 103

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

.find(id) ⇒ 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.

Returns:

  • (Hash) —

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



25
26
27
 
# File 'lib/atlas_rb/work.rb', line 25

def self.find(id)
  AtlasRb::Mash.new(JSON.parse(connection({}).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).



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

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) ⇒ 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.

Returns:

  • (Hash) —

    the parsed JSON response.



194
195
196
 
# File 'lib/atlas_rb/work.rb', line 194

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

.mods(id, kind = 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".

Returns:

  • (String) —

    the raw response body in the requested format.



284
285
286
287
288
289
 
# File 'lib/atlas_rb/work.rb', line 284

def self.mods(id, kind = nil)
  # json default, html, xml
  connection({}).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.



161
162
163
 
# File 'lib/atlas_rb/work.rb', line 161

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

.set_image_derivatives(id, small: nil, medium: nil, large: 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.

Returns:



249
250
251
252
253
254
 
# File 'lib/atlas_rb/work.rb', line 249

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

.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: 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.

Returns:



220
221
222
223
224
225
 
# File 'lib/atlas_rb/work.rb', line 220

def self.set_thumbnails(id, thumbnail: nil, thumbnail_2x: nil, preview: nil)
  body = { thumbnail: thumbnail, thumbnail_2x: thumbnail_2x, preview: preview }.compact
  AtlasRb::Mash.new(JSON.parse(
    connection({}).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.



122
123
124
 
# File 'lib/atlas_rb/work.rb', line 122

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

.update(id, xml_path) ⇒ 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.

Returns:

  • (Hash) —

    the parsed JSON response from the patch.



173
174
175
176
177
178
 
# File 'lib/atlas_rb/work.rb', line 173

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