collectionspace-client 0.3.0 → 0.15.0

data/examples/update_password.rb

@@ -1,33 +1,3 @@
 # frozen_string_literal: true
 
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'awesome_print'
-require 'base64'
-require 'collectionspace/client'
-
-CS_CFG_URL  = ENV.fetch('CS_CFG_URL', 'https://core.dev.collectionspace.org/cspace-services')
-CS_CFG_USER = ENV.fetch('CS_CFG_USER', 'admin@core.collectionspace.org')
-CS_CFG_PASS = ENV.fetch('CS_CFG_PASS', 'Administrator')
-CS_UPD_USER = ENV.fetch('CS_UPD_USER', 'admin@core.collectionspace.org')
-CS_UPD_PASS = Base64.encode64(ENV.fetch('CS_UPD_PASS', 'Administrator')).chomp
-
-client = CollectionSpace::Client.new(
-  CollectionSpace::Configuration.new(
-    base_uri: CS_CFG_URL,
-    username: CS_CFG_USER,
-    password: CS_CFG_PASS
-  )
-)
-
-PAYLOAD = <<~XML
-  <ns2:accounts_common xmlns:ns2="http://collectionspace.org/services/account">
-      <userId>#{CS_UPD_USER}</userId>
-      <password>#{CS_UPD_PASS}</password>
-  </ns2:accounts_common>
-XML
-
-client.all('accounts').each do |item|
-  next unless item['email'] == CS_UPD_USER
-
-  ap client.put(item['uri'], PAYLOAD).parsed
-end
+puts "Update password has been moved to Rake task: `cli:update_password[args...]`"

data/lib/collectionspace/client/batch.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CollectionSpace
+  # CollectionSpace batch
+  class Batch
+    def self.all
+      [
+        {
+          name: "Update Current Location",
+          notes: "Recompute the current location of Object records, based on the " \
+            "related Location/Movement/Inventory records. Runs on a single record " \
+            "or all records.",
+          doctype: %w[CollectionObject],
+          supports_single_doc: "true",
+          supports_doc_list: "false",
+          supports_group: "false",
+          supports_no_context: "true",
+          creates_new_focus: "false",
+          classname:
+          "org.collectionspace.services.batch.nuxeo.UpdateObjectLocationBatchJob"
+        },
+        {
+          name: "Update Inventory Status",
+          notes: "Set the inventory status of selected Object records. Runs on a " \
+            "record list only.",
+          doctype: %w[CollectionObject],
+          supports_single_doc: "false",
+          supports_doc_list: "true",
+          supports_group: "false",
+          supports_no_context: "false",
+          creates_new_focus: "false",
+          classname:
+          "org.collectionspace.services.batch.nuxeo.UpdateInventoryStatusBatchJob"
+        },
+        {
+          name: "Merge Authority Items",
+          notes: "Merge an authority item into a target, and update all " \
+            "referencing records. Runs on a single record only.",
+          doctype: %w[],
+          supports_single_doc: "true",
+          supports_doc_list: "false",
+          supports_group: "false",
+          supports_no_context: "false",
+          creates_new_focus: "false",
+          classname:
+          "org.collectionspace.services.batch.nuxeo.MergeAuthorityItemsBatchJob"
+        }
+      ]
+    end
+
+    def self.find(key, value)
+      all.find { |batch| batch[key] == value }
+    end
+  end
+end

data/lib/collectionspace/client/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module CollectionSpace
   # CollectionSpace client
   class Client
@@ -6,28 +8,39 @@ module CollectionSpace
 
     def initialize(config = Configuration.new)
       unless config.is_a? CollectionSpace::Configuration
-        raise CollectionSpace::ArgumentError, 'Invalid configuration object'
+        raise CollectionSpace::ArgumentError, "Invalid configuration object"
       end
 
       @config = config
     end
 
     def get(path, options = {})
-      request 'GET', path, options
+      request "GET", path, options
     end
 
     def post(path, payload, options = {})
       check_payload(payload)
-      request 'POST', path, { body: payload }.merge(options)
+      request "POST", path, {body: payload}.merge(options)
+    end
+
+    def post_file(file, options = {})
+      file = File.expand_path(file)
+      raise ArgumentError, "cannot find file #{file}" unless File.exist? file
+
+      request "POST", "blobs", {
+        body: {
+          file: File.open(file)
+        }
+      }.merge(options)
     end
 
-    def put(path, payload)
+    def put(path, payload, options = {})
       check_payload(payload)
-      request 'PUT', path, body: payload
+      request "PUT", path, {body: payload}.merge(options)
     end
 
     def delete(path)
-      request 'DELETE', path
+      request "DELETE", path
     end
 
     private

data/lib/collectionspace/client/configuration.rb

@@ -1,25 +1,27 @@
+# frozen_string_literal: true
+
 module CollectionSpace
   # CollectionSpace configuration
   class Configuration
-    def defaults
-      {
-        base_uri: nil,
-        username: nil,
-        password: nil,
-        page_size: 25,
-        include_deleted: false,
-        throttle: 0,
-        verify_ssl: true
-      }
-    end
+    DEFAULTS = {
+      base_uri: nil,
+      username: nil,
+      password: nil,
+      page_size: 25,
+      include_deleted: false,
+      throttle: 0,
+      verbose: false,
+      verify_ssl: true
+    }.freeze
+
+    attr_accessor :base_uri, :username, :password, :page_size, :include_deleted, :throttle, :verbose, :verify_ssl
 
     def initialize(settings = {})
-      settings = defaults.merge(settings)
+      settings = DEFAULTS.merge(settings)
       settings.each do |property, value|
-        next unless defaults.key? property
+        next unless DEFAULTS.key?(property)
 
         instance_variable_set("@#{property}", value)
-        self.class.send(:attr_accessor, property)
       end
     end
   end

data/lib/collectionspace/client/helpers.rb

@@ -1,6 +1,40 @@
+# frozen_string_literal: true
+
 module CollectionSpace
   # Helper methods for client requests
   module Helpers
+    # add / update batch job
+    def add_batch_job(name, template, data = {}, params = {pgSz: 100})
+      payload = Template.process(template, data)
+      response = get("batch", {query: params})
+      create_or_update(response, "batch", "name", name, payload)
+    end
+
+    # add / update batches and data updates
+    def add_batch(data = {}, params = {pgSz: 100})
+      payload = Template.process("batch", data)
+      response = get("batch", {query: params})
+      create_or_update(response, "batch", "name", data[:name], payload)
+    end
+
+    # add / update reports
+    def add_report(data = {}, params = {pgSz: 100})
+      payload = Template.process("report", data)
+      response = get("reports", {query: params})
+      create_or_update(response, "reports", "name", data[:name], payload)
+    end
+
+    # returns Array of authority doctypes for use in setting up batches
+    def authority_doctypes
+      response = get("/servicegroups/authority")
+      unless response.result.success?
+        raise CollectionSpace::RequestError, response.result.body
+      end
+
+      result = response.result.parsed_response
+      result.dig("document", "servicegroups_common", "hasDocTypes", "hasDocType")
+    end
+
     # get ALL records at path by paging through record set
     def all(path, options = {})
       list_type, list_item = get_list_types(path)
@@ -8,12 +42,10 @@ module CollectionSpace
       return [] unless iterations.positive?
 
       Enumerator::Lazy.new(0...iterations) do |yielder, i|
-        response = request('GET', path, options.merge(query: { pgNum: i }))
-        unless response.result.success?
-          raise CollectionSpace::RequestError, response.result.body
-        end
+        response = request("GET", path, options.merge(query: {pgNum: i}))
+        raise CollectionSpace::RequestError, response.result.body unless response.result.success?
 
-        items_in_page = response.parsed[list_type].fetch('itemsInPage', 0).to_i
+        items_in_page = response.parsed[list_type].fetch("itemsInPage", 0).to_i
         list_items = items_in_page.positive? ? response.parsed[list_type][list_item] : []
         list_items = [list_items] if items_in_page == 1
 
@@ -23,25 +55,175 @@ module CollectionSpace
 
     def count(path)
       list_type, = get_list_types(path)
-      response   = request('GET', path, query: { pgNum: 0, pgSz: 1 })
-      response.parsed[list_type]['totalItems'].to_i if response.result.success?
+      response = request("GET", path, query: {pgNum: 0, pgSz: 1})
+      raise CollectionSpace::RequestError, response.result.body unless response.result.success?
+
+      response.parsed[list_type]["totalItems"].to_i
+    end
+
+    # get the tenant domain from a system required top level authority (person)
+    def domain
+      path = "personauthorities"
+      response = request("GET", path, query: {pgNum: 0, pgSz: 1})
+      raise CollectionSpace::RequestError, response.result.body unless response.result.success?
+
+      refname = response.parsed.dig(*get_list_types(path), "refName")
+      CollectionSpace::RefName.parse(refname)[:domain]
+    end
+
+    # find procedure or object by type and id
+    # find authority/vocab term by type, subtype, and refname
+    def find(type:, value:, subtype: nil, field: nil, schema: "common", sort: nil, operator: "=")
+      service = CollectionSpace::Service.get(type: type, subtype: subtype)
+      field ||= service[:term] # this will be set if it is an authority or vocabulary, otherwise nil
+      field ||= service[:identifier]
+      search_args = CollectionSpace::Search.new.from_hash(
+        path: service[:path],
+        namespace: "#{service[:ns_prefix]}_#{schema}",
+        field: field,
+        expression: "#{operator} '#{value.gsub(/'/, "\\\\'")}'"
+      )
+      search(search_args, sortBy: CollectionSpace::Search::DEFAULT_SORT)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # @param subject_csid [String] to be searched as `sbj` value
+    # @param object_csid [String] to be searched as `obj` value
+    # @param rel_type [String<'affects', 'hasBroader'>, nil] to be searched as `prd` value
+    def find_relation(subject_csid:, object_csid:, rel_type: nil)
+      if rel_type
+        get("relations", query: {"sbj" => subject_csid, "obj" => object_csid, "prd" => rel_type})
+      else
+        warn(
+          "No rel_type specified, so multiple types of relations between #{subject_csid} and #{object_csid} may be returned",
+          uplevel: 1
+        )
+        get("relations", query: {"sbj" => subject_csid, "obj" => object_csid})
+      end
     end
 
     def get_list_types(path)
       {
-        'accounts' => %w[accounts_common_list account_list_item],
-        'relations' => %w[relations_common_list relation_list_item],
+        "accounts" => %w[accounts_common_list account_list_item],
+        "relations" => %w[relations_common_list relation_list_item]
       }.fetch(path, %w[abstract_common_list list_item])
     end
 
-    def prepare_query(query, options = {})
-      query_string = "#{query.type}:#{query.field} #{query.expression}"
-      options.merge(query: { as: query_string })
+    def reindex_full_text(doctype, csids = [])
+      if csids.any?
+        run_job(
+          "Reindex Full Text", :reindex_full_text, :reindex_by_csids, {doctype: doctype, csids: csids}
+        )
+      else
+        run_job(
+          "Reindex Full Text", :reindex_full_text, :reindex_by_doctype, {doctype: doctype}
+        )
+      end
+    end
+
+    # @param id [String] media record's identificationNumber value
+    # @param url [String] blobUri value
+    # @param verbose [Boolean] whether to put brief report of outcome to STDOUT
+    # @param ensure_safe_url [Boolean] set to false if using FILE URIs or
+    #   other non-HTTPS URIs
+    # @param delete_existing_blob [Boolean] set to false if you have already
+    #   manually deleted blobs
+    def reset_media_blob(id:, url:, verbose: false,
+      ensure_safe_url: true,
+      delete_existing_blob: true)
+      if ensure_safe_url
+        unless URI.parse(url).instance_of? URI::HTTPS
+          raise CollectionSpace::ArgumentError, "Not a valid url #{url}"
+        end
+      end
+
+      response = find(type: "media", value: id, field: "identificationNumber")
+      unless response.result.success?
+        if verbose
+          puts "#{id}\tfailure\tAPI request error: #{response.result.body}"
+        else
+          raise CollectionSpace::RequestError, response.result.body
+        end
+      end
+
+      found = response.parsed
+      total = found["abstract_common_list"]["totalItems"].to_i
+
+      if total.zero?
+        msg = "Media #{id} not found"
+        if verbose
+          puts "#{id}\tfailure\t#{msg}"
+        else
+          raise CollectionSpace::NotFoundError, msg
+        end
+      elsif total > 1
+        msg = "Found multiple media records for #{id}"
+        if verbose
+          puts "#{id}\tfailure\t#{msg}"
+        else
+          raise CollectionSpace::DuplicateIdFound, msg
+        end
+      end
+
+      media_uri = found["abstract_common_list"]["list_item"]["uri"]
+
+      if delete_existing_blob
+        blob_csid = found["abstract_common_list"]["list_item"]["blobCsid"]
+        delete("/blobs/#{blob_csid}") if blob_csid
+      end
+
+      payload = Template.process(:reset_media_blob, {id: id})
+      response = put(media_uri, payload, query: {"blobUri" => url})
+      if verbose
+        if response.result.success?
+          puts "#{id}\tsuccess\t"
+        else
+          puts "#{id}\tfailure\t#{response.parsed}"
+        end
+      else
+        response
+      end
+    end
+
+    def run_job(name, template, invoke_template, data = {})
+      payload = Template.process(invoke_template, data)
+      job = add_batch_job(name, template)
+      path = job.parsed["document"]["collectionspace_core"]["uri"]
+      post(path, payload)
+    end
+
+    def search(query, params = {})
+      options = prepare_query(query, params)
+      request "GET", query.path, options
+    end
+
+    def keyword_search(type:, value:, subtype: nil, sort: nil)
+      service = CollectionSpace::Service.get(type: type, subtype: subtype)
+      options = prepare_keyword_query(value, {sortBy: CollectionSpace::Search::DEFAULT_SORT})
+      request "GET", service[:path], options
+    end
+
+    def service(type:, subtype: "")
+      CollectionSpace::Service.get(type: type, subtype: subtype)
+    end
+
+    private
+
+    def create_or_update(response, path, property, value, payload)
+      list_type, item_type = get_list_types(path)
+      item = response.find(list_type, item_type, property, value)
+      path = item ? "#{path}/#{item["csid"]}" : path
+      item ? put(path, payload) : post(path, payload)
+    end
+
+    def prepare_query(query, params = {})
+      query_string = "#{query.namespace}:#{query.field} #{query.expression}"
+      {query: {as: query_string}.merge(params)}
     end
 
-    def search(query, options = {})
-      options = prepare_query(query, options)
-      request 'GET', query.path, options
+    def prepare_keyword_query(query, sort = {})
+      query_string = query.downcase.tr(" ", "+")
+      {query: {kw: query_string}.merge(sort)}
     end
   end
 end

data/lib/collectionspace/client/refname.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module CollectionSpace
+  # CollectionSpace RefName
+  #
+  # There are four patterns we need to handle:
+  #
+  # - urn:cspace:domain:type:name(subtype)'label'                       : Top level authority/vocabulary
+  # - urn:cspace:domain:type:name(subtype):item:name(identifier)'label' : Authority/vocabulary term
+  # - urn:cspace:domain:type:id(identifier)'label'                      : Collectionobject
+  # - urn:cspace:domain:type:id(identifier)                             : Procedures, relations, blobs
+  class RefName
+    attr_reader :domain, :type, :subtype, :identifier, :label
+
+    def initialize(refname)
+      @refname = refname
+      @domain = nil
+      @type = nil
+      @subtype = nil
+      @identifier = nil
+      @label = nil
+      parse
+    end
+
+    def parse
+      scanner = StringScanner.new(@refname)
+      scanner.skip("urn:cspace:")
+      @domain = to_next_colon(scanner)
+      @type = to_next_colon(scanner)
+
+      case next_segment(scanner)
+      when "name"
+        set_subtype(scanner)
+      when "id"
+        set_identifier(scanner)
+      end
+
+      self
+    end
+
+    # Convenience class method, so new instance of RefName does not have to be instantiated in order to parse
+    #
+    # As of v0.13.1, return_class is added and defaults to nil for backward compatibility
+    # Eventually this default will be deprecated, and a parsed RefName object will be returned as the default.
+    #   Any new code written using this method should set the return_class parameter to :refname_obj
+    def self.parse(refname, return_class = nil)
+      (return_class == :refname_obj) ? new(refname) : new(refname).to_h
+    end
+
+    # Returns a parsed RefName object as a hash.
+    # As of v0.13.1, this is equivalent to calling RefName.parse('refnamevalue', :hash)
+    # This was added to simplify the process of updating existing code that expects a hash when calling RefName.parse
+    def to_h
+      {
+        domain: domain,
+        type: type,
+        subtype: subtype,
+        identifier: identifier,
+        label: label
+      }
+    end
+
+    private
+
+    def next_segment(scanner)
+      segment = scanner.check_until(/\(/)
+      return nil unless segment
+
+      segment.delete_suffix("(")
+    end
+
+    def set_identifier(scanner)
+      scanner.skip("id(")
+      @identifier = to_end_paren(scanner)
+      return if scanner.eos?
+
+      set_label(scanner)
+    end
+
+    def set_label(scanner)
+      scanner.skip("'")
+      @label = scanner.rest.delete_suffix("'")
+    end
+
+    def set_subtype(scanner)
+      scanner.skip("name(")
+      @subtype = to_end_paren(scanner)
+
+      case next_segment(scanner)
+      when nil
+        set_label(scanner)
+      when ":item:name"
+        set_term_identifier(scanner)
+      end
+    end
+
+    def set_term_identifier(scanner)
+      scanner.skip(":item:name(")
+      @identifier = to_end_paren(scanner)
+      scanner.skip("'")
+      set_label(scanner)
+    end
+
+    def to_end_paren(scanner)
+      scanner.scan_until(/\)/).delete_suffix(")")
+    end
+
+    def to_next_colon(scanner)
+      scanner.scan_until(/:/).delete_suffix(":")
+    end
+  end
+end