Generic to Alma Data Delivery Specifications: Acquisitions

Generic to Alma Data Delivery Specifications: Acquisitions

Updated: 13 February 2020

1. Introduction

See the Copyright, Disclaimer, Trademarks section at the bottom of this document.

Ex Libris migrates your acquisitions data only if this service is purchased by your institution and is

stipulated in your contract with Ex Libris.

2. Overview

This document is intended to supplement the Generic to Alma Data Delivery specification. Most generic

migrations consist of Inventory and Fulfillment only, and Acquisitions is an extra migration.

There is a separate Generic Field Mapping form for Acquisitions that goes along with the Generic to

Alma Data Delivery Specifications: Acquisitions section. Contact your Ex Libris representative to get the

Generic Field Mapping form for Acquisitions.

The Generic Data Delivery form can be used for all delivered files.

2.1 Generic Migration Form: Maps for Acquisitions

There are no maps for Acquisitions migration in the Generic Migration form. Customers who are able to

contract for Generic Acquisitions migration must be technologically sophisticated to provide complex

data files to migration with minimal interaction from the migration team.

Because of this, we expect that generic acquisitions files be delivered with Alma-specific terms for

certain fields. For example, in Fines (fulfillment), there is a specific set of FineFeeTypes expected by

Alma. Customers may deliver a fine file with their own legacy fine type, and use the Migration form map

to change these from the old type to the Alma type. In other words, the migration team will provide a

structure to map fine fee types from the old sytem to an Alma value.

In Acquisitions, however, customers are expected to deliver the files with the Alma type already in the

delivered file. The expected types for these fields are listed in both Generic Field Mapping form for

Acquisitions and in Generic to Alma Data Delivery Specifications: Acquisitions.

3. Files Requested from your ILS

Ex Libris expects a certain set of files to be exported from the incoming ILS. As files are extracted, be

sure that the extracted file description, such as data elements and lengths, matches the description in

Expected File Formats.

The data elements listed below are those that Ex Libris expects to use in conversion. Not all data

elements that exist in the local ILS are necessary to transfer to Alma. If there are data elements that are

not listed, put it into a note. If you wish to have functionality tied to the missing data element, contact

your Ex Libris project manager about a functional enhancement.

NOTE: The scope of your specific conversion is agreed upon in your Alma contract.

DO NOT OPEN/UPDATE any delimited file extracts you provide to Ex Libris in Excel. This may ruin the

appropriate delimiter formatting and text formatting and may result in corrupted data.

3.1 Expected File Formats

All the files listed in the tables below are expected in CSV format with one record per line, and fields

delimited by commas and multi-values within fields delimited by semicolons.

The following is an example of a record with multiple values for the third field, using the semicolon as

separator for multiple values: “field1”,”field2”,”field3a”;”field3b”,”field4”

3.2 Generic Delivered Files Form

There is no separate delivered files form for Acquisitions. Simply type in the files delivered for

Acquisitions on the regular Generic Delivered Files list.

4. Acquisitions Files

4.1 Vendors

Ex Libris expects vendors in CSV format.

Field Name Repeatable? Notes

VEN_CREATE_DATE N

VEN_UPDATE_DATE N

VEN_CREATED_BY N

VEN_UPDATED_BY N

VENDOR_CODE N matches vendor code in order and invoice

VENDOR_NAME N

VENDOR_STATUS N ‘Active’ or ‘Inactive’

ADDITIONAL_CODE N

ALERT_NOTE N

NATL_TAX_ID N

ERP_CODE N

DETAILS_NOTE N

MATERIAL_SUPPLIER N ‘Y’ or ‘N’ (Generally all vendors here are

material suppliers. The other choice is

Licensor)

VENDOR_CURRENCY Y ISO 4217 three letter code

LIBRARY_CODE Y library code(s) in local format

EDI_CODE N

EDI_TYPE N

EDI_SERVER N

EDI_PORT N

EDI_USERNAME N

EDI_PASSWORD N

VENDOR_LANG Y must be in two-character ISO 639-1 format

VENDOR_ADDRESS_LINE1 Y - addr Vendor addresses are repeatable in groups.

If you provide two addresses, ALL fields

with the ‘Y – addr’ group must also be

repeated.

VENDOR_ADDRESS_LINE2 Y – addr




VENDOR_ADDRESS_CITY Y – addr

VENDOR_ADDRESS_STATE_PROV Y – addr

VENDOR_ADDRESS_POSTALCODE Y – addr

VENDOR_ADDRESS_COUNTRY Y – addr

VENDOR_ADDRESS_NOTE Y – addr

VENDOR_PHONE Y

VENDOR_FAX Y

VENDOR_EMAIL Y

VENDOR_URL Y - URL

VENDOR_URL_DESC Y – URL

ACCOUNT_CODE Y - acct Account is not required, but if the order has

an account, then a matching account has to

be in the vendor.

ACCOUNT_DESC Y - acct

ACCOUNT_DISCOUNT Y - acct

ACCOUNT_STATUS Y - acct

ACCOUNT_ERP Y - acct

ACCOUNT_NOTE Y - acct

ACCOUNT_EXP_REC_INT Y - acct

ACCOUNT_CLAIM_INT Y - acct

ACCOUNT_EXP_INV_INT Y - acct

ACCOUNT_EXP_ACT_INT Y - acct

ACCOUNT_REN_VAL_INT Y - acct

CONTACT_STATUS Y - contact

CONTACT_EXP_DATE Y - contact

CONTACT_LANG Y - contact

CONTACT_FIRST_NAME Y - contact

CONTACT_LAST_NAME Y - contact

CONTACT_MIDDLE_NAME Y - contact

CONTACT_JOB_TITLE Y - contact

CONTACT_EXT_ID Y - contact

CONTACT_ADD_LINE1 Y - contact





CONTACT_ADD_CITY Y - contact

CONTACT_ADD_STATE_PROV Y - contact

CONTACT_ADD_POSTALCODE Y - contact

CONTACT_ADD_COUNTRY Y - contact

CONTACT_ADD_NOTE Y - contact

CONTACT_PHONE Y - contact

CONTACT_EMAIL Y - contact

CONTACT_URL Y - contact

Any additional fields not listed above may be put into notes. The possible note fields in Alma vendors

are listed in the following chart in the Note Name column. The fields listed in the Default Local Field

column are those that are expected by Ex Libris. If you use other field names or have fields that you

want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract

fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make

as many copies of the line in the spreadsheet as needed for all note name/local field combinations.

Note Name Default Local Field

VENDOR_NOTE

4.2 Funds and Ledgers

In the fund file, LEDGER CODE, LEDGER NAME, FUND CODE, and FUND NAME are mandatory. Ledgers

are mandatory and if your institution does not have ledgers in the current ILS, define one general ledger

for use in Alma. Note that fund codes, summary fund codes, and ledgers together are unique across the

entire fiscal period, not just within specific hierarchies. Therefore, there should be no fund code,

summary fund code, or ledger code duplication in the file submitted, since all of the funds, summary

funds, and ledgers go into a single active fiscal period.

Funds are grouped under summary funds, and summary funds/funds are grouped under ledgers. Only

one level of summary fund is allowed in the extract; however, it is a simple task in Alma to create a new

summary fund after migration and drag other summary funds underneath it.

Field Name Notes

LEDGER CODE May be repeated across lines to group funds under a

single ledger

LEDGER NAME May be repeated across lines to group funds under a

single ledger

SUMMARY FUND CODE Not mandatory, may be repeated across lines

SUMMARY FUND NAME Not mandatory, may be repeated across lines

FUND CODE Alphanumeric, not repeatable. Matches Fund Code in

orders and invoices. Mandatory.

FUND NAME Alphanumeric, repeatable. Mandatory.

LIBRARY A library in the legacy ILS format; this will be sent

through the migration form Alma Library map.

If Central Order Library is used in the Migration Form,

then this field will be ignored and all funds will be set

to the institution level, meaning that all libraries in the

institution can use the fund.

EXT ID External ID for linking to an external source, if one

exists.

ALLOCATION Allocation, in local currency, of the current fiscal

year’s funds. Do not include the currency marker (e.g.

$ or €)

FY Fiscal year, if customer is providing previous year

funds for invoices. FY is defined as YYYY. If your

fiscal year crosses two calendar years, see the Fiscal

year questions on the Questionnaire tab of the

migration form to define your fiscal period.

NOTE

4.3 Purchase Orders

Ex Libris expects purchase order records in CSV delimited format.

The following fields are expected. Indicate the local field names for the expected fields in the Purchase

Order tab of the Generic Field Mapping Form - Acquisitions.

If your incoming system does not have multiple PO Lines on a single header, then put the same order

number into PO_NUMBER and POL_NUMBER, and provide only one set of POL_* fields.

Ex Libris generates a fund transaction (encumbrance) for open orders only. Closed orders are migrated

without any link to the fund. If you want to keep the fund history and encumbered amount for a closed

order, put this information into a note.


PO_CREATE_DATE N

PO_UPDATE_DATE N

PO_CREATED_BY N

PO_UPDATED_BY N

PO_LIBRARY_ID Y

PO_NUMBER N must be unique per Vendor in Alma

PO_ENTRY_POINT N NEW, SENT, CLOSED, CANCELLED (see

descriptions below) Default: SENT

PO_VENDOR N Matches vendor code in vendors. Mandatory. If

you have orders without a vendor (such as a gift

order), then give all of the gift orders a common

vendor code (such as ‘gift’) and then create a

vendor in the vendor file for this.

PO_VENDOR_ACCT N This is not required, but if it is used then there

must be a matching account in the vendor record

PO_SEND_DATE N Use only when the PO_ENTRY_POINT is SENT

or CLOSED (do not use when NEW)

PO_SHIPPING_METHOD N Text string (there is no fixed list here)

PO_APPROVE_DATE N

If there is a single PO Line for each PO header, the PO Header and Line information can be provided in the same

file. If there are multiple PO Lines for each PO Header, then the PO Header and PO Lines should be provided in

separate files. The PO Line file should additionally include a key which links it to the PO Header.

POL_CREATE_DATE Y - POL

POL_UPDATE_DATE Y - POL

POL_CREATED_BY Y - POL

POL_UPDATED_BY Y - POL

POL_LIBRARY_ID Y - POL In local library code format

POL_NUMBER Y - POL must be unique in Alma

POL_ACQ_METHOD Y - POL PURCHASE, APPROVAL, GIFT,

VENDOR_SYSTEM, DEPOSITORY,

EXCHANGE, TECHNICAL, LEGAL_DEPOSIT

(see explanation below) Default: PURCHASE

POL_ENTRY_POINT Y - POL use same values as PO_ENTRY_POINT

POL_LINE_TYPE Y - POL PRINTED_BOOK_OT,

PRINTED_JOURNAL_CO,

PRINTED_BOOK_SO, PRINT_OT, PRINT_CO,

PRINT_SO, PRINT_SO_NONMON,

OTHER_SERVICES_OT,

OTHER_SERVICES_CO (see explanation below)

POL_ADDL_NUM Y - POL additional number, usually for linking with

external systems or as an extra tracking number

POL_REP_CODE Y - POL reporting code

POL_RUSH Y - POL Y or N

POL_VEND_REF_NUM Y - POL Vendor's reference number

POL_VEND_REF_NUM_TYPE Y - POL

POL_NOTE_TO_VENDOR Y - POL instructions for the vendor that will be put on the

order when it is sent

POL_DISCOUNT Y - POL as a percentage

POL_EXP_REC_INT Y - POL expected receiving interval (claim period)

POL_EXP_REC_DATE Y - POL expected receiving date

POL_RECEIVED_DATE Y - POL

POL_EXP_ACT_INT Y - POL expected activation interval (claim)

POL_EXP_ACT_DATE Y - POL expected activation date

POL_SUB_INTERVAL Y - POL subscription interval

POL_BIB_ID Y - POL bib id is required; holding id and item id are

optional

POL_HOL_ID Y - POL (optional)

POL_ITEM_ID Y - POL links to item identifier in item file (optional)

POL_INVENTORY_LIB Y - POL library for destination of material

POL_INVENTORY_LOC Y - POL location for destination of material

POL_RECEIVING_NOTE Y - POL

POL_ITEM_QUANTITY Y - POL

POL_SUBS_START Y - POL subscription start

POL_SUBS_END Y - POL subscription end

POL_SUBS_RENEW_CYCLE Y - POL

POL_SUBS_RENEW_DATE Y - POL

POL_SUBS_REMINDER Y - POL

POL_INV_STATUS Y - POL NO_INVOICE, PARTIALLY_INVOICED or

FULLY_INVOICED

POL_USER_IDENTIFIER Y - POL If a particular patron requested this; must be an

actual identifier (not a text string). If you just

have a person’s name as text, put that into a note

POL_TOTAL_SUM Y - POL in foreign currency (currency of the invoice)

(=POL_SUM_FOREIGN *

POL_ITEM_QUANTITY)

POL_TOTAL_VAT Y - POL in foreign currency (currency of the invoice)

POL_CURRENCY Y - POL

POL_SUM_LOCAL Y - POL in local currency

POL_VAT_LOCAL Y - POL in local currency

POL_SUM_FOREIGN Y - POL in foreign currency (this is a per unit cost)

POL_VAT_FOREIGN Y - POL in foreign currency

POL_FUND Y - POL Matches fund code in funds file. If multiple funds

are used, structure the fund field like this

funda(25)|fundb(25)|fundc(50) where funda,

fundb, and fundc are fund codes, and the numbers

in parentheses are percentage distribution. The

separator is a pipe character (|)

POL_EXCHANGE_RATE Y - POL Explicit rate used at time of transaction

POL_TX_NOTE Y - POL transaction note

Any additional fields not listed above may be put into notes. The possible note fields in Alma orders are

listed in the following chart in the Note Name column. The fields listed in the Default Local Field column

are those that are expected by Ex Libris. If you use other field names or have fields that you want to

include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract fields on

the right, as necessary. If you want to include multiple local fields in the same Alma note, make as many

copies of the line in the spreadsheet as needed for all note name/local field combinations.


PO_NOTE at the level of the purchase order header

POL_NOTE at the level of the purchase order line

4.3.1 PO Entry Point

The PO Entry point indicates where the order sits in the workflow.

• NEW = order has not yet been sent. Likely it is waiting for funding. Fund codes are not required

for NEW orders.

• SENT = order has been funded and sent to the vendor. Fund codes are required. Continuous

orders (*SO or *CO line type) remain in SENT status indefinitely. A continuous order can be

received but still in SENT status because the order is expected to be received again the next

year.

• CLOSED = order is received and invoiced

• CANCELLED = order canceled

4.3.2 PO Line Type

The Alma line type value. Select one of the following line types from the drop-down list:

• PRINT_OT – printed book one time. This is used for one time or infrequent orders of specific

items, for example, a printed book, E book, or a musical score, that is not published repetitively.

The order is at the item level.

• PRINTED_BOOK_OT: Print Book One Time

• PRINT_CO – journal/continuation. This is used for orders that are repeated on a regular basis. An

example is monthly subscriptions to physical or electronic material such as journals. The order is

at the holding level, and items in the holding record are received periodically.

• PRINTED_JOURNAL_CO: Print Journal - Subscription

• PRINT_SO – standing order monograph. This is used for orders that are not repeated on a

frequent or regular basis. For example, this type of PO line is used for purchasing all the printed

books by a particular author when they are published or where a series of books are being

published, but not necessarily on a regular basis. The receipt of new material involves a new

bibliographic, holdings, and item record.

• PRINTED_BOOK_SO: Print Book – Standing Order

• PRINT_SO_NONMON - Standing Order Non-Monograph – Similar to continuous orders.

• OTHER_SERVICES_OT - Other Services One Time – Various non-inventory orders for services

purchased from a vendor. Both one-time behavior and repetitive behavior are available. This

should only be applied to orders without inventory. For electronic resources, see the ‘Line

Types and electronic orders’ section below.

• OTHER_SERVICES_CO: Other Services Subscription. This should only be applied to orders

without inventory. For electronic resources, see the ‘Line Types and electronic orders’ section

below.

Further Information: The PO may move through Alma workflows differently according to what type of

item is on order. For example, a monographic order is opened, sent to the vendor, received, invoiced,

and closed. However, a serial order may be received and invoiced many times and may remain open

(SENT) indefinitely.

Alma does have other PO Line types but they are not available for use in migration.

Line Types and Electronic Orders

The above line types are all descriptions based on a print order. All orders are stored in the legacy ILS as

print and so are migrated to Alma initially as print using the above line types. The physical to electronic

(P2E) process identifies orders attached to electronic bibliographic records and transforms the order to

electronic. In other words, if an order migrates as PRINT_SO, is attached to a bibliographic record you

identify as electronic and is in an electronic location, it is changed to the corresponding electronic

standing order line type by the P2E process.

4.3.3 PO Acquisition Method

AcqMethod is mandatory in Alma. If you are not sure which to use, then use PURCHASE.

• PURCHASE – normal workflow

• GIFT – not sent to vendor and no invoicing or payment

• EXCHANGE – not sent to vendor and no invoicing or payment

• APPROVAL – pre-established delivery plan - normal workflow except not sent to vendor

• VENDOR_SYSTEM – the order is placed at the vendor site so that sending it to the vendor is not

required. The normal workflow is followed except that the order is not sent to the vendor.

• DEPOSITORY – usually from the government. The order is not sent to vendor and there is no

invoicing or payment.

• TECHNICAL – no fund or amount required

• LEGAL_DEPOSIT – does not require fund or price, and uses a special version of the PO Line order

letter

4.3.4 Transactions of Amount 0.00

Your previous library system may allow for transactions to be of value 0.00 for all purchase orders

(encumbrances). In Alma, fund transactions can be of amount 0.00 only when it is an encumbrance and

when the associated PO is of type GIFT, DEPOSITORY, EXCHANGE, or TECHNICAL. All other

encumbrances of amount 0.00 are changed to 1.00.

4.4 Invoices

Ex Libris expects invoice records in CSV delimited format.

The following fields are expected. Indicate the local field names for the expected fields in the Invoice tab

of the Generic Field Mapping Form - Acquisitions.


INV_CREATE_DATE N

INV_UPDATE_DATE N

INV_CREATED_BY N

INV_UPDATED_BY N

INV_LIBRARY_ID N

INV_NUMBER N

INV_ENTRY_POINT N NEW, WAITING_APPROVAL, WAITING_SEND,

WAITING_PAYMENT, CLOSED, CANCELLED

Ex Libris expects migrated invoices to be generally

in the CLOSED category.

VENDOR_CODE N matches vendor code in vendor file

VENDOR_ACCT_CODE N not mandatory, but if it is used, there must be a

matching account in the vendor file

PAYMENT_VOUCHER_NUM N check number

PAYMENT_VOUCHER_DATE N

APPROVE_DATE N

APPROVE_BY N

INVOICE_DATE N

TOTAL_PRICE N in currency of invoice (foreign currency)

CURRENCY N

PAYMENT_STATUS N PAID, PARTALLY_PAID, NOT_PAID, PENDING

PAID_AMOUNT N

PAYMENT_METHOD N ACCOUNTINGDEPARTMENT, CASH,

CREDITCARD, BANKTRANSFERS,

DEPOSITACCOUNT, PREPAYMENT,

SPECIALPAYMENT, ATTACHMENT

If not provided, default is

'ACCOUNTINGDEPARTMENT'

PRE_PAID N Y or N

INV_REF_NUM N

PRO_RATA N Y or N

SHIP_AMT N

OVERHEAD_AMT N

INSURANCE_AMT N

DISCOUNT_AMT N

Invoice lines, repeatable in groups, similar to PO Lines. If there are multiple invoice lines per invoice header,

provide the invoice header and invoice line files separately, with the invoice line file using a unique key that links

it to the related invoice header.

INVL_CREATE_DATE Y - INVL

INVL_UPDATE_DATE Y - INVL

INVL_CREATED_BY Y - INVL

INVL_UPDATED_BY Y - INVL

INVL_CUST_ID Y - INVL

INVL_INST_ID Y - INVL

INVL_LIBRARY_ID Y - INVL

INVL_NUM Y - INVL invoice line number

INVL_PO_LINE Y - INVL related PO Line; matches PO_LINE_NUMBER.

This is the only way to link to related inventory.

INVL_QUANTITY Y - INVL

INVL_TOTAL_LINE_FOREIGN Y - INVL

INVL_LINE_PRICE_FOREIGN Y - INVL

INVL_VAT_FOREIGN Y - INVL

INVL_REPORTING_CODE Y - INVL

INVL_CURRENCY Y - INVL

INVL_LINE_PRICE_LOCAL Y - INVL

INVL_VAT_LOCAL Y - INVL

INVL_FUND Y - INVL matches fund code in Fund file

INVL_FISCAL_PERIOD Y - INVL in format YYYY.

INVL_EXCHANGE_RATE Y - INVL explicit rate used at time of payment

INVL_TX_NOTE Y - INVL

Any additional fields not listed above may be put into notes. The possible note fields in Alma invoices

are listed in the following chart in the Note Name column. The fields listed in the Default Local Field

column are those that are expected by Ex Libris. If you use other field names or have fields that you

want to include in the migration but are not expected by Ex Libris, you can rearrange, add, or subtract

fields on the right, as necessary. If you want to include multiple local fields in the same Alma note, make

as many copies of the line in the spreadsheet as needed for all note name/local field combinations.


INV_NOTE at the level of the invoice header

INVL_NOTE at the level of the invoice line

5. Copyright, Disclaimer, Trademarks

CONFIDENTIAL INFORMATION: The information herein is the property of Ex Libris Ltd. or its affiliates and any misuse or abuse

will result in economic loss. DO NOT COPY UNLESS YOU HAVE BEEN GIVEN SPECIFIC WRITTEN AUTHORIZATION FROM EX LIBRIS

LTD. This document is provided for limited and restricted purposes in accordance with a binding contract with Ex Libris Ltd. or

an affiliate. The information herein includes trade secrets and is confidential.

DISCLAIMER: The information in this document will be subject to periodic change and updating. Please confirm that you have

the most current documentation. There are no warranties of any kind, express or implied, provided in this documentation,

other than those expressly agreed upon in the applicable Ex Libris contract. This information is provided AS IS. Unless otherwise

agreed, Ex Libris shall not be liable for any damages for use of this document, including, without limitation, consequential,

punitive, indirect or direct damages. Any references in this document to third-party material (including third-party Web sites)

are provided for convenience only and do not in any manner serve as an endorsement of that third-party material or those

Web sites. The third-party materials are not part of the materials for this Ex Libris product and Ex Libris has no liability for such

materials.

TRADEMARKS: "Ex Libris," the Ex Libris Bridge to Knowledge, Primo, Aleph, Voyager, SFX, MetaLib, Verde, DigiTool, Rosetta, bX,

URM, Alma, and other marks are trademarks or registered trademarks of Ex Libris Ltd. or its affiliates. The absence of a name

or logo in this list does not constitute a waiver of any and all intellectual property rights that Ex Libris Ltd. or its affiliates have

established in any of its products, features, or service names or logos. Trademarks of various third-party products, which may

include the following, are referenced in this documentation. Ex Libris does not claim any rights in these trademarks. Use of

these marks does not imply endorsement by Ex Libris of these third-party products, or endorsement by these third parties of Ex

Libris products.

Oracle is a registered trademark of Oracle Corporation. UNIX is a registered trademark in the United States and other countries,

licensed exclusively through X/Open Company Ltd. Microsoft, the Microsoft logo, MS, MS-DOS, Microsoft PowerPoint, Visual

Basic, Visual C++, Win32, Microsoft Windows, the Windows logo, Microsoft Notepad, Microsoft Windows Explorer, Microsoft

Internet Explorer, and Windows NT are registered trademarks and ActiveX is a trademark of the Microsoft Corporation in the

United States and/or other countries. Unicode and the Unicode logo are registered trademarks of Unicode, Inc. Google is a

registered trademark of Google, Inc.

Copyright Ex Libris Limited, 2020. All rights reserved.

Web address: http://www.exlibrisgroup.com

Documents

Generic to Alma Data Delivery Specifications: Acquisitions