Author	Olamide Kolawole/Serhii Nosko
JIRA task	Folijet: Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration. Thunderjet Support: TBD
Business Requirements	Using MARC Bibs and Data Import to create FOLIO POLs Create orders by importing MARC Bibliographic Records SME Slide Deck
Architects Review	IN PROGRESS
PO review	IN PROGRESS

Revision History

Version	Date	Owner	Description
v1.0	06.26.2022	Serhii_Nosko	Initial version
v1.1	06.28.2022	Serhii_Nosko	Add model schemas
v1.2	06.30.2022	Serhii_Nosko	Add diagrams for Inventory creation
v1.3	06.30.2022	Serhii_Nosko	Add diagrams for creating and opening orders
v1.4	07.07.2022	Olamide Kolawole	Formatting changes
v1.5	08.07.2022	Serhii_Nosko	Add receiving API
v1.6	26.10.2022	Kateryna Senchenko	Add flow description with explicit DI actions for creating Order, Instance, Holdings and Item (requires post-processing step in mod-orders)

Overview

This document will illustrate the design that will integrate the Orders module area with Data Import(DI) module area. Order lines will be defined in MARC Bibliographic(MARC Bib) files by a user. The MARC Bib files will be parsed by DI and have records sent to mod-orders via Kafka eventing.

Solution Design

Architectural Requirements

Dependency Inversion: Unlike traditional integrations that have been implemented with Inventory and less so with Invoices, Orders will be a consumer of Data Import. Data Import will be responsible for parsing input files from a user into a form that FOLIO modules will understand to Create/Update their respective objects.
Single Source of Truth: This design should ensure that business logic only lives in one location within the FOLIO system. Orders and Data Import should not have copies/variants of the same functionality. This will reduce maintenance issues, clearly designate responsibilities and reduce cognitive load when developing the Orders and Data Import sub-systems.
Clearly Defined Input & Outputs of Components: Each component in the process flow should have clearly defined inputs and outputs. The cardinality of inputs and outputs of each component should be generally less than three. If the cardinality is more than three, then division of the component should be considered.

Process Flows

Basic flow for creating Pending Order

User triggers creating of the order via API

Source code for sequence diagram

@startuml
!pragma teoz true
!theme cerulean

skinparam backgroundColor white
autonumber "<b>[0]"

actor user as user
participant "mod-orders" as ord
participant "mod-orders-storage" as ords

user -> ord: create order
activate ord
    ord -> ord: validate order payload
    ord -> ords: persist order
    ords --> ord: created order dto
    ord -> ords: persist order lines
    ords --> ord: created order lines dto
 
deactivate ord

@enduml

Basic flow for creating Open Order

User triggers creation of the Order with Inventory Instance, Holdiings and Item

Source code for sequence diagram

@startuml
!pragma teoz true
!theme cerulean

skinparam backgroundColor white
autonumber "<b>[0]"

actor user as user
participant "mod-orders" as ord
participant "mod-orders-storage" as ords
participant "mod-inventory" as inv
participant "mod-finance" as finance

user -> ord: create order
activate ord
    ord -> ord: validate order payload
    ord -> ords: persist order
    ord -> ords: persist order lines
    ord -> inv: create Instance, Holdings, Item
    ord -> ords: persist Pieces
    ord -> ord: connect Pieces with Inventory items
    ord -> inv: update Invenory items with pieces connection
    ord -> finance: create Encumbrances
    ord -> ords: update order status to Open  
deactivate ord
@enduml

Create Pending Order with subsequent creation of Inventory entities (with source=FOLIO, no link to SRS MARC Bib)

If importing Order should be created in Pending status, no subsequent actions in the JobProfile will be processed. Therefore, Inventory entities that should be created when the Order is opened will not be mapped from the MARC source, but instead created out of existing Order information via Inventory API and assigned source=FOLIO. In this case the value Create Inventory, selected in the MARC-to-Order Mapping Profile, would determine which entities should be created. DI_COMPLETED event should be issued and JobExecution completed regardless of subsequent actions in the JobProfile.

Create Order, Instance, Holdings, Item following the JobProfile (requires Post-processing step for Orders) - Applicable for Orders that should be created in Open status

JobProfile for this flow should contain explicit actions with linked mappings for each entity that is expected to be created as a result of data import job. In this case value selected in Create Inventory field of the MARC-to-Order Mapping profile will be ignored.

Sequence diagram. Please note that DI_ERROR can be issued on each step of the processing, but was omitted for simplicity.

Source code for sequence diagram

@startuml
!pragma teoz true
!theme cerulean

skinparam backgroundColor white
autonumber "<b>[0]"

participant "mod-source-record-manager" as srm
participant "mod-orders" as ord
participant "mod-orders-storage" as ords
participant "mod-inventory" as inv
participant "mod-finance" as finance

  activate ord
    srm -> ord: **<<DI_ORDER_READY_TO_CREATE>>**
    ord -> ord: map order from MARC record
    ord -> ords: persist order
    ord -> ords: persist order lines
  activate inv
    ord -> inv: **<<DI_PENDING_ORDER_CREATED>>**
  deactivate ord 
  
    inv -> inv: Create Instance
    inv -> srm: <<DI_INVENTORY_INSTNACE_CREATED>>
    inv -> inv: Create Holdings
    inv -> srm: <<DI_INVENTORY_HOLDINGS_CREATED>>
    inv -> inv: Create Item
    inv -> srm: <<DI_INVENTORY_ITEM_CREATED>>
  activate ord
    inv -> ord: **<<DI_INVENTORY_FOR_ORDER_CREATED>>**
  deactivate inv    

    ord -> ords: persist Pieces
    ord -> ord: connect Pieces with Inventory items
    ord -> inv: update Invenory items with pieces connection
    ord -> finance: create Encumbrances
    ord -> ords: update order status to Open
    ord -> srm: <<DI_COMPLETED>>
  deactivate ord 
  
@enduml

Updated (Q1 2024)

Source code for sequence diagram

@startuml
!pragma teoz true
!theme cerulean

skinparam backgroundColor white
autonumber "<b>[0]"

participant "mod-source-record-manager" as srm
participant "mod-orders" as ord
participant "mod-orders-storage" as ords
participant "mod-inventory" as inv
participant "mod-finance" as finance

  activate ord
    srm -> ord: **<<DI_INCOMING_MARC_BIB_FOR_ORDER_PARSED>>**
    ord -> ord: map order from MARC record
    ord -> ords: persist order
    ord -> ords: persist order lines
  activate inv
    ord -> inv: **<<DI_PENDING_ORDER_CREATED>>**
  deactivate ord 
  
    inv -> inv: Create Instance
    inv -> srm: <<DI_INVENTORY_INSTANCE_CREATED>>
    inv -> inv: Create Holdings
    inv -> srm: <<DI_INVENTORY_HOLDINGS_CREATED>>
    inv -> inv: Create Item
    inv -> srm: <<DI_INVENTORY_ITEM_CREATED>>
  activate ord
    inv -> ord: **<<DI_ORDER_CREATED_READY_FOR_POST_PROCESSING>>**
  deactivate inv    

    ord -> ords: persist Pieces
    ord -> ord: connect Pieces with Inventory items
    ord -> inv: update Invenory items with pieces connection
    ord -> finance: create Encumbrances
    ord -> ords: update order status to Open
    ord -> srm: <<DI_COMPLETED>>
  deactivate ord 
  
@enduml

APIs

DI will communicate with mod-orders using kafka messaging, the same approach used for Inventory and Invoice module areas

Business Requirements

Should orders be created as pending or open?

Use cases for both, so include required field at top of field mapping profile that allows the user to set the status

Create orders

Applies when user choses to create pending order on the field mapping profile screen.

There is field in compositePurchaseOrder request payload named workflowStatus, it will be PENDING by default.

For creating orders CreateOrderEventHandler will use the same implementation as corresponding endpoint uses.

Method

Url

Request parameters

Request payload

Description

POST

/orders/composite-orders

lang

compositePurchaseOrder

Post a purchase order (PO) and a number of PO lines; record fund transactions corresponding to the order. Only in case an acquisition unit has to be assigned to 
the Order it is required that user should have extra permission orders.acquisitions-units-assignments.item.post to create an purchase order.

Open orders

Applies when user choses to create open order on the field mapping profile screen.

There is field in compositePurchaseOrder request payload named workflowStatus, it should be set as OPEN.

For creating orders CreateOrderEventHandler will use the same implementation as corresponding endpoint uses.

Method

Url

Request parameters

Request payload

Description

POST

/orders/composite-orders

lang

compositePurchaseOrder

Post a purchase order (PO) and a number of PO lines; record fund transactions corresponding to the order. Only in case an acquisition unit has to be assigned to 
the Order it is required that user should have extra permission orders.acquisitions-units-assignments.item.post to create an purchase order.

Receive orders

Basically from mod-orders side receiving and check-in API it the same thing.

Method	Url	Request parameters	Request payload	Description
POST	/orders/check-in	lang	checkingCollection	Check-in items spanning one or more PO lines

Work Breakdown Structure

Open Items

Question	Status	Answer
Oder payload has field 'approved', that is false by default. What value for this field DI should populate?	IN PROCESS	Ann-Marie Breaux (Deactivated) will discuss with SMEs.
When we have situation that max order lines limit is 10, but have 15 order lines and 2 orders in marc file, how they should be mapped?	IN PROCESS	Ann-Marie Breaux (Deactivated) will discuss with SMEs.
PO number can be auto generated by mod-orders system. Does it necessary to place this field on Order mapping profile?	IN PROCESS	Ann-Marie Breaux (Deactivated) will discuss with SMEs.
When creating order lines - its necessary to specify order source from these allowed values: [User, API, EDI, MARC, EBSCONET]. For our case it should be MARC?	CLOSED	MARC value should be used.
Do we need to support orders check-in after receiving?	CLOSED	Updated after conversation with Thunderjet Actually, checking and receive is the same thing, DI should use checking endpoint implementation
Is it possible scenario when DI going to open order, but not create any Instance, Holdings. Item?	CLOSED	Yes, it's possible the library is ordering something that they do not want represented in Inventory (like a database that they maybe want to handle through the ERM app), or other random things that they do not plan to keep in their permanent collection.

Open items to brainstorm with SA, Devs

Question

Status

Answer

We use database tables for DI handlers deduplication. Mod-orders does not have schema in DB and any DB related code.

Do we need to follow the same approach with introducing schema as we did in mod-inventory

CLOSED

Yes, we need to follow the same approach for event deduplication as in mod-inventory.

If we are going to create Inventory Instance, Holdings, Item separately - need to discuss with Thunderjet possibility to indroduce

new order parameter inventoryFlow with allowed values: [Synchronized, Independent], the same as did in Order Receiving flow

CLOSED

We will not introduce new parameter inventoryFlow, if need possibility to distinguish logic - orderSource field should be used.

DI will always pass MARC as order source.

Created stories

Description	Module	Story
Create default order mapping profile	data-import-converter-storage	TBD
Extend mapping engine with ability to create order and multiple order lines from the same MARC record.	data-import-processing-core	TBD
Adjust mod-orders to validate purchase order lines limit from Orders mapping profile
Add kafka handlers in mod-orders	mod-orders	TBD

Appendix

Data Model: Purchase Order

Composite purchase order request payload

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "composite purchase order with dereferenced/expanded orders fields",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID of this purchase order",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "approved": {
      "description": "whether or not the purchase order has been approved",
      "type": "boolean",
      "default": false
    },
    "approvedById": {
      "description": "UUID of the user approving the order",
      "type": "object",
      "$ref": "../../common/schemas/uuid.json"
    },
    "approvalDate": {
      "description": "Date and time when purchase order was approved",
      "type": "string",
      "format": "date-time"
    },
    "assignedTo": {
      "description": "UUID of the user this purchase order his assigned to",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "billTo": {
      "description": "UUID of the billing address",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "closeReason": {
      "description": "Close reason for purchase order. Some values are predefined and can trigger actions, such as Cancelled. See mod-orders-storage/src/main/resources/data/system/reasons-for-closure",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/close_reason.json"
    },
    "dateOrdered": {
      "description": "Date and time when purchase order was opened",
      "type": "string",
      "format": "date-time",
      "readonly": true
    },
    "manualPo": {
      "description": "if true, order cannot be sent automatically, e.g. via EDI",
      "type": "boolean"
    },
    "notes": {
      "description": "free-form notes associated with this purchase order",
      "id": "notes",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "poNumber": {
      "description": "A human readable ID assigned to this purchase order",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]{1,22}$"
    },
    "poNumberPrefix": {
      "description": "Purchase order number prefix",
      "type": "string"
    },
    "poNumberSuffix": {
      "description": "Purchase order number suffix",
      "type": "string"
    },
    "orderType": {
      "description": "the purchase order type",
      "type": "string",
      "enum": [
        "One-Time",
        "Ongoing"
      ]
    },
    "reEncumber": {
      "description": "indicates this purchase order should be re-encumbered each fiscal year. Only applies to ongoing orders",
      "type": "boolean",
      "default": false
    },
    "ongoing": {
      "description": "Ongoing information associated with this order",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/ongoing.json"
    },
    "shipTo": {
      "description": "UUID of the shipping address",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "template": {
      "description": "The ID of the order template used for this order. Applies to both PO and POL",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "totalEstimatedPrice": {
      "description": "total estimated price of this purchase order",
      "type": "number"
    },
    "totalEncumbered": {
      "description": "Total encumbered for the order",
      "type": "number",
      "readonly": true
    },
    "totalExpended": {
      "description": "Total expended for the order",
      "type": "number",
      "readonly": true
    },
    "totalItems": {
      "description": "total number of items included in the purchase order",
      "type": "integer"
    },
    "vendor": {
      "description": "UUID of the vendorDetails record",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "workflowStatus": {
      "description": "the workflow status for this purchase order",
      "type": "string",
      "$ref": "../../mod-orders-storage/schemas/workflow_status.json"
    },
    "compositePoLines": {
      "description": "a list of completely de-referenced purchase order lines",
      "id": "compositePoLines",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "composite_po_line.json"
      }
    },
    "acqUnitIds": {
      "description": "acquisition unit ids associated with this purchase order",
      "type": "array",
      "items": {
        "$ref": "../../common/schemas/uuid.json"
      }
    },
    "tags": {
      "type": "object",
      "description": "arbitrary tags associated with this purchase order",
      "$ref": "../../../raml-util/schemas/tags.schema"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    },
    "needReEncumber": {
      "description": "Indicates that order needs to be re-encumbered",
      "type": "boolean",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "vendor",
    "orderType"
  ]
}

Required fields

Field name	Allowed values	Description
orderType	[One-Time, Ongoing]	DI will setup only One-Time order type
vendor	-	Vendor that user chooses on Order field mapping profile

Not applicable fields for DI orders flow

Business requirements to answer why provided fields are not necessary to populated

Business Requirements

Use for one-time orders (physical, electronic, or both). Do not use for ongoing or package orders
Should field mapping profiles use order templates?
- No. The field mapping profile and its mapped/default data already acts as a template. Once a field mapping profile is set up, it does not have to be re-created each time a user imports
Can it create/assign order notes?
- No. Not the order notes created in the separate notes app
Can it create/assign tags?
- No, not yet, for any record type. Aiming to support tags in a future version of DI

Field name	Allowed values	Description
reEncumber	[True, False]	Indicates this purchase order should be re-encumbered each fiscal year
needReEncumber	[True, False]	Indicates that order needs to be re-encumbered
ongoing	-	Ongoing object includes these fields: interval, isSubscription, manualRenewal, notes, reviewPeriod, renewalDate, reviewDate All these fields should not be populated from DI, because DI does not support ongoing orders.
template	-	Predefined template to create order from
notes	-	Free-form notes associated with this purchase order
tags	-	List of simple tags that can be added to the purchase order

Data Model: Composite Purchase Order Lines

Composite po lines request payload

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "composite purchase order line with dereferenced/expanded orders fields",
  "type": "object",
  "properties": {
    "id": {
      "description": "UUID identifying this purchase order line",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "edition": {
      "description": "edition of the material",
      "type": "string"
    },
    "checkinItems": {
      "description": "if true this will toggle the Check-in workflow for details associated with this PO line",
      "type": "boolean",
      "default": false
    },
    "instanceId": {
      "description": "UUID of the instance record this purchase order line is related to",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "agreementId": {
      "description": "UUID of the agreement this purchase order line is related to",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "acquisitionMethod": {
      "description": "UUID of the acquisition method for this purchase order line",
      "type": "string",
      "$ref": "../../common/schemas/uuid.json"
    },
    "automaticExport": {
      "description": "if true then line will be marked as available to export in the EDIFACT format or other format",
      "type": "boolean",
      "default": false
    },
    "alerts": {
      "description": "alerts associated with this purchase order line",
      "id": "alerts",
      "type": "array",
      "items": {
        "description": "an alert record",
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/alert.json"
      }
    },
    "cancellationRestriction": {
      "description": "whether or not there are cancellation restrictions for this purchase order line",
      "type": "boolean"
    },
    "cancellationRestrictionNote": {
      "description": "free-form notes related to cancellation restrictions",
      "type": "string"
    },
    "claims": {
      "description": "claims associated with this purchase order line",
      "id": "claims",
      "type": "array",
      "items": {
        "description": "a claim record",
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/claim.json"
      }
    },
    "collection": {
      "description": "whether or not this purchase order line is for a collection",
      "type": "boolean"
    },
    "contributors": {
      "description": "list of contributors to the material",
      "id": "contributors",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/contributor.json"
      }
    },
    "cost": {
      "description": "cost details associated with this purchase order line",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/cost.json"
    },
    "description": {
      "description": "description of the material",
      "type": "string"
    },
    "details": {
      "description": "details about this purchase order line",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/details.json"
    },
    "donor": {
      "description": "the donor contributing to this purchase order line",
      "type": "string"
    },
    "eresource": {
      "description": "eresource-related details of this purchase order line",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/eresource.json"
    },
    "fundDistribution": {
      "description": "the UUIDs of the fund distribution records for this purchase order line",
      "id": "fundDistribution",
      "type": "array",
      "items": {
        "description": "a fund distribution record",
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/fund_distribution.json"
      }
    },
    "isPackage": {
      "description": "Indicates that this POL is for a package",
      "type": "boolean",
      "default": false
    },
    "locations": {
      "description": "a list of the location records for this purchase order line",
      "id": "locations",
      "type": "array",
      "items": {
        "description": "The location details",
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/location.json"
      }
    },
    "lastEDIExportDate": {
      "description": "The last date when line was exported in the EDIFACT file",
      "type": "string",
      "format": "date-time"
    },
    "orderFormat": {
      "description": "The purchase order line format",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/order_format.json"
    },
    "packagePoLineId": {
      "description": "UUID referencing the poLine that represents the package that this POLs title belongs to",
      "$ref": "../../common/schemas/uuid.json"
    },
    "paymentStatus": {
      "description": "The purchase order line payment status",
      "type": "string",
      "$ref": "../../mod-orders-storage/schemas/payment_status.json"
    },
    "physical": {
      "description": "details of this purchase order line relating to physical materials",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/physical.json"
    },
    "poLineDescription": {
      "description": "purchase order line description",
      "type": "string"
    },
    "poLineNumber": {
      "description": "A human readable number assigned to this PO line",
      "type": "string",
      "pattern": "^[a-zA-Z0-9]{1,22}-[0-9]{1,3}$",
      "readonly": true
    },
    "publicationDate": {
      "description": "date (year) of the material's publication",
      "type": "string"
    },
    "publisher": {
      "description": "publisher of the material",
      "type": "string"
    },
    "purchaseOrderId": {
      "description": "UUID of this parent purchase order",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
    },
    "receiptDate": {
      "description": "date the purchase order line was received",
      "type": [
        "null",
        "string"
      ],
      "format": "date-time"
    },
    "receiptStatus": {
      "description": "The purchase order line receipt status",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/receipt_status.json"
    },
    "renewalNote": {
      "description": "Renewal note for this purchase order line",
      "type": "string"
    },
    "reportingCodes": {
      "description": "a list of reporting codes associated with this purchase order line",
      "id": "reportingCodes",
      "type": "array",
      "items": {
        "type": "object",
        "$ref": "../../mod-orders-storage/schemas/reporting_code.json"
      }
    },
    "requester": {
      "description": "who requested this purchase order line",
      "type": "string"
    },
    "rush": {
      "description": "whether or not this is a rush order",
      "type": "boolean"
    },
    "selector": {
      "description": "who selected this material",
      "type": "string"
    },
    "source": {
      "description": "the source of this purchase order line",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/source.json"
    },
    "tags": {
      "description": "arbitrary tags associated with this purchase order line",
      "id": "tags",
      "type": "object",
      "$ref": "../../../raml-util/schemas/tags.schema"
    },
    "titleOrPackage": {
      "description": "title of the material",
      "type": "string"
    },
    "vendorDetail": {
      "description": "details related to the vendor of this purchase order line",
      "type": "object",
      "$ref": "../../mod-orders-storage/schemas/vendor_detail.json"
    },
    "metadata": {
      "type": "object",
      "$ref": "../../../raml-util/schemas/metadata.schema",
      "readonly": true
    }
  },
  "additionalProperties": false,
  "required": [
    "acquisitionMethod",
    "cost",
    "orderFormat",
    "source",
    "titleOrPackage"
  ]
}

Required Fields

Field name	Allowed values	Description
acquisitionMethod	-	The UUID format string
cost	-	The purchase order line cost. Includes fields: "listUnitPrice", "listUnitPriceElectronic", "currency", "additionalCost", "discount", "discountType", "exchangeRate", "quantityPhysical", "quantityElectronic", "poLineEstimatedPrice", "fyroAdjustmentAmount" Currency field is required.
orderFormat	[Electronic Resource, P/E Mix, Physical Resource, Other]	The purchase order line format
source	[User, API, EDI, MARC, EBSCONET]	The source of the order
titleOrPackage	-	The title of the materials

Not applicable fields for DI orders flow

Business requirements to answer why provided fields do not necessary to populate

Requirements from business

Use for one-time orders (physical, electronic, or both). Do not use for ongoing or package orders

Field name	Allowed values	Description
isPackage	[True, False]	Indicates that this POL is for a package. Default - false
packagePoLineId	-	Specify package po line id, applicable only package orders
renewalNote	-	Specify renewal note, applicable only for ongoing orders

Data Model: Check-in Collection

Receiving and check-in are the same things from mod-orders API side

Checking collection request payload

{
   "$schema":"http://json-schema.org/draft-04/schema#",
   "description":"A collection of check-in",
   "type":"object",
   "properties":{
      "toBeCheckedIn":{
         "description":"List of check-in",
         "id":"toBeCheckedIn",
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "poLineId":{
                  "description":"The id of the checkin PO line",
                  "type":"string",
                  "pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
               },
               "checkedIn":{
                  "description":"The number of pieces to check-in",
                  "type":"integer"
               },
               "checkInPieces":{
                  "description":"A collection of piece records",
                  "type":"array",
                  "id":"checkInPieces",
                  "items":{
                     "type":"object",
                     "properties":{
                        "id":{
                           "description":"The id of the piece",
                           "type":"string",
                           "pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                        },
                        "barcode":{
                           "description":"The barcode assigned to the piece",
                           "type":"string"
                        },
                        "callNumber":{
                           "description":"The call number assigned to the piece",
                           "type":"string"
                        },
                        "comment":{
                           "description":"The free form notes pertaining to the piece",
                           "type":"string"
                        },
                        "caption":{
                           "description":"The enumeration caption of the piece",
                           "type":"string"
                        },
                        "createItem":{
                           "description":"Whether or not to create an item record for this piece",
                           "type":"boolean"
                        },
                        "supplement":{
                           "description":"Whether or not this is a supplementary material for this piece",
                           "type":"boolean"
                        },
                        "locationId":{
                           "description":"The id of the location",
                           "type":"string",
                           "pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                        },
                        "holdingId":{
                           "description":"UUID of the holding record",
                           "$ref":"../../common/schemas/uuid.json"
                        },
                        "displayOnHolding":{
                           "description":"Whether or not receiving history should be displayed in holding record view",
                           "type":"boolean",
                           "default":false
                        },
                        "enumeration":{
                           "type":"string",
                           "description":"Enumeration is the descriptive information for the numbering scheme of a serial. Synchronized with inventory item."
                        },
                        "chronology":{
                           "type":"string",
                           "description":"Chronology is the descriptive information for the dating scheme of a serial. Synchronized with inventory item."
                        },
                        "discoverySuppress":{
                           "type":"boolean",
                           "description":"Records the fact that the record should not be displayed in a discovery system"
                        },
                        "copyNumber":{
                           "type":"string",
                           "description":"Copy number of the piece"
                        },
                        "materialTypeId":{
                           "description":"The id of the materialType",
                           "type":"string",
                           "pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                        },
                        "productId":{
                           "description":"The id of the Product",
                           "type":"string"
                        },
                        "productIdType":{
                           "description":"The UUID corresponding to the type of product id",
                           "type":"string",
                           "pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
                        },
                        "accessionNumber":{
                           "description":"The number referencing physical item acquired by the library",
                           "type":"string"
                        },
                        "itemDescription":{
                           "description":"The description associated with the item record",
                           "type":"string"
                        },
                        "electronicBookplate":{
                           "description":"A text that relates to the owner of the book",
                           "type":"string"
                        },
                        "itemStatus":{
                           "description":"The status of the Check in piece",
                           "$ref":"item_status.json"
                        }
                     },
                     "additionalProperties":false
                  }
               }
            },
            "additionalProperties":false,
            "required":[
               "poLineId"
            ]
         }
      },
      "totalRecords":{
         "description":"The total number of pieces to check-in in the list",
         "type":"integer"
      }
   },
   "additionalProperties":false,
   "required":[
      "toBeCheckedIn",
      "totalRecords"
   ]
}

Required fields

Field name	Allowed values	Description
toBeCheckedIn	-	Contains purchase order line id and collection of pieces to be checked in
totalRecords	-	Total records size to be checked in

Import Orders in MARC format

Revision History

Overview

Solution Design

Architectural Requirements

Process Flows

User triggers creating of the order via API

Basic flow for creating Open Order

Create Pending Order with subsequent creation of Inventory entities (with source=FOLIO, no link to SRS MARC Bib)

Create Order, Instance, Holdings, Item following the JobProfile (requires Post-processing step for Orders) - Applicable for Orders that should be created in Open status

APIs

Create orders

Open orders

Receive orders

Work Breakdown Structure

Open Items

Open items to brainstorm with SA, Devs

Created stories

Appendix

Data Model: Purchase Order

Required fields

Not applicable fields for DI orders flow

Data Model: Composite Purchase Order Lines

Required Fields

Not applicable fields for DI orders flow

Data Model: Check-in Collection

Required fields