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

.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

.files(id) ⇒ Array<AtlasRb::Mash>

List the FileSets and Blobs attached to a Work.

Useful for building download UIs — the response includes enough to render each file's display name, size, and download URL.

Examples:

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

Parameters:

  • id (String) —

    the Work ID.

Returns:

  • (Array<AtlasRb::Mash>) —

    the listing from GET /works/<id>/files, one entry per attached file.



203
204
205
 
# File 'lib/atlas_rb/work.rb', line 203

def self.files(id)
  JSON.parse(connection({}).get(ROUTE + id + '/files')&.body).map { |entry| AtlasRb::Mash.new(entry) }
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 metadata fields without uploading a full MODS document.

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.



188
189
190
 
# File 'lib/atlas_rb/work.rb', line 188

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.



216
217
218
219
220
221
 
# File 'lib/atlas_rb/work.rb', line 216

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

.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