Jobs
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.
- This option will not appear if your library does not have the bill connector feature activated.
- To see the Jobs option, you must have the Circulation Admin, Circulation Desk, or Student Worker Circulation roles. See Circulation account roles for more information.
- Contact OCLC Library Services or your OCLC Library Services Consultant to learn more about enabling the WMS Patron System Bill Connector
Create and manage bill connector 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.
Job information and export processing modes
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.
Bill Criteria
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:
- Amount Outstanding: Choose the minimum amount that must be outstanding against a bill before it can be exported. By default, the system will export any bill with an amount outstanding greater than 0.00 (zero).
- Patron Type(s): Choose one or more patron types whose bills should be exported by the job. By default, the system will export bills for users with any patron type.
- Bill Reason(s): Choose one or more bill reasons to be exported by the job. By default, the system will export bills with any bill reason.
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.
Processing Modes
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:
Reconciliation
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.
- Example: Your library wants outstanding bills to continue to block patrons based on Patron Type Policy and/or your library wishes to accept payments through WMS.
Transfer
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.
- Example: Library staff do not need to accept payments from users. Patrons with an outstanding balance should be blocked manually by library staff and/or the campus system via the circulation block flag in the user record. See Block a patron.
Synchronization mode
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:
- NEW: The bill was created in WMS since the last time the synchronization job ran successfully. The first time a synchronization job runs, all bills have a NEW row type.
- UPDATED: The bill's outstanding amount has been updated in WMS via a partial payment or partial waiving of the bill. The bill still has an amount outstanding.
- UPDATED_RESOLVED: The bill has been fully resolved in WMS via a payment, waive, or cancellation. No amount outstanding remains.
- In the export file, the OUTSTANDING_AMOUNT value will be 0.00.
- If your library imports bill updates into WMS that fully resolves a bill (the bill's amount outstanding is now 0.00), then synchronization mode will export the bill one final time to confirm for the partner system that the bill is successfully resolved in WMS.
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.
- For example, if a synchronization job is configured to export bills for users with patron type Undergraduate, then bills previously exported by that job will continue to provide updates to your student accounts system even if a patron graduates and becomes an Alumni patron type. Bills that are created after the patron is assigned the Alumni type will not be exported by the job for undergraduate bills.
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.
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.
Schedule and monitor job executions
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 opening its Activity Log accordion. 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. Click on the execution ID to see more details about the export attempt.
Schedule a job
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.
- A job must be in Enabled status to run on schedule. Disabled jobs will remember their previous schedule but the process will not run automatically.
- Daily or Weekly schedules can be run at the time of your choice.
- The system will prevent your library from scheduling jobs with the same start time and will only allow one job to process at a time. Other scheduled jobs must wait until the current job has stopped running. This will avoid export conflicts if bill criteria overlap across multiple jobs.
Manually run a job
Users with the Circulation Admin or Circulation Desk roles may use the Run button 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.
Retrieve and use bill export files
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
- Ex. wms.ZZZZZ.out-circdata-fees.D20210609.T070019.students123.csv
Data included in the export file
The file header includes information about the job that created the file:
- FILE_FORMAT_VERSION: The export file format version. Current file format is version 1.1.
- JOB_NAME: The name of the job when the export process produced the file.
- JOB_EXECUTION_ID: The job reference ID when the export process produced the file.
- JOB_EXECUTION_DATETIME: The date and time when the export process ran.
- OUTSTANDING_AMOUNT: The minimum amount outstanding configured in the job's bill criteria when the export process produced the file.
- BILL_REASON: The bill reasons selected in the job's bill criteria when the export process produced the file. Repeatable for each selected bill reason.
- PATRON_TYPE: The patron types selected in the job's bill criteria when the export process produced the file. Repeatable for each selected patron type.
Each export file will include the following data elements for each bill:
- BILL_ID: A 36-character identifier assigned to each bill by WorldShare Circulation. Can be used as a unique bill identifier by the partner system.
- ROW_TYPE: Reserved for future use. Value will always be NEW for reconciliation and transfer exports.
- PATRON_ID: The circulation barcode of the user who owes money on a library bill.
- CHARGING_INSTITUTION: The WorldCat Registry ID of the institution that originally created the bill.
- 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. Use this field to identify the institution that originally charged the bill to ensure payment is transferred to the correct library.
- CURRENCY: The ISO currency code of the bill, e.g., CAD, EUR, GBP, and USD.
- ORIGINAL_AMOUNT: The numeric amount that was originally assessed by the library.
- OUTSTANDING_AMOUNT: The numeric amount that remains unpaid of the bill's original amount.
- BILLED_TITLE: The title of the item associated with the bill. May be null/empty.
- BILLED_ITEM: The barcode of the item associated with the bill. May be null/empty.
- ASSESSED_DATETIME: The date and time that a bill was originally created in WMS. Timezone information is provided, e.g., 2021-03-08T05:40:36-05:00
- LAST_MODIFIED_DATETIME: The date and time that a bill was last updated in WMS. Timezone information is provided, e.g., 2021-03-08T05:40:36-05:00
- BILL_REASON: Configured in the Bill Reasons section of the OCLC Service Configuration and indicates the reason why a patron is being billed.
- ACCOUNT_CODE: The account code as configured in the Bill Reasons section of the OCLC Service Configuration.
- TAX_CODE: The tax code as configured in the Bill Reasons section of the OCLC Service Configuration.
The file footer includes summary information about the bills in the file:
- FILE_BILL_COUNT: The number of bills included in the export files.
- SKIPPED_BILL_COUNT: The number of bills that failed to be exported by WMS. Please contact OCLC Support for assistance with skipped bills.
Import updates to bills paid in another system
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.
Monitor bill connector imports
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.
Deliver import files to OCLC
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.
- The filename should be unique and use the .csv extension.
- When delivering a bill connector import file to OCLC, the filename may include:
- Alphanumeric characters (A-Z, a-z, 0-9)
- Periods (dots), dashes, and underscores
- Do not include spaces or other non-alphanumeric characters in the filename, and do not begin filenames with periods, dashes, or underscores.
Caution: Files with invalid names will not be processed by the bill connector.
Import file format
Each import file must include the following data elements for each bill that you wish to update in WMS:
- BILL_ID: A 36-character identifier assigned to each bill by WorldShare Circulation. WMS bill IDs are provided in files exported by the bill connector.
- ROW_TYPE: Reserved for future use. The value must always be UPDATE in an import file.
- OUTSTANDING_AMOUNT: The numeric amount that remains unpaid of the bill's original amount.
- PAYMENT_METHOD: Describes how the bill was paid or otherwise reduced the bill's outstanding amount, e.g., Visa, Student Accounts, invoice 22-333-44a, Waived, etc.
- The payment method may be up to 30 characters and does not need to match your library's configured Payment Methods.
- Do not submit credit card or bank account details in the PAYMENT_METHOD field.
- LAST_MODIFIED_DATETIME: The date and time that a bill was last updated in a system outside of WMS. Timezone information must be provided, e.g., 2021-03-08T05:40:36-05:00
-
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.
Retry failed payment import files
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.
