FOLIO Inventory Batch Upsert Hrid API

openapi: 3.2.0
info:
  title: Folio Inventory Batch Upsert Hrid API
  version: v5.0
  description: 'Operations tagged Inventory Batch Upsert Hrid across 2 of this provider''s published API definitions: folio-mod-inventory-update-inventory-update-5-0-openapi.json, folio-mod-inventory-update-inventory-update-5-0-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Inventory Batch Upsert Hrid
paths:
  /inventory-batch-upsert-hrid:
    description: Create or update a batch of instances with holdings and items, based on incoming HRIDs on all three record types.
    parameters:
    - $ref: '#/components/parameters/okapi_tenant'
    - $ref: '#/components/parameters/okapi_token'
    - $ref: '#/components/parameters/okapi_url'
    put:
      operationId: batchUpsertByHrid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/inventory-record-sets-with-hrids'
      responses:
        '200':
          description: Batch of Inventory record sets successfully created or updated by HRIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metrics'
        '207':
          description: Partially successful update of record set. Errors enumerated in response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch-upsert-response-207'
        '400':
          description: 'Bad request, for example: empty request body, non-JSON or invalid JSON in request body or JSON does not contain inventory record sets'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '422':
          description: One or more validation errors found in the incoming batch of record sets. No updates performed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '500':
          description: Internal error in the module or in storage during batch upsert by HRID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Inventory Batch Upsert Hrid
      summary: Batch upsert by hrid
      x-summary-source: derived
components:
  schemas:
    record-retention:
      type: object
      description: Prevent deletion of existing record, using pattern matching in select field.
      properties:
        ifField:
          type: string
          description: Name of the field to match.
        matchesPattern:
          type: string
          description: Regex pattern to match the field by.
      additionalProperties: false
      required:
      - ifField
      - matchesPattern
    inventory-record-sets-with-hrids:
      type: object
      description: A collection of inventory records sets (instances, holdings and items, etc)
      properties:
        inventoryRecordSets:
          type: array
          description: List of inventory record sets.
          items:
            $ref: '#/components/schemas/inventory-record-set-with-hrids'
      required:
      - inventoryRecordSets
    error-response:
      type: object
      description: Response on a unsuccessful upsert request for a single record.
      properties:
        category:
          type: string
          description: Type of problem, typically error category STORAGE.
        statusCode:
          type: string
          description: The HTTP status code assigned to the error.
        message:
          anyOf:
          - type: string
          - type: object
          description: Error message returned by Inventory storage.
        shortMessage:
          type: string
          description: A short error message that might be used by the client to count similar error occurrences.
        entityType:
          type: string
          description: The record type for which a problem occurred.
        transaction:
          type: string
          description: Type of REST operation for which the problem occurred.
        entity:
          type: object
          description: The JSON object that was pushed to Inventory storage when the problem occurred.
        details:
          type: object
          description: Any further details, i.e. additional context for the problem.
    item-with-hrid:
      type: object
      description: An item record in compliance with the schema of the given version of the underlying `item-storage` API.
      properties:
        hrid:
          type: string
          description: The external identifier of the item; the client's own unique ID for the updating record.
      additionalProperties: true
    metrics:
      type: object
      description: Report on the number of operations performed, by record type, transaction type, and outcome.
      properties:
        INSTANCE:
          type: object
          description: Reports the number of operations performed on instance records by transaction type and outcome.
          properties:
            CREATED:
              $ref: '#/components/schemas/outcomes'
            UPDATED:
              $ref: '#/components/schemas/outcomes'
            DELETED:
              $ref: '#/components/schemas/outcomes'
        HOLDINGS_RECORD:
          type: object
          description: Reports the number of operations performed on holdings records by transaction type and outcome.
          properties:
            CREATED:
              $ref: '#/components/schemas/outcomes'
            UPDATED:
              $ref: '#/components/schemas/outcomes'
            DELETED:
              $ref: '#/components/schemas/outcomes'
        ITEM:
          type: object
          description: Reports the number of operations performed on item records by transaction type and outcome.
          properties:
            CREATED:
              $ref: '#/components/schemas/outcomes'
            UPDATED:
              $ref: '#/components/schemas/outcomes'
            DELETED:
              $ref: '#/components/schemas/outcomes'
        INSTANCE_RELATION_SHIP:
          type: object
          description: Reports the number of operations performed for the instance's parent-child relationships.
          properties:
            CREATED:
              $ref: '#/components/schemas/outcomes'
            DELETED:
              $ref: '#/components/schemas/outcomes'
            PROVISIONAL_INSTANCE:
              $ref: '#/components/schemas/outcomes'
        INSTANCE_TITLE_SUCCESSION:
          type: object
          description: Reports the number of operations performed for the instance's preceding-succeeding relationships.
          properties:
            CREATED:
              $ref: '#/components/schemas/outcomes'
            DELETED:
              $ref: '#/components/schemas/outcomes'
            PROVISIONAL_INSTANCE:
              $ref: '#/components/schemas/outcomes'
    outcomes:
      type: object
      description: Reports the number of different outcomes of operations of a given type per entity type.
      properties:
        COMPLETED:
          type: integer
          description: Number of successfully completed operations of a given type per entity type.
        FAILED:
          type: integer
          description: Number of failed operations of a given type per entity type.
        SKIPPED:
          type: integer
          description: Number of skipped operations of a given type per entity type.
        PENDING:
          type: integer
          description: Number operations of a given type that were unresolved per entity type
    processing-upsert:
      type: object
      description: An object holding supporting pieces of data and/or processing instructions for Inventory update processing.
      properties:
        item:
          type: object
          description: Instructions for processing Inventory Items.
          properties:
            retainOmittedRecord:
              $ref: '#/components/schemas/record-retention'
            retainExistingValues:
              $ref: '#/components/schemas/properties-retention'
            status:
              type: object
            statisticalCoding:
              $ref: '#/components/schemas/statistical-coding'
        holdingsRecord:
          type: object
          description: Instructions for processing Inventory holdings records.
          properties:
            retainExistingValues:
              $ref: '#/components/schemas/properties-retention'
            statisticalCoding:
              $ref: '#/components/schemas/statistical-coding'
        instance:
          type: object
          description: Instructions for processing instance records.
          properties:
            retainExistingValues:
              $ref: '#/components/schemas/properties-retention'
            statisticalCoding:
              $ref: '#/components/schemas/statistical-coding'
    instance-with-hrid:
      type: object
      description: An instance record in compliance with the schema of the given version of the underlying `instance-storage` API.
      properties:
        hrid:
          type: string
          description: The external identifier of the instance; the client's own unique ID for the updating record.
      additionalProperties: true
    inventory-record-set-with-hrids:
      type: object
      description: An instance record and an array of holdings records with embedded items.
      properties:
        instance:
          $ref: '#/components/schemas/instance-with-hrid'
        holdingsRecords:
          type: array
          description: Collection of holdings of the instance, each holdings record with embedded items.
          items:
            $ref: '#/components/schemas/holdings-record-with-hrid'
        instanceRelations:
          description: Different types of instance-to-instance relationships to create or update.
          properties:
            parentInstances:
              type: array
              description: Collection of objects with information required for finding and linking to parent instances
              items:
                type: object
                properties:
                  instanceIdentifier:
                    description: Object with information required for finding the parent instance to link to.
                    properties:
                      hrid:
                        type: string
                        description: A unique ID for the parent instance to link to.
                  provisionalInstance:
                    type: object
                    description: Object with at least the mandatory instance properties required for creating a provisional instance if the parent does not yet exist. Other valid instance properties allowed.
                    properties:
                      title:
                        type: string
                        description: The parent record’s title.
                      source:
                        type: string
                        description: The parent record’s source.
                      instanceTypeId:
                        type: string
                        description: The parent record’s resource type ID (UUID).
                    additionalProperties: true
                  instanceRelationShipTypeId:
                    type: string
                    description: UUID for the type of relationship to establish to a parent instance (article, volume, multipart, series).
            childInstances:
              type: array
              description: Collection of objects with information required for finding and linking to child instances
              items:
                type: object
                properties:
                  instanceIdentifier:
                    type: object
                    description: Object with information required for finding the child instance to link to.
                    properties:
                      hrid:
                        type: string
                        description: A unique ID for the child instance to link to.
                  provisionalInstance:
                    type: object
                    description: Object with at least the mandatory instance properties required for creating a provisional instance if the child does not yet exist. Other valid instance properties allowed.
                    properties:
                      title:
                        type: string
                        description: The child record’s title.
                      source:
                        type: string
                        description: The child record’s source.
                      instanceTypeId:
                        type: string
                        description: The child record’s resource type ID (UUID).
                    additionalProperties: true
                  instanceRelationShipTypeId:
                    type: string
                    description: UUID for the type of relationship to establish to a child instance (article, volume, multipart, series).
                required:
                - instanceIdentifier
            precedingTitles:
              type: array
              description: Collection of objects with information required for finding and linking to preceding instances
              items:
                type: object
                properties:
                  instanceIdentifier:
                    type: object
                    description: Object with information required for finding the preceding instance to link to.
                    properties:
                      hrid:
                        type: string
                        description: A unique ID for the preceding instance to link to.
                  provisionalInstance:
                    type: object
                    description: Object with at least the mandatory instance properties required for creating a provisional instance if the preceding title does not yet exist. Other valid instance properties allowed.
                    properties:
                      title:
                        type: string
                        description: The preceding record’s title.
                      source:
                        type: string
                        description: The preceding record’s source.
                      instanceTypeId:
                        type: string
                        description: The preceding record’s resource type ID (UUID).
                    additionalProperties: true
                required:
                - instanceIdentifier
            succeedingTitles:
              type: array
              description: Collection of objects with information required for finding and linking to succeeding instances
              items:
                type: object
                properties:
                  instanceIdentifier:
                    type: object
                    description: Object with information required for finding the succeeding instance to link to.
                    properties:
                      hrid:
                        type: string
                        description: A unique ID for the succeeding instance to link to.
                  provisionalInstance:
                    type: object
                    description: Object with at least the mandatory instance properties required for creating a provisional instance if the succeeding title does not yet exist. Other valid instance properties allowed.
                    properties:
                      title:
                        type: string
                        description: The succeeding record’s title.
                      source:
                        type: string
                        description: The succeeding record’s source.
                      instanceTypeId:
                        type: string
                        description: The succeeding record’s resource type ID (UUID).
                    additionalProperties: true
                required:
                - instanceIdentifier
        processing:
          $ref: '#/components/schemas/processing-upsert'
      required:
      - instance
    properties-retention:
      type: object
      description: Defines retention policies for existing values when updating records.
      properties:
        forOmittedProperties:
          description: If set to true/"true" MIU retains existing properties if they are absent from the incoming record. If set to false (default), MIU removes absent properties from the existing record too.
        forTheseProperties:
          type: array
          description: List of properties to retain existing values for, whether they are present or not in the incoming record.
          items:
            type: string
    batch-upsert-response-207:
      type: object
      description: Response on partly successful batch upsert request.
      properties:
        metrics:
          $ref: '#/components/schemas/metrics'
        errors:
          type: array
          description: List of problems encountered during an inventory update or delete request.
          items:
            $ref: '#/components/schemas/error-response'
    statistical-coding:
      type: array
      description: Configures the statistical code(s) to set for the given events.
      items:
        type: object
        properties:
          if:
            type: string
            description: The event triggering a statistical coding; currently only one supported event.
            enum:
            - deleteSkipped
          becauseOf:
            type: string
            description: The cause of the event.
            enum:
            - ITEM_STATUS
            - ITEM_PATTERN_MATCH
            - HOLDINGS_RECORD_PATTERN_MATCH
            - PO_LINE_REFERENCE
          setCode:
            type: string
            description: The UUID of the statistical code to set on the inventory record.
    holdings-record-with-hrid:
      type: object
      description: A holdings record in compliance with the schema of the given version of the underlying `holdings-storage` API, optionally with embedded items.
      properties:
        hrid:
          type: string
          description: The external identifier of the holdings record; the client's own unique ID for the updating record.
        items:
          type: array
          description: Inventory items recorded by this holdings record.
          items:
            $ref: '#/components/schemas/item-with-hrid'
  parameters:
    okapi_tenant:
      in: header
      name: X-Okapi-Tenant
      description: Okapi Tenant
      required: false
      schema:
        type: string
    okapi_url:
      in: header
      name: X-Okapi-Url
      description: Okapi URL
      required: false
      schema:
        type: string
    okapi_token:
      in: header
      name: X-Okapi-Token
      description: Okapi Token
      required: false
      schema:
        type: string
x-refined-from:
- folio-mod-inventory-update-inventory-update-5-0-openapi.json
- folio-mod-inventory-update-inventory-update-5-0-openapi.yml