Tech Blog

Integrating with Priority‘s Financial Management Module for Invoice Payments

Introduction

This blog will show how to integrate financial payments from Alma Acquisitions to Priority’s Financial Management module.
We will focus on the payment of invoices. Note that it is also possible to pay POs (Purchase Orders) via this same integration (and not only invoices).
Details about Priority‘s Financial Management module can be found at Priority for Financials.

While this blog focuses on Priority’s Financial Management module, the flow and integration is either identical or nearly identical to integration with other systems.

This blog will explain

  1. the steps in exporting invoices to the financial system
  2. the steps in updating Alma from the financial system when the invoice is paid.

This blog will not discuss the creation of the invoices. It will begin after invoice has been created and before it is exported to and synchronized with the financial system. For information about creating invoices see  Creating Invoices.

You may also wish to see the blog by Nathan Mealey of Portland State University titled Exporting Invoices and Importing Payments with Banner and Alma.

Preliminary Settings

In the workflow described here the following settings exist in the institution. The settings are found under the acquisitions configuration menu in “General > Other Settings” and are also explained in the On Line Help at Configuring Other Settings for Acquisitions.

  • handle_invoice_payment = true
  • invoice_skip_erp = false
  • invoice_use_pro_rata = true

Here is a description of the parameters:

handle_invoice_payment = true

This means that invoices are sent to the ‘Waiting for Payment Invoices’ page to await automatic or manual handling.
If this parameter was set to false then invoices would be closed automatically when they are exported to the ERP system.

invoice_skip_erp = false

This means that the invoice workflow does not skip the step where the invoice is Waiting for Payment

invoice_use_pro_rata = true

This means that the use pro rata setting is selected by default when creating new invoices. For more information about the pro rata when invoicing see Creating Invoices in Alma.

Steps to configure and run integration

ONE
An integration profile of type “finance” should be created. For more about this type of integration profile see Financial Systems in Alma.

Via this integration profile the invoices will be exported to the financial system and imported back from the financial system with payment status.  As with other integration profiles the invoices are not sent directly back and forth to the “other system” but rather placed on an ftp server for “pickup”.

The integration profile is created via “External systems > Integration Profiles” under the General Configuration menu.  Here is the “General Information” tab where the integration type (“Finance”) appears and the ftp connection is chosen.

In the integration profile “Actions” tab we have defined that:

  • The “Import Payment Confirmation” will occur every day at 02:00 and will go to directory “invoice_paid” on the ftp server.
  • The “Export Invoices for Payment” will occur every day at 02:00 and will go to directory “invoice_out” on the ftp server.

Note that the import and export can also be run manually.

Here is the “Actions” tab of the profile:

TWO
The invoice should then be created and be in status “ready to be paid”.  The invoice is created via one of the methods described at Creating Invoices in Alma.

In our example we will manually create an invoice for Purchase Order PO-385713  (This Purchase Order has one order, POL-46096, with title “The effect of knowledge and attitudes of library directors and professional librarians toward library automation on automated programs in academic and research libraries in Taiwan / $$c by Lucy Te-chu Lee with introduction by Alicia Chen”).

The invoice “Payment method” is “Accounting Department”.
For information about making this the default method payment method see Configuring the Default Payment Method of the Invoice in Alma.

Here is the invoice header.

Note also that the invoice above is in status “Approved”. It could also have previously been in a status “Ready to be paid”. These optional steps are determined by “Invoice Approval Rules”, which are described at Configuring Invoice Approval Rules.

THREE
Now we will export the invoice to the finance system. For more information about exporting invoices see Invoice Export.

The job “ERP Export” is run as defined in the integration profile, which in our case is called “Priority”, which we saw above.
Rather than waiting until 02:00 AM (the time it is scheduled to run automatically) we will run it manually:

Here is the file on the ftp server:

The file of the invoice is on the ftp server for the finance department to take.
In this case the file is called 7484513260000121-1668947793199.xml and you can see the actual file here: Invoice file exported from Alma

See also the Data Dictionary (based on xsd) for the invoice export at Invoice Payment XSD Data Dictionary.

Because the job “Export Invoices for Payment” has run the invoice changes status from “Ready to be paid” to status “Waiting for Payment”

FOUR
Now the Payment Status will be imported from the Finance System and the invoice will be closed.  For more information about the invoice import see Import for Integrations of Type Finance.
The Finance system has paid the invoice and returns an xml file back to the defined directory on the ftp server with the payment status PAID.

The important tag in the xml is this:

<xb:payment_status>PAID</xb:payment_status>

If the invoice is rejected by the finance department then the invoice xml should have this:

<xb:payment_status>REJECTED</xb:payment_status>

The xml should also have the unique identifier of the invoice.  The unique identifier was included also in the export.

Here is the unique identifier of the invoice from the export.

Here is the unique identifier of the invoice in the Alma User Interface.

Here is the file called 7484511820000121_to_import which we will use to import the PAID payment status for invoice number PO-385713.  You can see the actual file here: Invoice file imported to Alma.

Here is the PAID status and unique identifier:

See also the Data Dictionary (based on xsd) for the invoice import at Invoice Receive Payment XSD Data Dictionary.

The invoice information in xml format is put on the ftp server by the finance system. It is put in the directory specified in the integration profile:

The import file is now on the ftp server and the import of the integration profile runs (either manually or scheduled):

The invoice has now changed to status “closed”:

The Payment Status has changed to “Paid”:

Note also that the Payment Identifier in the invoice in Alma comes from the payment_voucher_number in the input file:

Note also that the Invoice Note in the invoice in Alma comes from the payment_note in the input file:


Files referred to above

Invoice file exported from Alma

<?xml version="1.0" encoding="UTF-8"?>
<payment_data xmlns="http://com/exlibris/repository/acq/invoice/xmlbeans">
  <invoice_list>
    <invoice>
      <invoice_number>PO-385713</invoice_number>
      <invoice_owner>Alma University</invoice_owner>
      <approved_by>AliciaC613</approved_by>
      <invoice_amount>
        <currency>EUR</currency>
        <sum>10</sum>
      </invoice_amount>
      <vendor_code>ACHEN</vendor_code>
      <vendor_name>A. Chen Publishing</vendor_name>
      <vendor_liable_for_vat>false</vendor_liable_for_vat>
      <vendor_payment_address_list>
        <payment_address preferred="true">
          <line1>21 Sifria Blvd.</line1>
          <line2>Southern Dimona Educational Center</line2>
          <city>Bismarck</city>
          <country>USA</country>
          <stateProvince>North Dakota</stateProvince>
          <types>
            <type>Billing</type>
            <type>Claim</type>
            <type>Order</type>
            <type>Payment</type>
            <type>Returns</type>
            <type>Shipping</type>
          </types>
        </payment_address>
      </vendor_payment_address_list>
      <unique_identifier>7484511820000121</unique_identifier>
      <invoice_date>20/11/2022</invoice_date>
      <invoice_due_date>01/01/1970</invoice_due_date>
      <payment_method>ACCOUNTINGDEPARTMENT</payment_method>
      <number_of_attachments>1</number_of_attachments>
      <invoice_ownered_entity>
        <createdBy>AliciaC613</createdBy>
        <creationDate>20221120</creationDate>
        <customerId>110</customerId>
        <institutionId>121</institutionId>
        <modificationDate>20221120</modificationDate>
        <modifiedBy>AliciaC613</modifiedBy>
      </invoice_ownered_entity>
      <vat_info>
        <expended_from_fund_ind>true</expended_from_fund_ind>
        <inclusive_ind>true</inclusive_ind>
        <vat_amount>0.0</vat_amount>
        <vat_percentage>0.0</vat_percentage>
        <vat_type>INCLUSIVE</vat_type>
        <vat_in_invoice_line_level>false</vat_in_invoice_line_level>
      </vat_info>
      <additional_charges>
        <discount_amount>0.0</discount_amount>
        <insurance_amount>0.0</insurance_amount>
        <overhead_amount>0.0</overhead_amount>
        <shipment_amount>0.0</shipment_amount>
        <total_charges_amount>0.0</total_charges_amount>
      </additional_charges>
      <invoice_line_list>
        <invoice_line>
          <line_number>1</line_number>
          <line_type>REGULAR</line_type>
          <quantity>1</quantity>
          <total_price>10.0</total_price>
          <price>10.0</price>
          <po_line_info>
            <fully_Invoiced_ind>true</fully_Invoiced_ind>
            <po_line_owner>Main Library</po_line_owner>
            <mms_record_id>99484387800121</mms_record_id>
            <meta_data_values>
              <creator>Li, Te-chu.</creator>
              <date>1988</date>
              <publisher>University of Pittsburgh</publisher>
            </meta_data_values>
            <po_line_number>POL-46096</po_line_number>
            <po_line_price>10.0</po_line_price>
            <po_line_title>The effect of knowledge and attitudes of library directors and professional librarians toward library automation on automated programs in academic and research libraries in Taiwan / by Lucy Te-chu Lee with introduction by Alicia Chen</po_line_title>
          </po_line_info>
          <fund_info_list>
            <fund_info>
              <amount>
                <currency>EUR</currency>
                <sum>10</sum>
              </amount>
              <local_amount>
                <currency>USD</currency>
                <sum>10.35</sum>
              </local_amount>
              <code>LIS</code>
              <name>Library and Information Science</name>
              <fiscal_period>01/01/2022 -  31/12/2022</fiscal_period>
              <type>ALLOCATED</type>
              <fund_type>WorkDay</fund_type>
              <fund_type_desc>WorkDay</fund_type_desc>
              <ledger_code>LEDGER1006</ledger_code>
              <ledger_name>Information Technology</ledger_name>
            </fund_info>
          </fund_info_list>
        </invoice_line>
      </invoice_line_list>
      <invoice_exchange_rate_list>
        <exchange_rate>
          <currency>ISK</currency>
          <explicit_ind>false</explicit_ind>
          <rate>149.20277</rate>
        </exchange_rate>
        <exchange_rate>
          <currency>USD</currency>
          <explicit_ind>false</explicit_ind>
          <rate>1.0345498</rate>
        </exchange_rate>
        <exchange_rate>
          <currency>GBP</currency>
          <explicit_ind>false</explicit_ind>
          <rate>0.8702105</rate>
        </exchange_rate>
        <exchange_rate>
          <currency>PLN</currency>
          <explicit_ind>false</explicit_ind>
          <rate>4.7089086</rate>
        </exchange_rate>
      </invoice_exchange_rate_list>
    </invoice>
   </invoice_list>
</payment_data>

Invoice file imported to Alma

<?xml version="1.0" encoding="UTF-8"?>
<xb:payment_confirmation_data xmlns:xb="http://com/exlibris/repository/acq/xmlbeans">
  <xb:invoice_list>

    <xb:invoice>
      <xb:vendor_code>ACHEN</xb:vendor_code>
      <xb:invoice_number>PO-385713</xb:invoice_number>
      <xb:unique_identifier>7484511820000121</xb:unique_identifier>
      <xb:payment_status>PAID</xb:payment_status>
      <xb:payment_note>Paid and approved by Thomas Safransky</xb:payment_note>
      <xb:invoice_date>20221120</xb:invoice_date>
      <xb:payment_voucher_date>20221120</xb:payment_voucher_date>
      <xb:payment_voucher_number>613</xb:payment_voucher_number>
      <xb:voucher_amount>
        <xb:currency>EUR</xb:currency>
        <xb:sum>10.00</xb:sum>
      </xb:voucher_amount>
    </xb:invoice>
  </xb:invoice_list>
</xb:payment_confirmation_data>

2 Replies to “Integrating with Priority‘s Financial Management Module for Invoice Payments”

  1. Thanks for this, which is very clear and helpful.

    When the invoice (payment) import is run, as in your step FOUR, and the XML contains a Explicit currency conversion rate, does that rate get added to the invoice in Alma, perhaps in the Explicit Ration section? That would be sooo helpful, but I haven’t gotten it to work that way in my testing so far. I don’t know why the import file would be set up to include that if it doesn’t import in some way. If it can be imported, how do you set up your configuration and XML file to make that happen?

  2. Hello “SLV User” (Alan):

    Please confirm that this is the situation you are describing:

    Problem:
    Explicit Ratio information in the import file of the Finance integration profile it is not taken into account when the invoice is change from “Waiting for Payment” to “Closed”

    Description:
    When running an integration of type “Finance” and importing the xml file via the “Import Payment Confirmation” section of the “Actions” tab of the integration profile (as described at https://developers.exlibrisgroup.com/blog/integrating-with-prioritys-financial-management-module-for-invoice-payments ) then:
    If the imported xml contains the following six lines to state that there is an explicit ratio (as described at https://developers.exlibrisgroup.com/alma/apis/xsd/invoice_receive_payment.xsd/#XML ):


    GBP
    1000
    true

    Then when the invoice gets changed from “Waiting for Payment” to “Closed” the explicit ratio is not added to the invoice.

Leave a Reply