Please be aware that EDI configuration can be complex and will require ongoing communication with your EDI vendor(s) and your team at ByWater. Because there is no standard configuration that works for all libraries, multiple rounds of test orders are typical. Please expect configuration to take multiple weeks from initial setup to being fully up and running.

Libraries in implementation should be aware that we cannot test until you are fully live. EDI will not be active immediately upon go-live.

Your ByWater Educator will work with you on the steps below. Any steps that must be completed by your library are clearly marked as: 

Action item: [task details].

Setup

Step 1: System preferences

1. EdifactInvoiceImport: 'Do' or 'Don't' automatically import invoices when vendors send them to a library's FTP folder. Since importing invoices marks items as Received, ByWater sets this to 'Don't' by default. That way, items won't be marked Received until the library imports their invoice. Your library can switch this to 'Do' if preferred.
2. AcqItemSetSubfieldsWhenReceiptIsCancelled: To have Koha automatically update an item subfield if receipt is cancelled, set the subfield and value here. For instance, if you would like an item's not for loan status to revert to -1/On order if receipt is cancelled, set it as 7=-1.
   
3. AcqItemSetSubfieldsWhenReceived: This will tell Koha to automatically update item subfields when items are received. (Note that not for loan statuses can be automatically updated using each vendor's plugin.) For instance, if you would like items' not for loan status to automatically update to -2/Processing upon receipt, set this to 7=-2.
4. MarcItemFieldsToOrder: If a vendor will be sending item information in order files, this maps the tag/subfields they will use in order to create your order lines in Koha, including item details. ByWater uses a standard set of tags/subfields unless a vendor requires a specific other tag. See your EDI workbook for details.
   
5. MarcFieldsToOrder: This system preference allows vendors to send order information including price, fund, and quantity in MARC order files. This is for vendors who are not sending item information as part of the order file. ByWater uses a standard set of tags/subfields unless a vendor requires a specific other tag. See your EDI workbook for details.
   

Action item: Review preferences above, and discuss any questions or changes with your Educator.

Step 2: Create budget and funds

Action item: If they aren't set up, follow the instructions in the Koha manual to create a budget and add funds. 

Step 3: Gather account information

Action item: Complete details in workbook for each EDI vendor your library will be using.

Step 4: Create vendors

Action item: Create vendor(s) in Koha from Acquisitions > Vendors.

Step 5: Vendor grid/mapping setup

In addition to information in MarcFieldsToOrder and MarcItemFieldsToOrder, we highly recommend mapping bib-level item types in 942$c as part of your order files. If a vendor cannot do so, you will need to add 942$c to your files at the staging step by using a MARC modification template or prior to staging your file using an outside program such as MarcEdit.

Some of these mapped fields will need a list of codes that vendors will include as part of your downloaded order file. Your Educator will add EDI reports to your Reports module that you can use to generate lists of these codes.

For vendors whose order files will contain item information, the subfields listed below should be included in your mapping/grids. This list also notes the codes that should be set up as selection options for specific subfields:

Mandatory

1. Home library: map to 970$a - use library branches report
   
2. Holding library: map to 970$b - use library branches report
3. Fund: map to 970$e - use fund code report
4. Item-level item type: map to 970$y - use item types report
5. Not for loan - map to 970$7
   
1. This is typically set to -1 (Ordered or On order) for all items
   
6. Price: map to 970$g
   
7. Replacement price: map to 970$v
   
8. Quantity: map to 970$q

Strongly recommended

1. Bib-level item type: map to 942$c - use item types report

Optional (partial list)

1. Collection codes: map to 970$8 - use collection codes report
2. Shelving locations: map to 970$c - use shelving location report
   
3. See EDI workbook for full list of optional subfields

For vendors whose order files will not contain item information, the subfields listed below should be included in your mapping/grids. This list also notes the codes that should be set up as selection options for specific subfields:

Mandatory

1. Fund: map to 975$e - use fund code report
2. Quantity: map to 975$q
   
3. Price: map to 975$g

Strongly recommended

1. Bib-level item type: map to 942$c - use item types report
   

Optional (partial list)

1. Discount: map to 975$d
   
2. Replacement price: map to 975$v
   
3. See EDI workbook for full list of optional subfields

Action items: 

1. Set up grids/mapping with your vendors using the applicable tags/subfields per your EDI workbook.
   
1. If your vendor requests different tags/subfields, or cannot include a given subfield, please discuss with your Educator.
2. For the applicable fields outlined above, generate and share code lists with your vendor using the EDI reports in Koha's Reports module.
   

Step 6: Koha setup

1. Close invoice on receipt: Do you want invoices from this vendor to close automatically upon receipt?
   
1. Most libraries do not want this enabled so that they can review the invoice/received items prior to closing the invoice.
2. Add item note receipt: Do you want 'Received via EDIFACT' automatically added as a non-public note (952$x) to items upon receipt?
   
3. Update item prices: Do you want items' price (952$g), replacement price (952$v), both, or neither automatically updated based on the price in the invoice?
   
1. Note that this updates prices in the item record separate from updating order pricing. The order price updates automatically based on the invoice unless discussed otherwise.
2. Many libraries choose to not update the replacement price, since the price in the invoice often includes a discount.
   
4. Not for loan status: Do you want Koha to automatically update items' not for loan status upon receipt to a value defined here?
1. For instance, your library may want to have items’ not for loan status automatically updated to In Processing upon receipt. The options available are based on the not for loan values defined in Administration > Authorized values > NOT_LOAN category.
   
2. Note that this can also be set with the system preference AcqItemSetSubfieldsWhenReceived as discussed above. 

Step 7: Final MARC file setup (if applicable)

If your vendor will be sending final MARC files for your library to overlay atop order files, matching should occur on 999$c (Koha biblionumber) for bib overlay and 952$9 (Koha item number) for item overlay. The Koha biblionumber and item number are sent to vendors as part of your EDI order. Your library should confirm that each vendor can include these numbers as part of your final MARC files. If they cannot, discuss with your Educator. 

Note: For final MARC files, Ingram will send the biblionumber in 999$a. Libraries will need a special MARC modification template to copy that number to 999$c. Please discuss with your Educator.

If your vendor's final MARC files will include item information, the vendor may want a list of item subfields. 952 is Koha's item tag. The most common item subfields for final files are:

952$a - Home library

952$b - Holding library

952$c - Shelving location

952$g - Price

952$o - Call number

952$p - Barcode

952$v - Replacement price

952$y - Item type

952$7 - Not for loan status

952$8 - Collection code

952$9 - Item number

A full list of item subfields is available in the Koha Manual.

Note that Koha overlays the entire tag - it can't overlay only specific subfields. This means that for item overlays, any item subfields that are not included in your vendor's final MARC files will be treated as blank/null by Koha. For instance, if your order file contained an item type, home library, holding library, not for loan value, shelving location, and collection code, the final MARC file must also contain those subfields, or existing data will be blanked out when you overlay the final file.

Similarly, if your library will be overlaying bib records, you will want to make sure that your bib-level item type (942$c) is retained/included. Please discuss options with your Educator.

Action items:

1. Verify that your vendors can include 999$c (biblionumber) and, if applicable, 952$9 (item number) in your final MARC files.
   
1. Libraries receiving final MARC files from Ingram: discuss the required custom MARC modification template with your Educator.
   
2. Confirm that your vendor will include all applicable item subfields in your final MARC records.
3. Discuss options for adding/retaining the bib-level item type (942$c) for bib overlays.
   

Ordering/receiving workflow

Generate MARC order file

1. Create your order, but do not submit it.
   
2. Download the order MARC file.
   

1. Go to Cataloging > Stage records for import to stage your MARC file.
   
1. Use any MARC modification templates that you have discussed with your Educator.
   
2. Do not import the file at this step.
2. In Acquisitions, find the vendor's record, then create a new basket. 
   
3. Add to the basket using the 'From a staged file' option, and select the file you just staged.
   
1. This imports the order file into Koha.
4. Review the details for each bib/item in your order to verify that order/item information is coming through completely and correctly. If it is not, please discuss with your Educator.
   
5. Click the 'Create EDIFACT order' button to submit your order and close your basket.

You can view the status of your EDIFACT message in the basket under 'EDI status'. 

Once 'Create EDIFACT order' is clicked, 'EDI status' will change to Pending. The EDI cron runs every 15 minutes, so this will remain pending until the next run. Once it sends, the status will update again.

The status will also be visible in Acquisitions > EDIFACT messages.

Once your basket is created, its bibs/items will be visible in your OPAC/Aspen (unless you have chosen to suppress them). Depending on your settings, patrons may be able to place holds on these titles. 

Invoices and receiving

1. When you are ready to bring the invoice into Koha, go to Acquisitions > EDIFACT messages, and click the 'Import' button next to the invoice.
   
2. In Acquisitions > Invoices, find your invoice:
1. Review it for accuracy - if items have been marked Received that are not physically present, you can cancel receipt.
2. Add any adjustments.
   
3. Click 'Close' if everything is correct, and if you have received everything you expect to on this invoice.
   
4. Save your invoice.

Importing the invoice will mark items Received, so most libraries choose to wait to import invoices until they have physically received items. Depending on settings in your plugin(s) settings as discussed above, receiving items may also update not for loan statuses and prices. Please reach out to your Educator with any questions.

Overlay final files