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.

The Koha Manual gives an overview of the EDI ordering process and setup requirements. 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 your library imports each 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 (commonly 'On order' or 'Ordered') if receipt is cancelled, set it as 7=-1.
   
3. AcqItemSetSubfieldsWhenReceived: This will tell Koha to automatically update item subfields when items are received. For instance, if you would like items' not for loan status to automatically update to -2/Processing upon receipt, set this to 7=-2. Note that not for loan statuses can also be automatically updated using each vendor's plugin.
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 different specific tag. See Step 9 below 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 different specific tag. See Step 9 below 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: Create vendors

1. In a consortium, each library system typically has their own account for each vendor. So, the accounts in Koha could be Vendor A - County X Library, Vendor A - County Y Library, Vendor A - County Z Library (etc.).
2. In a unified system with multiple locations where each branch does their own ordering, each branch may have a separate account for the same vendor. This could look like Vendor A - Main branch, Vendor A - East branch, Vendor A - West branch (etc.).
3. A single-location library may have separate accounts for Adult, Teen, and Children's materials for the same vendor. This could look like Vendor A - Adult, Vendor A - Teen, Vendor A - Children's (etc.). 

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

Step 4: Gather account information

1. Library EAN(s) and qualifier: Libraries with multiple ordering accounts will typically have multiple EANs.
2. Library SAN and qualifier:
1. A library SAN may be required by your vendor(s) in addition to your Library EAN. If your vendor does not require this, you may skip these two entries in the workbook.
2. SANs are assigned by Bowker Publishing Services. If your vendor requires a SAN but you are not sure what yours is, you can contact Bowker Support at (856) 399-7495 or isbn-san@bowker.com to look it up. If they tell you that none exists, they can be created by/purchased from Bowker.

Action items: 

1. Make a copy of the EDI workbook for your library's use.
   
2. Complete details on your copy of the workbook for each vendor your library will be ordering with for EDI. 
   
3. Submit a ticket with your workbook linked (preferred) or attached so that a ByWater Solutions Educator can configure your plugin. Note that we cannot configure your plugin without this information.

Step 5: Plugin setup

Action items:

1. Confirm that you have submitted a ticket with your EDI workbook linked (preferred) or attached.
   
2. Respond to any questions from your Educator about your workbook.
   

Step 6: File transports

In Administration > File transports (under Additional parameters), create a new file transport with the following:

1. Name: The name that will be visible for selection in EDI accounts.
2. Transport: SFTP (default) or FTP.
3. Host: FTP address provided by your vendor.
4. Port: 22 (default; use for SFTP) or 21 for FTP.
5. Passive mode: Defaults to On (Recommended)/Enabled (Recommended) for FTP, but can set to Off/Disabled.
1. This does not apply to SFTP connections.
2. Leave at Enabled for FTP connections.
6. Authentication mode: Defaults to Password-based.
1. Keep this set to Password-based. This should only be changed by ByWater Solutions.
7. Username: Provided by your EDI vendor.
8. Password: Provided by your EDI vendor.
1. Once this is entered, passwords will be hashed, which means that they won't be visible to your library or recovered/viewed by ByWater Solutions staff.
9. Key file: Leave unset.
10. Remote download directory: Provided by your EDI vendor.
11. Remote upload directory: Provided by your EDI vendor.
12. Debug mode: Set to Disabled.
1. ByWater Solutions staff will update this to Enabled if needed for troubleshooting.

The completed screen should look similar this (with your vendor's details substituted):

Click 'Submit' to continue.

When you save the new connection (or edit an existing connection), you will receive a confirmation screen. For SFTP connections, it will look like this:

For FTP connections:

Click 'Save' to complete the new file transport (or save edits to an existing transport).

Action item: Create new File transfer settings using the details gathered in your EDI workbook.

Step 7: EDI accounts

1. Basic information:
1. Vendor: Select from the vendors you created in step 3.
   
2. Description: Enter a description that will help library staff identify this account, including distinguishing it from other accounts with the same vendor if applicable. This could include the library name (if multiple libraries or branches have accounts with the same vendor), account number, or account purpose (such as Teen, Grant Orders, Processed etc.).
3. Plugin: Select the plugin for this vendor.
4. Qualifier: Provided by your EDI vendor (or copied from the EDI workbook if listed there).
   
5. SAN: This is the vendor's SAN, not the library's SAN. It will be provided by your EDI vendor (or may be copied from the EDI workbook if listed there).
   
6. Standard: Provided by your EDI vendor (or copied from the EDI workbook if listed there).
   
2. Transport settings: Select the file transport settings for this vendor that you created in step 6.
   
3. Message types: Select 'Orders enabled' and 'Invoices enabled' unless discussed otherwise with your vendor and ByWater Solutions.
   
4. Functional switches: Leave both options deselected unless discussed otherwise with your vendor and ByWater Solutions.
   

Action item: Create EDI accounts settings for each account you will use for EDI ordering.

Step 8: Library EANs

1. Library: Leave at 'All libraries', or limit to a specific library if this account should only be used by one location.
   
2. Description: Enter a description that will help library staff identify this account, including distinguishing it from other accounts with the same vendor if applicable. This could include the library name (if multiple libraries or branches have accounts with the same vendor), account number, or account purpose (such as Teen, Grant Orders, Processed etc.).
3. EAN: Enter your EAN as provided by your vendor and entered in your EDI workbook.
   
4. Qualifier: Select the qualifier as provided by your vendor (or copied from the EDI workbook if listed there).
   

Action item: Create Library EAN settings for each account you will use for EDI ordering.

Step 9: 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 10: 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. If they cannot include both, discuss with your Educator.
2. 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

Creating orders

1. Use any MARC modification templates that you have discussed with your Educator.
   
2. Do not import the file at this step.
   

1. If you did not already stage your file, select the 'From a new file' option. Be sure to use any MARC modification templates that you have discussed with your Educator. Review the staged file, then complete the import. 
2. If you staged your file previously in Cataloging, use the 'From a staged file' option, and select the file you staged earlier. 

1. If your EDI vendor's grid/mapping only includes order information (price, quantity, and fund) but not item information, verify the order details and add item details as needed.
2. If your EDI vendor's grid/mapping contains order and item information, verify that both have imported completely and correctly.
   
3. If any details are not displaying as you expect, please discuss with your Educator.
   
4. Once your order file has been imported into a basket, 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. 

1. 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.
2. You can view the status of your EDIFACT message in the basket under 'EDI status'. 
   

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

1. If your library individually imports invoices into Koha when staff are ready to review them (typically when items have physically arrived at the library), start with step 1.
   
2. If your library is automatically importing invoices as soon as the vendor sends them, start with step 2 (this is less common).
   

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.

Cataloging/processing (overlaying final files)

1. Typically, libraries use the 999$c/Koha biblionumber matching rule for final files. When applicable, Koha matches for item overlay on 952$9/item number. The biblionumber and item number are sent to vendors as part of your EDI order, and they should include them in your final files so that they overlay properly.
   
2. Please discuss any questions about which settings to use for staging/importing final files with your Educator.