When the WMS Patron System Bill Connector is enabled, navigate to Circulation > Scheduled Jobs > Jobs to create and manage your library's bill export jobs.
The WMS Patron System Bill Connector uses export jobs to find the bills that you want to share with another system and to set the frequency of bill exports.
From the Jobs screen, use the Create New Job button to configure a new job.
To monitor, update, or run an existing job, click on the job from the Name column.
Note: Users with the Circulation Admin or Circulation Desk roles are allowed to create and update bill connector jobs for your library. Users with the Student Worker Circulation role may view existing jobs and monitor job activity. See Circulation account roles for more information.
Configure one or more bill connector export jobs with different processing modes, bill criteria, and/or export schedules. Each subset of your library's bills may have its own export job with a unique Job Reference that will appear in the CSV filename for easy identification.
When creating a new job, set Bill Criteria to identify bills that should be exported when the job runs. You may adjust bill criteria at any time. Options include:
All bill criteria are honored when the job runs and selects bills for export.
Circulation groups: Export files are always limited to the bills owed by patrons of the exporting institution that can be paid by Group Payments Policy. Bills charged by other institutions in your group can be identified in the export file.
In some cases, it may be enough to provide bill details to other systems used by your institution. For example, it may be enough for the campus registrar to know which users owe the library money. In other cases, your library may want the campus system to fully manage bills raised by WMS. Three export Processing Modes are available to reflect the different scenarios:
Use reconciliation mode if your library wants to notify another system about the existence of a library bill. This mode provides a CSV file of all relevant bills. Bills are not updated by WMS during the export process.
Use transfer mode if your library wants to transfer responsibility for bill payments to another system. This mode provides a CSV file of all relevant bills and marks all of the exported bills as paid in WMS using the Payment Method of your choice.
Bills paid via a transfer job will move to the patron's Account History and will no longer appear to the user in My Account or on a self-check machine. Bills will no longer be counted towards the patron's bill limits. See Patron Type Policy.
Use synchronization mode if your library wants to frequently notify another system about new bills or updates to bills that that system is already tracking. This mode is recommended if the campus or debt collection system will be providing bill updates to WMS via import file. Synchronization mode provides a CSV file of all relevant bills that have been created or updated in WorldShare Circulation since the last time the job ran successfully. Bills are not updated by WMS during the export process.
Synchronization jobs can be scheduled to provide export files more frequently than reconciliation or transfer jobs. You can choose to schedule synchronization exports for an hourly, daily, or weekly cadence. You may also choose to run the job manually, as needed.
The first time a synchronization export runs, all existing bills that match the job's criteria are exported. In all subsequent export files, only new bills, updated, or previously exported bills will be included. The ROW_TYPE value in synchronization files will indicate the state of the bill:
Bill criteria are used to select bills for export from your library's existing bills the first time a synchronization job runs. New bills will also be selected for subsequent job executions only if the bill meets the bill criteria of the job. However, subsequent updates to previously exported bills will continue to be exported until the bill is fully resolved, regardless of the bill criteria originally used to select the bill for export.
To ensure exports consistently provide details about previously exported bills, you will not be allowed to update the bill criteria of a synchronization job over time. If you wish to synchronize bills using different billing criteria, you may create a new job for the new criteria and, if needed, disable the original job.
# FILE_FORMAT_VERSION=1.1 # JOB_NAME=Example Sync Job # JOB_EXECUTION_ID=3694359069333377 # JOB_EXECUTION_DATETIME=2021-08-25T17:04-0400 # OUTSTANDING_AMOUNT=5.00 # PATRON_TYPE=Graduate # PATRON_TYPE=Undergraduate BILL_ID,ROW_TYPE,PATRON_ID,CHARGING_INSTITUTION,CURRENCY,ORIGINAL_AMOUNT,OUTSTANDING_AMOUNT,BILLED_TITLE,BILLED_ITEM,ASSESSED_DATETIME,LAST_MODIFIED_DATETIME,BILL_REASON,ACCOUNT_CODE,TAX_CODE "e05fdbe7-5a11-4001-9d81-093d23187e91",NEW,user1,91475,USD,10.55,10.55,,,"2021-08-25T16:41:40-04:00","2021-08-25T16:41:40-04:00","Overdue",LIBOVD,"VAT Exempt" "15bfef42-28ae-4ac2-9ad8-9306a02b8249",UPDATED,user2,91475,USD,25.00,10.00,,,"2021-08-05T16:41:19-04:00","2021-08-25T17:04:51-04:00","Lost library card","Admin Other", "4a28c8a8-7c4b-4fe5-84c3-79b316fc6c01",UPDATED_RESOLVED,user3,91475,USD,200.00,0.00,,,"2021-07-22T08:30:01-04:00","2021-08-25T17:04:51-04:00","Replacement Cost",LIBREP, # FILE_BILL_COUNT=3 # SKIPPED_BILL_COUNT=0
Caution: Bill connector files include sensitive personal and financial data. We advise you to consult with your local IT department when deciding how to download, transfer, and store this data on your local or institution-managed systems.
Staff users with the Circulation Admin, Circulation Desk, or Student Worker Circulation roles may monitor job executions to ensure that files are being exported as expected. See Circulation account roles for more information.
Review each job via Circulation > Scheduled Jobs > Job to find information about the date and time that a job is next scheduled to run, the date and time that a job last ran, and the status of the last attempt.
View more information about each job execution of a specific job by using the drop-down next to the Job Name to reveal the Job Information and Activity Log tabs. Each attempt to run the job will include its execution ID, execution date and time, status, and a summary of the export including the number of bills exported in the Activity Log.
Schedule a job
From the Job information tab, click the Edit button. Use the Schedule option to choose when and how often an export file will be generated by WMS. You may choose to export files daily, weekly, or not to use the scheduling function and run a job on an ad-hoc basis.
Users with the Circulation Admin or Circulation Desk roles may use the Run option under the Actions column to manually run an Enabled job, regardless of its schedule. The Run option will not appear if the job is currently Disabled.
The ad-hoc Run option is useful if you prefer not to run a job on a predetermined schedule and only need to export billing data a few times per year, or for testing the integration.
Bill connector export files are placed in your OCLC file exchange account as CSV files that can be downloaded, transformed, and imported into other software as needed. Export files are retained for 30 days. Files older than 30 days are subject to deletion.
Caution: Bill connector files include sensitive personal and financial data. We advise you to consult with your local IT department when deciding how to download, transfer, and store this data on your local or institution-managed systems.
Bill export files can be found under the /xfer/wms/out/circdata/fees file exchange directory and can be downloaded using an open-source SFTP client or your local IT support's preferred method. See Download files using an open-source SFTP client for more information.
Filenames are built as follows: wms.myLibrarySymbol.out-circdata-fees.exportDateTime.jobReferenceId.csv
# FILE_FORMAT_VERSION=1.1 # JOB_NAME=Transfer SAP FI # JOB_EXECUTION_ID=35184372212636 # JOB_EXECUTION_DATETIME=2021-09-10T07:30-0400 # OUTSTANDING_AMOUNT=20.00 # PATRON_TYPE=Undergraduate BILL_ID,ROW_TYPE,PATRON_ID,CHARGING_INSTITUTION,CURRENCY,ORIGINAL_AMOUNT,OUTSTANDING_AMOUNT,BILLED_TITLE,BILLED_ITEM,ASSESSED_DATETIME,LAST_MODIFIED_DATETIME,BILL_REASON,ACCOUNT_CODE,TAX_CODE "39e2beb1-5b2e-4100-9b83-cfad2baa8cc2",NEW,user1,91475,USD,25.00,25.00,,,"2021-09-09T16:36:20-04:00","2021-09-09T16:36:20-04:00","Lost library card",LIBCAR,VAT0 "dcac0bd7-4311-45fa-8f8e-dd81f3985f8b",NEW,user2,91475,USD,45.99,45.99,"British children's writers since 1960.",30717000366255,"2021-09-09T16:37:33-04:00","2021-09-09T16:37:33-04:00","Replacement Cost",LIBREP,VAT0 "05ec3a2f-eb81-4a04-b2fd-a8c1ce5021d3",NEW,user2,91475,USD,34.50,34.50,"Buffalo Bill's America : William Cody and the Wild West Show /",573918992,"2021-09-09T16:37:04-04:00","2021-09-09T16:37:04-04:00","Replacement Cost",LIBREP,VAT0 # FILE_BILL_COUNT=3 # SKIPPED_BILL_COUNT=0
The file header includes information about the job that created the file:
Each export file will include the following data elements for each bill:
The file footer includes summary information about the bills in the file:
The WMS Patron System Bill Connector allows your library to import information about payments that have occurred outside of WMS. Deliver CSV files to your OCLC file exchange account to notify WMS of a bill's new amount outstanding after a partial or complete payment has occurred in your other billing systems, such as your campus bursar system.
The bill connector will pay down the bills in WorldShare Circulation using the payment method specified in your CSV file and will unblock a patron's account caused by any bill limit set in Patron Type Policy and will update the patron's fees data in My Account. Payments processed by the bill connector will be visible to you in the patron's Bills tab in WorldShare Circulation and will be reflected the next day in your reporting data in WorldShare Reports and Report Designer.
Navigate to Circulation > Scheduled Jobs > Jobs > Imports to monitor incoming import files.
Note: Any user with the Circulation Admin, Circulation Desk, or Student Worker Circulation roles may monitor imports to ensure that files are being received and processed as expected.
Find the date and time that a file was imported, the current status of the import execution, and a summary of the bill updates that were imported or skipped. To see more details about the import and any skipped bills, click on the Job Execution ID value.
Import files should be delivered to the /xfer/wms/in/circdata/payments file exchange directory. You can deliver files using an open-source SFTP client or your local IT support's preferred method.
Note: Import files are limited to 10,000 bill updates per file.
Caution: Files with invalid names will not be processed by the bill connector.
Each import file must include the following data elements for each bill that you wish to update in WMS:
WMS will use the provided date and time to verify if the file contains the most recent update to a bill's outstanding amount. If the data provided is not the most recent change, then the update will be skipped by WMS. We recommend delivering bill updates as frequently as possible to WMS with accurate last-modified date information to avoid bills being skipped during import file processing, partial payments being applied in the wrong order, and to reduce the chances of a patron accidentally over-paying a bill, especially if your library will accept payments in WMS and another system.
Each file must also indicate the FILE_FORMAT_VERSION in the header. Currently, the only supported version is 1.0.
The file footer may include the optional FILE_BILL_COUNT element to indicate how many bill updates have been submitted for processing.
# FILE_FORMAT_VERSION=1.0 BILL_ID,ROW_TYPE,OUTSTANDING_AMOUNT,PAYMENT_METHOD,LAST_MODIFIED_DATETIME "2d2ca0a6-bec8-4497-97e9-9d45c226b6b7",UPDATE,70.00,"Check","2021-09-05T10:32:57-04:00" "96888eda-ca32-4ed3-90eb-824baedb348a",UPDATE,56.78,"Credit Card - Visa",2021-009-05T04:03:30-04:00" # FILE_BILL_COUNT=2
An import file may fail to process or to process completely if the file is delivered while WorldShare Circulation is undergoing system maintenance or a system error occurs during processing. Only bill updates that failed to process in previous attempts will be retried.
Eligible import executions will display a Retry Import button to users with the Circulation Admin or Circulation Desk roles. The retry option will be available up to 21 days after an import file is delivered to OCLC.
Retrying the file will create a new import attempt with a new execution ID. Click the link to verify if the retry successfully updates the patron bills.