Deprecated: Run Invoice Export to Duke AP/SAP

By Julie Brannon
7 min

Introduction

This page describes a manual process that was used to run invoice exports to Duke AP for several months after go-live with Alma. This process has moved into a nightly automated schedule. Please reference user documentation Invoice Approval Process and technical specification https://duke.atlassian.net/l/cp/sx1Hbmpr pages for additional information about the process that’s currently in production.

Integration Diagram

For reference, this diagram explains the full process. This wiki page describes the manual process we’re doing now to complete steps 5-17 which will eventually be automated.

 

image-20241108-170518.png

 

Frequency

Only run the invoice export one time per day. The file naming convention for files sent to SAP isn’t set up to manage more than one file per library (PERKN, LAW, MED, FORD) per day. The export job in Alma scoops up invoices from all libraries together, so we’re not running this separately for each library. Currently, staff seem to be requesting that this run about 3 times per week.

Moving files around on the S/FTP server

Derrek set up a separate directory on the Alma S/FTP server for the GitLab process, so we need to move files around between the folders that 1) manage what goes in/out of Alma and 2) a higher level directory that manages files in/out of GitLab.

 

image-20240731-132829.png

Roles/Permissions

To run this process, you need the following roles and permissions:

  • Alma: Invoice Operator (to view the list of Ready to be Paid invoices)

  • Alma: General System Administrator (to run the jobs from the Configuration area)

  • S/FTP Server permissions within dul-lsis-ftp/alma directory

  • WinSCP or other tool setup to connect to the Alma S/FTP server - instructions here: WinSCP server setup

  • Access to the Alma Integrations GitLab repository https://gitlab.oit.duke.edu/alma-integrations

Overview of this process

  • Run a job in Alma to create an .xml file of invoices

  • Run a job in GitLab which does 4 things

    • transform the file

    • generate reports

    • send files to AP

    • create a payment confirmation .xml file to send back to Alma

  • Run an Alma job to ingest the payment confirmation file

  • Notify users by emailing them the .dat output file and .xls report

Step-by-Step Instructions to run the export

1. Communication

This process begins when you receive a request via email from Julie Harris (Ford), Neal Fricks/Marsha Perry (Law) or Penny Brown (DUL) asking to export invoices to AP. Li Ma has not yet indicated that the Medical Center Library is ready to process invoices.

  • Send an email to the other libraries to ask if they want me to wait for invoices from them as well for today. I send something like this: “Penny has some DUL invoices ready for export today.  Let me know if you expect to approve more invoices today and would like me to hold off until later to run the export.  If not, I’ll go ahead and run it for Penny. Thanks, Julie”

  • Once everyone has replied and the invoices for the day are ready, we can run the export.

2. Set up the tools you’ll need

3. Count the number Invoices ready for export

  • Navigate to Acquisitions > Receiving and Invoicing > Ready to be paid

  • Note the number of invoices sitting in the queue on this screen so that you can confirm that they all exported later.

4. Run Export in Alma

  • Navigate to Configuration > General > Integration Profiles > Invoice Export

  • Click the Actions tab

  • Look for the Export Invoices for Payment section and click “Run” as seen below

  • image-20240731-172505.png

Navigate to the “Monitor Jobs” page and find the job name “ERP export using profile Invoice Export” to confirm that it completes successfully. Click on the elipses on the far right and select Report to confirm that the expected number of invoices were processed.

image-20240731-172903.png

Sample job report showing that 19 invoices were exported

image-20240731-173138.png

 

5. Copy the output file to the directory needed for GitLab

  • In WinSCP, navigate to the Alma S/FTP server to /home/dul-lsis-ftp/alma/production/invoices. Be careful - there is an invoice-export directory at the top level, but that’s used by GitLab. We need to grab the invoice file exported by Alma and it’s in the production/invoices directory.

  • Find the latest .xml file which has a date/timestamp that matches when you just ran the export in Alma. You might need to refresh to see it pop up. Here’s how that directory looks.

    image-20240731-173926.png

  • Copy the file and paste it into the Alma S/FTP server directory /home/dul-lsis-ftp/alma/invoice-export/input. The GitLab pipeline job will look for the Alma invoice extract file there.

  • Copy the file name to your clipboard since you’ll need it as an input variable to the GitLab pipeline Be sure to copy the full file name including the .xml extension. So, in the example above, we need to copy the text 16915868640008501-1722357426274.xml for use later.

6. Run the Invoice Export job in GitLab

  • Go to Gitlab invoice export, pipelines https://gitlab.oit.duke.edu/alma-integrations/invoice-export/-/pipelines

  • Select Run pipeline. The screen below will open. On the first variables row, add the input variable key INPUT_FILE. Paste the file name you copied to your clipboard as the input variable value, as seen below. Ignore the second line that is hovering there - we only have one input variable.

  • Click Run Pipeline

image-20240731-174513.png

  • On the next screen, click on one of the grey play buttons to run the process. It can take a few minutes to complete, so refresh occasionally until complete.

image-20240731-174756.png

  • If you’re curious, you can view the job log by navigating to Jobs and clicking on the job name, as seen below.

image-20240731-175141.png

Sample log view:

image-20240731-175225.png

7. Run a job to import the payment confirmation file to Alma

  • In WinSCP, navigate to the /alma/invoice-export directory. Copy the alma_payment_update.xml file that was created by the Invoice-Export app from GitLab. You might need to refresh to see the file pop up.

image-20240731-175935.png

  • Navigate to the /alma/production/invoices/payment_confirmation directory and paste the file there. This is where the Alma job we’re about to run will look for a payment update file.

image-20240731-180358.png

8. Run the Alma Invoice Payment Confirmation job

  • Back in Alma, navigate to Configuration > General > Integration Profiles > Invoice Payment Confirmation

  • Click the Actions tab

  • Look for the Import Payment Confirmation section and click “Run” as seen below

  • Navigate to “Monitor Jobs”and confirm that the “ERP import using profile Invoice Payment Confirmation” completed successfully. This job doesn’t generate a useful report.

image-20240731-180541.png

9. File Housekeeping (Optional)

  • This is optional…Make a copy of the folders containing files from today’s GitLab run - this makes it easy to attach the output reports to the email to users. This is optional…

image-20240731-182301.png

  • Optional:Now, let’s clean up. On the Alma server, delete the files generated by the GitLab run from the invoice-export folder, the input, output, and report folders so that it’s clean and ready for tomorrow. The files have unique names daily, but I like to remove the clutter so I don’t accidentally reference the wrong file when doing this process.

10. Send output file, detail report, and error report to staff by email

  • Send an email to the contacts at the libraries that had invoices in this run. If there were no errors, attach the .dat file from the /alma/invoice-export/output folder and the .xlsx file from the reports folder. If there were errors in the run, also attach the error report that is also in the reports folder.

    • Marsha Perry and Neal Hicks at Law

    • Julie Harris at Ford

    • Penny Brown at DUL

    • Li Ma at Medical Center - not running invoices yet as of 7/31/24

image-20240731-191251.png

 

 

Related content