Skip to main content
OCLC Support

Integrate invoice information with your financial system by implementing the WMS Accounting System Invoice Connector

Discover how to implement to the Accounting System Invoice Connector to synchronize invoice information between WorldShare Acquisitions and your financial system by exporting and importing a single invoice file.

Overview

You can integrate invoice information from WMS to your financial system by exporting a single file of invoices that are ready for payment to an OCLC file exchange server. This file includes all required data for integration with a financial system, including:

  • Invoice data
  • Order data
  • Order item data
  • Resource data
  • Vendor data

This single file of invoices can then be retrieved using your OCLC file exchange account, transformed into the necessary format, and imported into your financial system.

Once you have retrieved the exported file and transferred its contents to your financial system, you can also provide a file of payment information back to an OCLC file exchange server. This payment information can include not only the specific invoices that you want to mark as paid but updates to specific fields on the invoice.

 Note: There is a minimal one-time implementation fee to turn on this service. Please contact OCLC Support to purchase this service for your institution.

Important notes about the invoice connector

 Caution: Please carefully review the below points when gathering information and deciding if the Invoice connector is right for your institution.

  • Your institution will need access to the OCLC SFTP account. For more information, refer to Download files using an open-source SFTP client.
  • Your institution will need to write a procedure to pick up the invoice files from the OCLC SFTP server.
  • The invoice export file is output as a JSON file. It may need to be reformatted to suit the needs of your financial system.

     Note: Financial systems may require CSV, XML, tab-delimited or another file type. 

  • The file name of the invoice output file cannot be specified by the institution, as it is a standard file name generated by OCLC.
  • The files will remain in place until the OCLC file deletion process removes them. This process is 90 days and is determined by the DEAP team.
  • There can only be one invoice file export job and it can not run automatically more than once per day. Unless the job has been run manually, there should only be a max of one file per day.
  • A file is not generated if no invoices are output. However, an email notification will be sent every day indicating if any invoices have been exported.
  • The only invoices included in the export file are those which are flagged as Ready to Pay. If you don't want an invoice to be exported, use the Pay option on the invoice record in WMS.
  • A paid response file will need to be generated and posted back to the OCLC SFTP server.
  • It is recommended that you thoroughly test the Invoice connector integration with test data and a test budget before using it in production, including manually running the invoice export job that you know when a file is going to be generated.

Integrate the WMS Accounting System Invoice Connector

1. Configure vendor information

Some vendor fields are included as a part of the invoice export jobs. The fields are available in a vendor's profile in WMS under the local identifiers accordian. For more information, see Edit a vendor. The following vendor fields are included in the export file and may need to be entered prior to using the invoice export:

  • Accountancy System ID
  • GST Registration Number
  • PST Registration Number

2. Configure invoice export job

In order to enable export of invoice data to an OCLC file exchange server, you must first configure an invoice export automated job. You can only create one invoice export job for your institution.

  1. On the left navigation, click Automated Jobs > Jobs to open the Jobs screen.
  2. Click New Job to open the New Job dialog.
  3. In the New Job dialog:
    1. Enter a name for the job in the Name text field.
    2. Select Invoice Export from the Type drop-down list.
    3. Click Save. The Invoice export job screen opens.
  4. From the Invoice export screen:
    1. Select an Invoice Status setting.
      • Awaiting Payment - Sets any Ready for Payment invoice(s) to Awaiting Payment upon export. This ensures that invoices are not exported twice, while also indicating that invoices need to be paid. Invoices will not be marked as Paid until you upload a payment import file. This will then trigger the marking of invoices as paid. This allows you to only mark invoices as paid either once they have been transferred to the financial system or when payment has been transmitted by the financial system.
      • Paid - Immediately marks the invoices as Paid upon export. This is for use by those institutions that do not want to import a file of paid invoices back to WMS. This method assumes that all invoices exported will be transferred to the accounting system, and that any problems with this process will be handled manually by staff via unpaying the invoice and then marking them as Ready for Payment again in order for them to be re-exported.
    2. Select the how often you want to export invoice data from the Schedule drop-down list.
      • Inactive - Job is not currently in use and will not be run until activated.
      • Daily - Specify the job to run daily at a specific time. Enter the time in hh:mm format (e.g., 05:00 PM).
      • Weekly - Specify a time and day of the week for the job to run. Select a day to run the job from the drop-down list and enter the time in hh:mm format (e.g., 05:00 PM).
      • Monthly - Specify a time and day of the month for the job to run. Select a day of the month to run the job from the drop-down list and enter the time in hh:mm format (e.g., 05:00 PM).
      • Manual only - Manually run this job at times you choose by clicking Run on the Invoice export job screen.
    3. Enter the name of the user you want to be notified when the system exports invoices and when the system imports payment files from the Notify text field. 

       Note: This is an auto-suggest text field. Auto-suggestions for field-appropriate elements start with the first keystroke in the text field.  Auto-suggestions include an email address for the user which is pulled from Delivery Notification of the WorldShare Admin module. If no email exists in the Delivery Notification section, the Library Record email address will be used.

  5. Click Save.

3. Mark invoices to be exported as Ready for Payment

After you configure the invoice export job, all invoices marked as Ready for Payment will be exported to an OCLC file exchange server according to your predefined schedule. You can mark invoices as Ready for Payment to ensure invoices are exported.

Changing an invoice's status to Ready prevents editing it. The Ready status is often used to mean the invoice is ready to be imported into a separate financial system used by the library.  

  1. From the left navigation, click Invoices > Invoices.
  2. Search for an open invoice. To find an invoice, see Search and filter invoices or Search and filter invoice items.
  3. From the search results, click the Invoice Number.
  4. Click Mark as Ready at the top of the screen to change the invoice status to Ready.
  5. (Optional) Click Reopen invoice at the top of the screen to change the invoice status back to Open.

When the invoice export job runs, it will pick up all Marked as Ready invoices and export a file of this invoice data to an OCLC file exchange server. Simultaneously, it will mark the invoices as Awaiting Payment or Paid based on your Invoice Status setting.

4. Process the invoice file(s)

a. Retrieve the exported file(s) from your OCLC file exchange account

Once invoices have been exported to an OCLC file exchange server, you will need to retrieve the files using your OCLC file exchange account.

JSON invoice export file - Sample
{
  "invoices": [
    {
      "invoiceNumber": "INV-2020-44",
      "vendorInvoiceNumber": "InvoiceNumberDemo2",
      "vendor": {
        "name": "Actrace",
        "id": "671f85e1-2efe-4715-ab20-c942e18aef3a"
      },
      "dateCreated": "2020-04-09T14:16:55",
      "note": "Notes for invoice 2.",
      "institutionInvoiceTotal": {
        "amount": 325.4,
        "currency": "USD"
      },
      "vendorInvoiceTotal": {
        "amount": 297.97,
        "currency": "EUR"
      },
      "invoiceItems": [
        {
          "invoiceItemNumber": "INV-2020-44-1",
          "resource": {
            "oclcNumber": "57333009",
            "title": "Time",
            "resourceType": "WORLDCAT",
            "materialTypeCode": "Book_Digital"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-2",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "f81bf6d3-9772-42d9-91dd-06a677e55bbd"
          },
          "transactionType": "DEBIT",
          "quantity": 1,
          "id": "a40fe091-959a-4283-b4b5-89ab102a36ef",
          "transactionTypeDetail": "DEBIT",
          "invoicingPercentage": 100,
          "funds": [
            {
              "percentage": 100,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 2",
              "fundCode": "tfbcid2",
              "fundNumber": "BP-2014-256-73",
              "amount": {
                "amount": 106.99,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 85.37,
            "currency": "EUR"
          },
          "discountPercentage": 0,
          "discountTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax1Percentage": 9.755,
          "tax1Total": {
            "amount": 8.3278,
            "currency": "EUR"
          },
          "tax2Percentage": 5,
          "tax2Total": {
            "amount": 4.2685,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 12.5963,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 97.97,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 0,
            "currency": "EUR"
          },
          "total": {
            "amount": 97.97,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        },
        {
          "invoiceItemNumber": "INV-2020-44-4",
          "resource": {
            "localResourceID": "b38f1745-f7ca-44fc-a806-f39e4b29d91b",
            "title": "Test Local Resource 2020-04-09",
            "resourceType": "LOCAL",
            "materialTypeCode": "otr"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-6",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "e7bcaea0-ff13-4bc1-abf3-bfe905af2ff6"
          },
          "transactionType": "DEBIT",
          "quantity": 1,
          "id": "0a9e2cb1-1142-40fb-9354-40f7978f5a48",
          "transactionTypeDetail": "DEBIT",
          "invoicingPercentage": 100,
          "funds": [
            {
              "percentage": 29.7,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 2",
              "fundCode": "tfbcid2",
              "fundNumber": "BP-2014-256-73",
              "amount": {
                "amount": 64.87,
                "currency": "USD"
              }
            },
            {
              "percentage": 38.18,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 1",
              "fundCode": "tfbcid1",
              "fundNumber": "BP-2014-256-72",
              "amount": {
                "amount": 83.39,
                "currency": "USD"
              }
            },
            {
              "percentage": 32.12,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 3",
              "fundCode": "tbbcid3",
              "fundNumber": "BP-2014-256-74",
              "amount": {
                "amount": 70.15,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 117.85,
            "currency": "EUR"
          },
          "discountPercentage": 0,
          "discountTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax1Percentage": 9.755,
          "tax1Total": {
            "amount": 11.4963,
            "currency": "EUR"
          },
          "tax2Percentage": 5,
          "tax2Total": {
            "amount": 5.8925,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 17.3888,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 135.24,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 64.76,
            "currency": "EUR"
          },
          "total": {
            "amount": 200,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        }
      ],
      "id": "777a337d-d5e7-4b67-a51d-8c9754e48516",
      "registryId": 91475,
      "invoiceDate": "2020-04-09",
      "taxHandling": "EXCLUDE_ADDITIONAL_COSTS",
      "invoiceCurrency": "EUR",
      "exchangeRate": {
        "foreignCurrency": "EUR",
        "homeCurrency": "USD",
        "rate": 1.092058
      },
      "discountTotal": {
        "amount": 0,
        "currency": "EUR"
      },
      "taxTotal": {
        "amount": 29.99,
        "currency": "EUR"
      },
      "serviceChargesTotal": {
        "amount": 0,
        "currency": "EUR"
      },
      "shippingTotal": {
        "amount": 0,
        "currency": "EUR"
      }
    },
    {
      "invoiceNumber": "INV-2020-43",
      "vendorInvoiceNumber": "InvoiceNumberDemo1",
      "vendor": {
        "name": "Actrace",
        "id": "671f85e1-2efe-4715-ab20-c942e18aef3a"
      },
      "dateCreated": "2020-04-09T14:13:18",
      "note": "Notes for invoice.",
      "institutionInvoiceTotal": {
        "amount": 496.73,
        "currency": "USD"
      },
      "vendorInvoiceTotal": {
        "amount": 496.73,
        "currency": "EUR"
      },
      "invoiceItems": [
        {
          "invoiceItemNumber": "INV-2020-43-1",
          "resource": {
            "oclcNumber": "20723999",
            "title": "Bear",
            "resourceType": "WORLDCAT",
            "materialTypeCode": "Book"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-1",
            "vendorOrderItemNumber": "VendorOrderItemNumber123456",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "32ab5474-e8f7-4575-b7ea-93f8d81d2605"
          },
          "transactionType": "DEBIT",
          "quantity": 1,
          "id": "39f62d8d-6a8f-4d36-a97b-3734c02e747e",
          "transactionTypeDetail": "DEBIT",
          "invoicingPercentage": 100,
          "funds": [
            {
              "percentage": 100,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 1",
              "fundCode": "tfbcid1",
              "fundNumber": "BP-2014-256-72",
              "amount": {
                "amount": 84.12,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 78.56,
            "currency": "EUR"
          },
          "discountPercentage": 10,
          "discountTotal": {
            "amount": 7.86,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 2.99,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 2.99,
            "currency": "EUR"
          },
          "tax1Percentage": 9.755,
          "tax1Total": {
            "amount": 6.8968,
            "currency": "EUR"
          },
          "tax2Percentage": 5,
          "tax2Total": {
            "amount": 3.535,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 10.4318,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 84.12,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 0,
            "currency": "EUR"
          },
          "total": {
            "amount": 84.12,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        },
        {
          "invoiceItemNumber": "INV-2020-43-2",
          "resource": {
            "oclcNumber": "62493393",
            "title": "Hattie Big Sky",
            "resourceType": "WORLDCAT",
            "materialTypeCode": "Book"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-3",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "52aa20a6-1cbf-47bb-9a34-b6092bab214c"
          },
          "transactionType": "DEBIT",
          "quantity": 2,
          "id": "08927bb0-3757-487d-a9db-2476b82e7079",
          "transactionTypeDetail": "DEBIT",
          "invoicingPercentage": 100,
          "funds": [
            {
              "percentage": 50,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 1",
              "fundCode": "tfbcid1",
              "fundNumber": "BP-2014-256-72",
              "amount": {
                "amount": 129.99,
                "currency": "USD"
              }
            },
            {
              "percentage": 50,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 2",
              "fundCode": "tfbcid2",
              "fundNumber": "BP-2014-256-73",
              "amount": {
                "amount": 129.99,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 129.99,
            "currency": "EUR"
          },
          "discountPercentage": 0,
          "discountTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax1Percentage": 0,
          "tax1Total": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax2Percentage": 0,
          "tax2Total": {
            "amount": 0,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 259.98,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 0,
            "currency": "EUR"
          },
          "total": {
            "amount": 259.98,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        },
        {
          "invoiceItemNumber": "INV-2020-43-3",
          "resource": {
            "kbCollectionID": "EBSCOhost.27h",
            "title": "Abstracts In Social Gerontology",
            "resourceType": "KBWC_COLLECTION",
            "materialTypeCode": "Book_Continuing"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-5",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "453b22e7-f3b2-4a91-acf3-9b2b9b23a0b0"
          },
          "transactionType": "DEBIT",
          "quantity": 1,
          "id": "926e2085-f15a-4f6f-9bc3-c41db08b3e20",
          "transactionTypeDetail": "DEBIT_PARTIAL",
          "invoicingPercentage": 50,
          "funds": [
            {
              "percentage": 100,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 2",
              "fundCode": "tfbcid2",
              "fundNumber": "BP-2014-256-73",
              "amount": {
                "amount": 53.84,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 49.39,
            "currency": "EUR"
          },
          "discountPercentage": 5,
          "discountTotal": {
            "amount": 2.47,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax1Percentage": 9.755,
          "tax1Total": {
            "amount": 4.577,
            "currency": "EUR"
          },
          "tax2Percentage": 5,
          "tax2Total": {
            "amount": 2.346,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 6.923,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 53.84,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 0,
            "currency": "EUR"
          },
          "total": {
            "amount": 53.84,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        },
        {
          "invoiceItemNumber": "INV-2020-43-4",
          "resource": {
            "kbTitleID": "safari.tech 14283359",
            "title": "100 Great Branding Ideas",
            "resourceType": "KBWC_ENTRY",
            "materialTypeCode": "Book_Digital"
          },
          "orderItem": {
            "orderItemNumber": "PO-2020-18499-4",
            "order": {
              "orderNumber": "PO-2020-18499",
              "externalOrderId": "ExternalOrderID1234",
              "id": "ec3a3c52-d54f-4850-b009-fef4e9c34ede"
            },
            "id": "c63329d9-ce71-4bc1-85cf-ca5365fb09ba"
          },
          "transactionType": "DEBIT",
          "quantity": 1,
          "id": "7b9902d0-c97b-4610-9e5b-6d56f44a578e",
          "transactionTypeDetail": "DEBIT_PARTIAL",
          "invoicingPercentage": 0,
          "funds": [
            {
              "percentage": 100,
              "budgetPeriod": {
                "id": "fcbfae01-e313-4e3f-ac83-4103f7c594d5",
                "budgetPeriodNumber": "BP-2014-256"
              },
              "fundName": "Test Fund BCI Demo 1",
              "fundCode": "tfbcid1",
              "fundNumber": "BP-2014-256-72",
              "amount": {
                "amount": 98.79,
                "currency": "USD"
              }
            }
          ],
          "unitPrice": {
            "amount": 98.79,
            "currency": "EUR"
          },
          "discountPercentage": 0,
          "discountTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "serviceChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingCharge": {
            "amount": 0,
            "currency": "EUR"
          },
          "shippingChargeTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax1Percentage": 0,
          "tax1Total": {
            "amount": 0,
            "currency": "EUR"
          },
          "tax2Percentage": 0,
          "tax2Total": {
            "amount": 0,
            "currency": "EUR"
          },
          "taxTotal": {
            "amount": 0,
            "currency": "EUR"
          },
          "calculatedTotal": {
            "amount": 98.79,
            "currency": "EUR"
          },
          "adjustmentAmount": {
            "amount": 0,
            "currency": "EUR"
          },
          "total": {
            "amount": 98.79,
            "currency": "EUR"
          },
          "customFields": [
            {
              "@type": "NumberField",
              "label": "CF_I_Number_4_Dig",
              "description": "nummer 4 dez",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-1",
              "decimalPlaces": 4
            },
            {
              "@type": "TextField",
              "label": "CF_I_Text",
              "description": "text",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-2"
            },
            {
              "@type": "DateField",
              "label": "CF_I_Date",
              "description": "date",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-3"
            },
            {
              "@type": "MultiSelectField",
              "label": "CF_I_M-List",
              "description": "multi selectl list",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-4",
              "value": []
            },
            {
              "@type": "SelectField",
              "label": "CF_I_S-List",
              "description": "single selectl list1",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-5"
            },
            {
              "@type": "TextField",
              "label": "Lederhose",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-6"
            },
            {
              "@type": "NumberField",
              "label": "Filter Helen Invoice Item Number-1 EN ",
              "description": "Number - 1 decimal places",
              "fieldDefinitionNumber": "CF-INVOICE_ITEM-13",
              "decimalPlaces": 1
            }
          ]
        }
      ],
      "id": "dc12e3c2-038d-4999-a08d-b41e38d8b4dc",
      "registryId": 91475,
      "invoiceDate": "2020-04-09",
      "taxHandling": "EXCLUDE_ADDITIONAL_COSTS",
      "invoiceCurrency": "EUR",
      "exchangeRate": {
        "foreignCurrency": "EUR",
        "homeCurrency": "USD",
        "rate": 1
      },
      "discountTotal": {
        "amount": 10.33,
        "currency": "EUR"
      },
      "taxTotal": {
        "amount": 17.35,
        "currency": "EUR"
      },
      "serviceChargesTotal": {
        "amount": 0,
        "currency": "EUR"
      },
      "shippingTotal": {
        "amount": 2.99,
        "currency": "EUR"
      }
    }
  ]
}

Sample JSON invoice export files are also available on the OCLC Developer Network.

Retrieve manually using FTP client
  1. Sign in to OCLC file exchange using an open source SFTP client or using SFTP commands.
    Steps 2-4 - Image

    Retrieve exported file from OCLC SFTP server

  2. Navigate to the root directory.
  3. Click the xfer directory.
  4. Navigate to wms > out > acq > invoices. A list of all files exported in the last 90 days will display. File names are structured as follows: [OCLC symbol].out-acq-invoices.D[Date].T[Time]
  5. Right-click the invoice export file you want to retrieve and click Download from the context menu.
Retrieve automatically using code

It is possible to write a simple program to retrieve the exported files automatically. The program must be able to:

  1. Parse the names of the export files and extract the most recent date/time from the file name. File names are structured as follows: [OCLC symbol].out-acq-invoices.D[Date].T[Time].
  2. Download only the file(s) with names that include a date/time stamp that is more recent than the last extracted date.

 Note: 

  • The files on the OCLC SFTP server cannot be renamed or deleted, so it is important to keep track of your most recently downloaded file.
  • It is recommended that you run the invoice export job manually when testing, so that you know when a file is going to be generated. 

b. Transform the export file to the required data format

Once you have retrieved the export file, you can transform it to the required data format and import into your financial system. The file contains data from:

  • Invoices
  • Invoice items
  • Orders
  • Order items
  • Resource (e.g. WorldCat record)
  • Vendor

For examples and more information, refer to Financial System Integration on the OCLC Developer Network.

The general steps needed to transform the file are:

  1. Identify the file type needed by your financial institution, if it is not JSON. It could be CSV, XML, tab-delimited or another file type.
  2. Identify the fields needed by your financial system.
  3. Identify source fields in the WMS file that will need to be inserted into the new file that will be passed to the financial system.
  4. Transform the data in the WMS JSON file into the format required by your financial system. You will need to parse the JSON file, take out the required field values, and enter them into the new file in the required format. As a part of this process, you will need to map the vendor IDs and fund codes in the WMS file to the financial system.

     Note:

  • If the format required by your financial system does not have a hierarchical structure similar to the JSON file, you will need to repeat certain data elements in multiple rows.
  • Some fields needed by the financial system may need to be calculated or composed from multiple fields in the source file.
  • Fund and vendor mapping must be stored in the code, unless the fund code in WMS is the same as in the financial system, since there is no financial system ID field in the fund record in WMS.
  • There can be multiple WMS fund codes mapped to the same financial system fund ID.
  • There is a field in the vendor record that can be used to retrieve the ID used for the vendor by the financial system rather than storing the mapping yourself. This is known as the Accountancy System ID and is supplied in the resulting invoice file posted to the OCLC FTP server.

c. (Optional) Update and upload the payment import file

 Note: The easiest way to construct a payment file is to modify the existing JSON file exported by WMS.

If you selected the Invoice Status setting of Awaiting Payment for your invoice export job, then the invoices will be marked as Awaiting Payment upon export. In order to mark these invoices as paid, you will need to upload a payment import file using OCLC file exchange. The payment import file communicates which invoices need to be marked as paid.

The schema for the payment import file and the invoice export file are largely the same, so one strategy for creating a payment import file is to modify the invoice export file and upload it. You can modify the following fields:

  • Date Paid (paymentDate) - This field is now editable and can be different from the date on which the system changed the status to paid.
  • Payment Reference ID (paymentReferenceID) - This is a new field and represents the check or payment transaction number used for the actual payment transmitted to the vendor.
  • External Invoice ID (externalInvoiceId) - This is a new field and contains a unique invoice ID used by a system external to WMS (e.g. the financial system), if different from the invoice ID used by WMS.
  • Invoice Item Total (invoiceItems.total.amount) - This allows you to over-write the total of the invoice item to the exact total used in the financial system for the item. This will override the calculated total used in the system for the item.
JSON invoice payment import file - Sample
{
  "invoices": [
    {
      "externalInvoiceId": "ExternalInvoiceID2",
      "paymentReferenceId": "PaymentReferenceID2",
      "paymentDate" : "2020-04-12",
      "invoiceNumber": "INV-2020-44",
      "invoiceItems": [
        {
          "invoiceItemNumber": "INV-2020-44-1",
          "total": {
            "amount": 102.00,
            "currency": "EUR"
          }
        },
        {
          "invoiceItemNumber": "INV-2020-44-4"
        }
      ],
      "id": "777a337d-d5e7-4b67-a51d-8c9754e48516",
      "exchangeRate": {
        "foreignCurrency": "EUR",
        "homeCurrency": "USD",
        "rate": 1.09206
      }
    },
    {
      "externalInvoiceId": "ExternalInvoiceID1",
      "paymentReferenceId": "PaymentReferenceID1",
      "paymentDate" : "2020-04-14",
      "invoiceItems": [
        {
          "invoiceItemNumber": "INV-2020-43-1"
        },
        {
          "invoiceItemNumber": "INV-2020-43-2"
        },
        {
          "invoiceItemNumber": "INV-2020-43-3",
          "total": {
            "amount": 53.89,
            "currency": "EUR"
          }
        },
        {
          "invoiceItemNumber": "INV-2020-43-4"
        }
      ],
      "id": "dc12e3c2-038d-4999-a08d-b41e38d8b4dc",
      "exchangeRate": {
        "foreignCurrency": "EUR",
        "homeCurrency": "USD",
        "rate": 1.5
      }
      }
  ]
}

Before uploading the payment import file to an OCLC file exchange server:

  • Remove any invoices that were not successfully imported into the financial system from the JSON export file.
  • Adjust totals in the invoice item if they were adjusted before or after importing into the financial system.

To upload a payment import file:

  1. Sign in to OCLC file exchange using an open source SFTP client or using SFTP commands.
    Steps 2-4 - Image

    Upload payment import file to OCLC SFTP server

  2. Navigate to the root directory.
  3. Click the xfer directory.
  4. Navigate to wms > in > acq > payment. OCLC file exchange will pick up the file and pass it on to WorldShare Acquisitions for processing. When this happens, which should be almost immediately, the file will disappear from the payments folder upon refresh.

 Note: The instructions provided above detail how to post the payment file manually. You can also write a simple program in code to do this process automatically.

5. (Optional) Monitor the notifications for the export and import processes

You can view the status of invoice export activities and payment import activities with the invoice export job activity log.

  1. On the left navigation, click Automated Jobs > Jobs.
  2. Select Invoice Export from the Type filter and click Apply.
  3. Click the Name of the job to view the Invoice export job screen.
  4. From the Invoice export job screen, click Activity Log to open the accordion.
  5. (Optional) Click View Details in the Status column to open the Logging Details dialog, which provides additional details about the activity process.

Available Activity Log and Logging Details columns

Activity Log and Logging Details columns - Table
Column Description
Date The date and time the file was processed.
Type The type of file that was processed (Invoice Payment Import or Invoice Export).
Result The result of the file that was processed (e.g., 2 of 2 ready invoices exported).
Details Additional details about the file that was processed (e.g., REQUEST_ID: B3N-GEDK-G99).
Status Icon associated with the severity of the file that was processed (Success, Warning, or Error).
Status Message The status of the file that was processed (Completed or Failed). If the status is Completed, the View Details link will be present. Click View Details to open the Logging Details dialog.