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/"
ASSOCIATION_TYPES =

The five relationship predicates Atlas accepts, carried here so a caller can build a select box without hard-coding the vocabulary. Adding a sixth needs an Atlas release, so this list cannot drift ahead of the server.

%w[
  is_codebook_for
  is_figure_for
  is_instructional_material_for
  is_supplemental_material_for
  is_transcription_of
].freeze

Constants inherited from Resource

Resource::TYPE_MAP

Constants included from FaradayHelper

FaradayHelper::ASSERTION_AUDIENCE, FaradayHelper::ASSERTION_ISSUER, FaradayHelper::ASSERTION_TTL, FaradayHelper::INSTRUMENTATION_EVENT

Class Method Summary collapse

Methods inherited from Resource

class_for, descendant_works, find_many, history, mods_version, mods_versions, permissions, preview, put_mods, reparent, set_permissions, set_thumbnails, tombstone

Methods included from FaradayHelper

#connection, #multipart, #read_body, #read_raw, #system_connection, #with_file_part

Class Method Details

.add_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil) ⇒ Array<String>

Add a linked membership: surface a Work in an additional Collection.

Wraps POST /works/<id>/linked_members with a collection_id body. This does not move the Work — its structural parent (a_member_of) is untouched; the Collection is added to a_linked_member_of. Atlas enforces two-sided authorization (edit on the Work and the target Collection) and the structural guards, surfacing failures as a 422. Permissions are never changed by this call.

Examples:

AtlasRb::Work.add_linked_member("w-789", "col-456")
# => ["col-456"]

Parameters:

  • work_id (String) —

    the Work ID.

  • collection_id (String) —

    the Collection to link the Work into.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Array<String>) —

    the Work's full set of linked Collection noids after the add — the affected sub-resource, so no follow-up linked_members GET is needed.

Raises:



635
636
637
638
639
640
 
# File 'lib/atlas_rb/work.rb', line 635

def self.add_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
  write_resource(
    connection({ collection_id: collection_id }, nuid, on_behalf_of: on_behalf_of)
      .post(ROUTE + work_id + '/linked_members')
  )
end

.assets(id, nuid: nil, on_behalf_of: 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.

Every entry (Blob and Delegate) also carries the advisory read gate set via set_derivative_permissions: gated (true if the asset must be authorized rather than fetched directly) and permission (the effective read-group set, or nil for guests, to whom group names are withheld).

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. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Array<AtlasRb::Mash>, nil) —

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

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



455
456
457
458
459
 
# File 'lib/atlas_rb/work.rb', line 455

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

.associate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil) ⇒ Hash

Assert that this Work stands in a typed relationship to another Work.

Wraps POST /works/<id>/associations with a work_id + type body. The edge is stored on this Work only; target reports the same edge under inbound. Asserting an edge that already exists is a no-op, and two Works can hold several different edges at once.

A cycle is permitted and meaningful — "A is a transcription of B" and "B is a figure for A" can both be true.

Examples:

AtlasRb::Work.associate("w-789", "w-123", type: "is_codebook_for")
# => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}

Parameters:

  • work_id (String) —

    the asserting Work's ID (the codebook, figure, …).

  • target_id (String) —

    the Work being pointed at (the dataset, article, …).

  • type (String) —

    one of ASSOCIATION_TYPES.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the Work's associations after the add, in the associations shape — so no follow-up GET is needed.

Raises:

  • (AtlasRb::WorkAssociationError) —

    if Atlas rejects the claim (HTTP 422): unknown type, unresolvable target, a non-Work target, the Work itself, or either end tombstoned. The envelope's error code is exposed as #code.

  • (AtlasRb::ForbiddenError) —

    if Atlas refuses the write (HTTP 403). Associating is admin / devolved-admin only, because the claim renders on the target's page too.

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such Work, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



766
767
768
769
770
771
 
# File 'lib/atlas_rb/work.rb', line 766

def self.associate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
  write_resource(
    connection({ work_id: target_id, type: type }, nuid, on_behalf_of: on_behalf_of)
      .post(ROUTE + work_id + '/associations')
  )
end

.associations(id, nuid: nil, on_behalf_of: nil) ⇒ Hash?

List a Work's typed associations with other Works.

Wraps GET /works/<id>/associations. An association is DRS v1's "associated works": a directed claim that one object is the codebook, figure, transcription, instructional material or supplemental material for another. Both objects stay separate records — this is not membership, and nothing moves in the containment tree.

The edge is stored once, on the Work that asserts it. Atlas derives the other direction, so outbound and inbound can never disagree.

Examples:

AtlasRb::Work.associations("w-789")
# => {"outbound" => {"is_codebook_for" => ["w-123"]}, "inbound" => {}}

Parameters:

  • id (String) —

    the Work ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash, nil) —

    {"outbound" => {predicate => [noid, …]}, "inbound" => {…}}. outbound is what this Work asserts, inbound what other Works assert about it. Predicates holding no edges are omitted, so both maps are {} for an unassociated Work.

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



726
727
728
 
# File 'lib/atlas_rb/work.rb', line 726

def self.associations(id, nuid: nil, on_behalf_of: nil)
  read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/associations'))
end

.clear_incomplete(id, nuid: nil, on_behalf_of: nil) ⇒ Hash

Clear the incomplete flag and its reason.

The repair half of mark_incomplete: call it from the same job when a later run succeeds, or by hand once an operator has fixed the Work. Both fields clear together — a reason without a flag would leave a stale cause on the Solr document.

Idempotent: clearing a Work that was never flagged is a no-op.

Examples:

On a later successful run

AtlasRb::Work.clear_incomplete(work_id)

Parameters:

  • id (String) —

    the Work ID.

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

    optional NUID of the acting user.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the updated Work, the same shape find returns, with incomplete false and incomplete_reason null.

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such resource, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



277
278
279
280
281
282
 
# File 'lib/atlas_rb/work.rb', line 277

def self.clear_incomplete(id, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .delete(ROUTE + id + '/incomplete')
  ))["work"]
end

.complete(id, nuid: nil, on_behalf_of: 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 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.

This call also mints the Work's persistent identifier. Atlas registers <prefix>/<noid> with its Handle service, pointed at the public Work page, and records it as handle on the Work. Two consequences for a caller:

  • Minting can never fail the call. A handle server that is down, slow or unconfigured leaves handle null and the Work still complete — never a non-2xx. So a 200 does not promise a handle: the response body carries the Work, so check handle on it rather than assuming success minted one.
  • Re-completing is safe. Atlas mints only when handle is empty, and the underlying registration is keyed by handle name, so a repeat call re-points rather than minting a second identifier.

A deployment with no handle server configured mints nothing at all, which is the normal state for a stack brought up without it.

Examples:

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

Parameters:

  • id (String) —

    the Work ID.

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

    optional NUID of the acting user.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Faraday::Response) —

    the raw response. Status 200 on success.

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").



198
199
200
 
# File 'lib/atlas_rb/work.rb', line 198

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

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

Proxy deposit — librarian uploads on behalf of a researcher

AtlasRb::Work.create("col-456", depositor: "000000123")

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. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

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

    optional NUID to stamp on the new Work's depositor field. When omitted, Atlas defaults the depositor to the acting user (nuid:); this kwarg is the proxy / batch escape hatch where the librarian who uploaded the Work is distinct from the person it should be attributed to. The acting user becomes the Work's proxy_uploader. The depositor is immutable post-create; there is no setter on the update surface.

Returns:

  • (Hash) —

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

Raises:



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/atlas_rb/work.rb', line 140

def self.create(id, xml_path = nil, idempotency_key: nil, nuid: nil,
                on_behalf_of: nil, depositor: nil)
  params = { collection_id: id }
  params[:depositor] = depositor if depositor
  result = AtlasRb::Mash.new(write_resource(
    connection(params, nuid,
               on_behalf_of: on_behalf_of, idempotency_key: idempotency_key).post(ROUTE)
  ))["work"]
  return result if xml_path.to_s.empty?

  # The MODS seed is a second call: create takes the parent and the
  # provenance slots, and the document goes through the write that owns it.
  AtlasRb::Resource.put_mods(result["id"], xml_path, nuid: nuid, on_behalf_of: on_behalf_of)
  find(result["id"], nuid: nuid, on_behalf_of: on_behalf_of)
end

.disassociate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil) ⇒ Hash

Retract one typed relationship between two Works.

Wraps DELETE /works/<id>/associations/<type>/<target_id> — the type is a path segment because it is part of the edge's identity, so retracting the figure claim leaves a transcription claim between the same two Works standing. Idempotent: retracting an edge that was never asserted is a no-op.

Examples:

AtlasRb::Work.disassociate("w-789", "w-123", type: "is_codebook_for")
# => {"outbound" => {}, "inbound" => {}}

Parameters:

  • work_id (String) —

    the asserting Work's ID.

  • target_id (String) —

    the associated Work to drop.

  • type (String) —

    the predicate to retract, one of ASSOCIATION_TYPES.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the Work's remaining associations, in the associations shape.

Raises:



803
804
805
806
807
808
 
# File 'lib/atlas_rb/work.rb', line 803

def self.disassociate(work_id, target_id, type:, nuid: nil, on_behalf_of: nil)
  write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .delete(ROUTE + work_id + '/associations/' + type.to_s + '/' + target_id)
  )
end

.file_sets(id, nuid: nil, on_behalf_of: nil) ⇒ Array<AtlasRb::Mash>?

List a Work's page FileSets in order, each with its assets.

Wraps GET /works/<id>/file_sets — the ordered, grouped sibling of assets (which flattens FileSet membership away). One entry per page-bearing FileSet, sorted position ascending with unordered (null-position) FileSets last; metadata and derivative-container FileSets are excluded as entries. Each entry nests its downloadable assets — the page's content Blobs plus any per-page IIIF Delegates — in the same polymorphic shape assets returns.

This is the read a IIIF Presentation manifest assembler needs: the response is unpaginated by design, so the whole page sequence arrives in one call.

Examples:

Assemble manifest canvases in page order

AtlasRb::Work.file_sets("w-789").each do |page|
  iiif = page.assets.find { |a| a["uri"] }
  add_canvas(order: page.position, image: iiif&.uri)
end

Parameters:

  • id (String) —

    the Work ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Array<AtlasRb::Mash>, nil) —

    one entry per page FileSet, in page order: { "noid", "type", "position", "tombstoned", "assets" => [...] }.

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



495
496
497
498
499
 
# File 'lib/atlas_rb/work.rb', line 495

def self.file_sets(id, nuid: nil, on_behalf_of: nil)
  read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/file_sets')) do |body|
    body.map { |entry| AtlasRb::Mash.new(entry) }
  end
end

.find(id, nuid: nil, on_behalf_of: 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. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header (acting-as / view-as). Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash, nil) —

    the "work" object, already unwrapped from the JSON response, or nil when the Work does not exist (404).

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (e.g. an auth/validation error envelope), carrying Atlas's status + body.



33
34
35
36
 
# File 'lib/atlas_rb/work.rb', line 33

def self.find(id, nuid: nil, on_behalf_of: nil)
  body = fetch_resource(ROUTE + id, nuid: nuid, on_behalf_of: on_behalf_of)
  body && AtlasRb::Mash.new(body)["work"]
end

.linked_members(id, nuid: nil, on_behalf_of: nil) ⇒ Array<String>?

List the Collections a Work is a linked member of.

Wraps GET /works/<id>/linked_members. Linked membership is the DAG overlay — a Work has exactly one structural parent (a_member_of, set by create / Resource.reparent) but may additionally appear in any number of other Collections as a linked member (a_linked_member_of). This returns just those linked Collection noids; the structural parent is not included.

Examples:

AtlasRb::Work.linked_members("w-789")
# => ["col-456", "col-457"]

Parameters:

  • id (String) —

    the Work ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Array<String>, nil) —

    linked Collection noids (possibly empty). The shape mirrors Collection.children — a bare array of ids, not an envelope.

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



595
596
597
 
# File 'lib/atlas_rb/work.rb', line 595

def self.linked_members(id, nuid: nil, on_behalf_of: nil)
  read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/linked_members'))
end

.list(in_progress: nil, incomplete: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash?

List Works, paginated.

Wraps GET /works. Returns the full pagination envelope — works plus pagination — rather than a bare array, so callers can page through results.

Examples:

Find stuck deposits

AtlasRb::Work.list(in_progress: true)

Find works whose pipeline gave up

AtlasRb::Work.list(incomplete: 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".

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

    when set, filter to Works whose incomplete flag matches — the staff list of Works whose enrichment pipeline gave up (see mark_incomplete). Independent of in_progress:, and the two combine: in_progress: false, incomplete: true reads as "finished, but degraded".

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

    1-indexed page number.

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

    page size override.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (AtlasRb::Mash, nil) —

    { "works" => [...], "pagination" => {...} }. Each entry in "works" is a flat Work summary (id, title, description, in_progress, incomplete, incomplete_reason, handle). handle is carried on the summary, not just the detail read, so "which Works never minted?" is answerable from one page rather than a fetch per row.

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



79
80
81
82
83
84
85
86
87
88
 
# File 'lib/atlas_rb/work.rb', line 79

def self.list(in_progress: nil, incomplete: nil, page: nil, per_page: nil, nuid: nil, on_behalf_of: nil)
  params = {}
  params[:in_progress] = in_progress unless in_progress.nil?
  params[:incomplete]  = incomplete  unless incomplete.nil?
  params[:page]        = page        if page
  params[:per_page]    = per_page    if per_page
  read_body(connection(params, nuid, on_behalf_of: on_behalf_of).get(ROUTE)) do |body|
    AtlasRb::Mash.new(body)
  end
end

.mark_incomplete(id, reason:, nuid: nil, on_behalf_of: nil) ⇒ Hash

Flag a Work whose enrichment pipeline gave up.

The counterpart to complete, for the other half of the lifecycle: complete says the deposit finished, this says something downstream of it did not. Call it from a work-scoped job's give-up handler — the PDF or media rendition, the derivatives, the full-text extraction — once that job has exhausted its retries. Atlas's GET /works?incomplete=true then lists the Work for staff, and incomplete_bsi on its Solr document lets a result row render a pill without a per-row fetch.

The flag never hides the Work. A record with its file, title and metadata but one missing derivative is degraded, not broken, and stays readable — enrichment does not fail a deposit.

Idempotent on the server; the last reason wins. Clear it with clear_incomplete when a later run of the same job succeeds, which makes the state self-healing.

Examples:

In a give-up handler

AtlasRb::Work.mark_incomplete(work_id, reason: "pdf_rendition_gave_up")

Parameters:

  • id (String) —

    the Work ID.

  • reason (String, nil) —

    a machine token naming the cause — one per give-up handler, e.g. "pdf_rendition_gave_up", "media_rendition_gave_up", "ingest_gave_up". Atlas stores it as an opaque string and does not validate it against a list, so the vocabulary is the caller's and a new token needs no Atlas release. Map it to display text at the point of use, with a fallback for a token the view has not been taught. A blank reason still sets the flag.

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

    optional NUID of the acting user.

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash) —

    the updated Work, the same shape find returns, carrying incomplete and incomplete_reason.

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such resource, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



244
245
246
247
248
249
 
# File 'lib/atlas_rb/work.rb', line 244

def self.mark_incomplete(id, reason:, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .post(ROUTE + id + '/incomplete', JSON.dump(reason: reason))
  ))["work"]
end

.mets(id, nuid: nil, on_behalf_of: nil) ⇒ Hash?

Fetch the Work-level METS structural metadata (page order).

Wraps GET /works/<id>/mets — the JSON projection of the Work's METS document, whose physical structMap is the preservation record of page order. The page sequence surfaces under "mets" => "pages" (one entry per page: noid / order / label). Atlas builds the document when the Work is completed (complete) and rebuilds it on page changes thereafter, so a Work that has never been completed has no METS yet — Atlas answers 404 and this binding returns nil (matching User.find_by_nuid's missing-resource convention).

For runtime page listing (e.g. manifest assembly) prefer file_sets, which needs no completion and carries each page's assets; this read is the preservation-record view.

Examples:

AtlasRb::Work.mets("w-789").mets.pages.map(&:order)
# => [1, 2, 3]

Parameters:

  • id (String) —

    the Work ID.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Hash, nil) —

    the "work" object, already unwrapped: { "id", "mets" => { "created_at_iso", "agent", "files", "structure_label", "pages" => [...] } } — or nil when the Work has no METS yet (never completed) or does not exist.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



534
535
536
537
538
 
# File 'lib/atlas_rb/work.rb', line 534

def self.mets(id, nuid: nil, on_behalf_of: nil)
  read_body(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + '/mets')) do |body|
    AtlasRb::Mash.new(body)["work"]
  end
end

.mods(id, kind = nil, nuid: nil, on_behalf_of: 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. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (String, nil) —

    the raw response body in the requested format.

    nil when Atlas answers 404 — nothing is there to read, or, with a misconfigured ATLAS_URL, the route is not Atlas's at all.

Raises:

  • (AtlasRb::ResourceError) —

    on any non-2xx other than 404 / 410 (an auth or validation envelope, a 5xx, a proxy's 503), carrying Atlas's status and body so the failure is attributable at the boundary.



560
561
562
563
564
565
 
# File 'lib/atlas_rb/work.rb', line 560

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

.remove_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil) ⇒ Array<String>

Remove a linked membership: drop a Work from an additional Collection.

Wraps DELETE /works/<id>/linked_members/<collection_id> — the Collection is passed as a path segment, not a body. This removes the Collection from the Work's a_linked_member_of; the structural parent (a_member_of) is untouched. Atlas enforces the same two-sided authorization as add_linked_member. Removing a link that does not exist is a server-side concern; this binding simply forwards the call.

Examples:

AtlasRb::Work.remove_linked_member("w-789", "col-456")
# => []

Parameters:

  • work_id (String) —

    the Work ID.

  • collection_id (String) —

    the linked Collection to remove.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (Array<String>) —

    the Work's remaining linked Collection noids after the removal (possibly empty).

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").

  • (AtlasRb::LinkedMemberError) —

    if Atlas rejects the removal on structural grounds (HTTP 422). The envelope's error code is exposed as #code.

  • (AtlasRb::ForbiddenError) —

    if Atlas refuses the removal on authorization grounds (HTTP 403).

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such resource, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



677
678
679
680
681
682
 
# File 'lib/atlas_rb/work.rb', line 677

def self.remove_linked_member(work_id, collection_id, nuid: nil, on_behalf_of: nil)
  write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .delete(ROUTE + work_id + '/linked_members/' + collection_id)
  )
end

.set_derivative_permissions(id, policy:, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Replace a Work's per-asset derivative-visibility policy.

Sets which read groups may fetch each of the Work's downloadable renditions, reusing the resource read-group vocabulary ("public", Grouper group names, [] = private). Two media families:

  • the image ladder small / medium / large / service (deep-zoom) / master (the original image), and
  • independent media audio / video / pdf.

Unlike set_image_derivatives (which upserts URIs) this is a whole-object REPLACE: the map you pass is the complete policy. Within the image ladder omitted tiers inherit by cascade (an absent tier inherits the next lower-resolution tier; small inherits the Work's own visibility). Independent media do NOT cascade — an absent audio/video/pdf key rides the Work. Pass a tier as [] to make it private.

Atlas enforces: a tier may not be more visible than the Work, and — within the image ladder — visibility must narrow as resolution grows (master ⊆ service ⊆ large ⊆ medium ⊆ small; independent media impose no ordering). The gate is advisory — it surfaces on assets as gated / permission for BOTH Delegate (image tier) and Blob (master / pdf / audio / video, classified by media type) entries, for the display layer (Cerberus / the IIIF auth service; Cerberus's download :read check) to enforce.

Examples:

AtlasRb::Work.set_derivative_permissions(
  "w-789",
  policy: { small:   ["public"],
            large:   ["northeastern:drs:repository:archives"],
            service: ["northeastern:drs:repository:archives"] }
)

Parameters:

  • id (String) —

    the Work ID.

  • policy (Hash) —

    tier => Array(read groups), e.g. { large: ["northeastern:drs:repository:archives"], master: [...] }. Keys may be strings or symbols; recognized keys are small / medium / large / service / master / audio / video / pdf.

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional On-Behalf-Of NUID.

Returns:

  • (AtlasRb::Mash) —

    the updated Work; the stored map echoes back under derivative_permissions.

Raises:



377
378
379
380
381
382
 
# File 'lib/atlas_rb/work.rb', line 377

def self.set_derivative_permissions(id, policy:, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .patch(ROUTE + id + '/derivative_permissions', JSON.dump(policy))
  ))
end

.set_full_text(id, text:, nuid: nil, on_behalf_of: nil) ⇒ AtlasRb::Mash

Store a Work's derived full-document text for search indexing.

Purpose-specific PATCH in the same "machine-set derived metadata" family as Resource.set_thumbnails / set_image_derivatives. Hand Atlas the Work-level aggregate of the extracted body text (the concatenation of the Work's content FileSets' text); Atlas stores it as the Work's derived full_text and its FullTextIndexer projects it onto the Work's Solr doc (all_text_timv) for body-text search + the "Full Text Match" snippet.

Distinct from metadata — this is a machine-extracted search aid (pdftotext / Tika in a Cerberus job), not user-authored descriptive content, and is re-sent on any re-ingest. Empty/blank text clears it.

Examples:

AtlasRb::Work.set_full_text("w-789", text: extracted_pdf_text)

Parameters:

  • id (String) —

    the Work ID.

  • text (String) —

    the extracted plain text (Work-level aggregate).

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

    optional acting user's NUID. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

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

    optional NUID for the On-Behalf-Of header. Falls through to AtlasRb.config.default_on_behalf_of when omitted.

Returns:

  • (AtlasRb::Mash) —

    the parsed JSON response (the Work; the stored text is not echoed back — it's read only through Solr).

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such resource, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



417
418
419
420
421
422
 
# File 'lib/atlas_rb/work.rb', line 417

def self.set_full_text(id, text:, nuid: nil, on_behalf_of: nil)
  AtlasRb::Mash.new(write_resource(
    connection({}, nuid, on_behalf_of: on_behalf_of)
      .patch(ROUTE + id + '/full_text', JSON.dump(text: text))
  ))
end

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

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

Sibling of Resource.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. On the relay-signing path it is signed into the assertion sub; on the BYO-JWT (ATLAS_JWT) path it is ignored (identity lives in the token).

Returns:

Raises:

  • (AtlasRb::StaleResourceError) —

    if Atlas reports an optimistic-lock conflict that exhausted its internal retry budget (HTTP 409 with error: "stale_resource").

  • (AtlasRb::NotFoundError) —

    if Atlas answers 404 — the id names no such resource, so the write did not happen.

  • (AtlasRb::ResourceError) —

    on any other non-2xx, carrying Atlas's status and body.



316
317
318
319
320
321
322
 
# File 'lib/atlas_rb/work.rb', line 316

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