Alma NCIP Integration System Addon

The Alma NCIP Integration system addon allows for integration between ILLiad and Alma using NCIP. This addon uses NCIP v2 calls to the Alma NCIP responder.

Installation

The addon is a system addon for the ILLiad client. The addon must be installed on each client where NCIP functionality is used; any ILLiad client performing checking in from lending libraries, checking in borrowing items from patrons, marking lending items as found, and handling lending returns. Please refer to the addon installation documentation for help with installing client addons.

Version History

• 1.0.0: Initial release

Addon Settings

LendingEnabled Determines whether lending requests are enabled for NCIP Integration.

BorrowingEnabled Determines whether borrowing requests are enabled for NCIP Integration.

ErrorQueueBorrowing

Defines the name of the queue to which borrowing transactions will be routed if there is an error in processing.

ErrorQueueLending

Defines the name of the queue to which lending transactions will be routed if there is an error in processing.

NCIPResponderURL

URL for the NCIP Server Responder.

ApplicationProfileType

The mapping for the NCIP ApplicationProfileType. This can be a tag or static value. If you would like a different library type for LibraryUseOnly, use “{Custom:ApplicationProfileType}.”

BorrowingUserIdentifier

The mapping for the NCIP user identifier sent for borrowing requests. This can be a tag or static value.

LendingUserIdentifier

The mapping for the NCIP user identifier sent for lending requests. This can be a tag or static value.

FromAgencyId

Generic From Agency ID string to use in NCIP calls

ToAgencyId

Generic To Agency ID string to use in NCIP calls

RequestIdentifierPrefix

Prefix for RequestIdentifier.

ItemBarcodeField

If Multiple Barcode support is enabled, this field will be used to store additional barcodes (beyond the first)

HistoryEntryAcceptItemSuccess

The history entry made when the AcceptItem NCIP call is completed successfully. Leave blank for no history entry.

HistoryEntryRequestItemSuccess

The history entry made when the RequestItem NCIP call is completed successfully. Leave blank for no history entry.

HistoryEntryCheckOutItemSuccess

The history entry made when the CheckOutItem NCIP call is completed successfully. Leave blank for no history entry.

HistoryEntryCheckInItemSuccess

The history entry made when the CheckInItem NCIP call is completed successfully. Leave blank for no history entry.

MultipleBarcodeDelimiter

The delimiter character that is used to separate multiple barcodes within a single field. for example, “1234,6875,5567” when delimited by a comma will be split into 3 values. Default is a space.

PickupLocationField

The mapping for the pickup location field. Default is NVTGC.

PickupLocationMappings

A comma-delimited list of mappings (i.e., a=b,c=d) which will be used when mapping to PickupLocations from a particular field.

General Notes

• The system addon works in conjunction with functionality that is performed in the ILLiad staff client. If a request is modified in an application other than the ILLiad staff client (such as Web Circ) the NCIP processing functionality will not be initiated. Each client that will be performing the Check in from lending library functionality, Check In from Customer and Document Delivery Mark Found functionality will need to have this addon or the NCIP processing functionality will not be initiated.

• Users must have a barcode defined in the SSN field of the User record. If the barcode is not set the NCIP calls will fail.

• A User’ NVTGC is mapped to an NCIP pickup location. The mapping is defined in the DataMapping.lua file. More information on the mapping can be found in the Pickup Location Mapping section below.

• The NCIP functionality will only work for ILLiad requests whose request type is set to Loan.

Borrowing Functionality

Borrowing functionality is split up into 2 separate pieces. The first happens when a request is checked in from the lending library. The second step happens when the user returns an item.

Step 1. Check in from lending library

The NCIP functionality will be initiated when using the Check In button on the Check In from Lending Library form. An NCIP call of AcceptItem will be processed that should create a temporary item for the patron that will be marked on hold. If an error occurs during either NCIP call the request will be routed to the ErrorQueue defined in the addon settings. The request will remain at Awaiting Post Receipt Processing if no errors were encountered. If there are any custom workflows for these requests, they should be handled using routing rules after continuing the processing of the item.

Process

1. In the client on the main form, navigate to the Borrowing ribbon and click on Check In From Lending Library.
2. Search for the request that is being checked in.
3. Click on Check In. The NCIP processing will happen after the standard ILLiad processing occurs.

Step 2. Check in from customer

The NCIP functionality will only be initiated when using the Borrowing Check In form. Please note that NCIP processing will not be initiated when using the Mark In Transit button, manually routing an item, or using Web Circulation to receive items from a patron. An NCIP call of CheckInItem will be made if the item barcode contains the RequestIdentifierPrefix setting indicating that the ILLiad request had previously created a temporary item. If an error occurs during the NCIP call the request will be routed to the ErrorQueue defined in the addon settings. The request will remain at Awaiting Return Label Printing if no errors were encountered.

Process

1. In the client on the main form, navigate to the Borrowing ribbon and click on Check In.
2. Find the requests to be checked in using the search or by entering the ILLiad TN or ILL number.
3. As soon as the check in process completes (either by enabling Auto Process or clicking Process Queue) the NCIP functionality will be initiated.

Multiple Barcode Functionality

For borrowing, Multiple barcodes in a single specified field (ItemBarcodeField) of a transaction can be split according to a specified delimiter character (MultipleBarcodeDelimiter) by enabling BorrowingMultipleBarcodeFields (enabled by default). Please note that the total number of expected barcodes within the field is anticipated to be one less than the piece count of the transaction and will not run if the parsed number of barcodes is not specifically equal to (number of pieces) - 1.

Lending Functionality

Lending functionality is split up into 2 separate pieces. The first happens when a request is marked as found. The second step happens when the request is marked as returned from the lending library.

Lending Check Out

The NCIP addon will validate that the number of pieces matches the barcodes entered into the ItemBarcodeField. Staff should scan each barcode into the ILLiad ItemBarcodeField, including for the first piece. If the number of barcodes does not match the total number of pieces for the item, the request will be routed to the ErrorQueueLending status. If validation is successful, an NCIP CheckOut message is sent for each barcode.

The lending check out will attempt to find a lender’s barcode in the NCIPBarcodes table. This table can be customized using the UChicago NCIP Configuration client addon. If a lender’s symbol is not found in the table, the FallbackAccount barcode is used for the NCIP check out.

Process

1. In the client on the main form, navigate to the Lending ribbon and click on Update Stacks Search.
2. Find the request to be processed.
3. Enter barcodes in the ItemBarcodes field. The Update Stacks Search form should be customized to ensure the ItemBarcodes field has been added.
4. Handle any other typical workflow at this step.
5. As soon as the mark found process completes the NCIP functionality will be initiated.

Lending Check In

The NCIP addon will validate that the number of pieces matches the barcodes entered into the ItemBarcodeField. If the number of barcodes does not match the total number of pieces for the item, the request will be routed to the ErrorQueueLending status. If validation is successful, an NCIP CheckIn message is sent for each barcode.

Process

1. In the client on the main form, navigate to the Lending ribbon and click on Lending Returns.
2. Find the request to be processed.
3. As soon as the return process completes (either by enabling Auto Process or clicking Process Queue) the NCIP functionality will be initiated.

DataMapping Customization

The DataMapping file allows for customization of settings that should rarely change. Examples are values for data that is sent via NCIP calls, the ILLiad fields that contain the item and user barcodes, and the text of the history entries made upon a successful NCIP call.

Pickup Location Mapping

An ILLiad NVTGC is mapped to NCIP pickup locations by entries that can be found in settings. The key is set to an ILLiad NVTGC. The value should be the NCIP pickup location. In the example, ILL ans SCI are ILLiad NVTGCs and Main Library ans Science Library are the NCIP pickup location.

Example

ILL=Main Library,SCI=Science Library

When processing a request for a user that has an NVTGC without a mapping for a pickup location, the request will be routed to the ErrorQueue.

Application Profile Types Conditionally set by LibraryUseOnly

There is an option to set the Application Profile type conditionally depending on whether the transaction is listed as “LibraryUseOnly”

Process

1. In DataMapping.lua, locate the code block marked “Library Use Only Conditional Mappings”
2. Replace the strings for true and false evaluations appropriately to evaluate to the proper setting

Example

In the below example, “ILL_LU” will return if the transaction is LibraryUseOnly and “ILL” will return otherwise.

DataMapping.Handlers.ApplicationProfileType = function ()
    if (GetFieldValue("Transaction", "LibraryUseOnly")==true) then
        return "ILL_LU";
    else
        return "ILL";
    end
end

1. in the app configuration, set the ApplicationProfileType to {Custom:ApplicationProfileType}.

Tagging

The DataMap file allows for tagged values. The tagging syntax will look for values inside of curly braces. i.e. { } and must match a specific format.

The TableField replacement will retrieve a value from an ILLiad table and field. The format is the TableName, followed by a period, followed by the FieldName. Transaction, User, and Lender are the only allowed table names for tag replacement. Setting is an alternate table name that can be used which will obtain the value of an addon setting.

Example: {TableField:Transaction.ReferenceNumber} would be replaced with the ReferenceNumber of the ILLiad request. {TableField:User.LastName} would be replaced with the LastName of the user associated with the ILLiad request. Example: {TableField:Setting.AgencyId} would be replaced with the AgencyId specified in the addon customization.