Troubleshooting Unimarket-to-Banner Invoice Integration Errors

  • Updated

This guide provides Functional Users in Accounts Payable and Finance Offices with instructions for troubleshooting common errors encountered during the transmission of Invoices from Unimarket to Banner, and offers guidance on reconciling data between the two systems.

 

Interface Logging and Error Notifications

When the Banner APIs produce an error during message transmission, the interface logs the activity and triggers an error notification.

Error Notification

Error emails are sent using the Oracle UTL_MAIL function, to the addresses defined in the FTMSDAT record (FZKEPRC-UM ERROR EMAIL). These emails contain the document ID and the specific API error message.

 

Interface Error Logging Tables (FISHRS Database Schema)

Table NameContent LoggedPurpose
FZPEPRCRequest Log (cXML messages)Records messages sent from Unimarket to the Banner Interface.
FZRCXMLBanner PO and Invoice API LogRecords Banner PO and Invoice API activity, including the detailed API error message.

 

Unimarket Invoice 'Reference' Field

In Unimarket (v4.5+), the Reference field on the Invoices tab will display specific error codes if the transmission fails.  Refer to the API error email for the explanation.

CodeMeaningCommon Cause
Error_10Header Build ErrorPO has not posted or Supplier is missing data in Banner FTMVEND.
Error_20Header API ErrorGeneral failure of the Banner Invoice API. Will need to be researched using the API email.
Error_30Item/Accounting Line ErrorReferencing closed PO lines or invalid FOAPAL combinations.
Error_40Completion API ErrorInvoice created but failed to "Complete" in Banner. Manual completion in Banner required.

 

Timing & Posting Errors

These errors occur primarily because the Invoice and the Order arrive in Banner simultaneously, or the Banner posting process has not yet completed.

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve

PO has not been posted

Invoice waiting reprocessing

The PO is in posting event in Banner. An invoice cannot attach to a PO that isn't in the ledgers.

Wait: The integration is designed to retry the invoice automatically (usually 5/10 minutes later).

  • Verify: If you receive many of these, verify with Finance that the Banner Posting process is running.
  • Technical Note (Oracle 19c): If reprocessing fails, your DBA may need to grant CREATE JOB permissions to the FISHRS user. To allow DBMS_SCHEDULER to handle the INV DELAY logic.
Stopping a Reprocessing LoopThe Invoice will never post because the PO cannot post.

If an invoice is stuck in a failed retry loop, you can manually drop the scheduled job.

  1. Identify the ID: SELECT * FROM USER_SCHEDULER_JOBS;
  2. Match the JOB_ACTION to the FZBEPRC_ID.
  3. Drop the job:
    BEGIN
      dbms_scheduler.drop_job(job_name => 'DBMS_JOB$_XXXXX'); 
    END;
    /

Purchase Order cannot be invoiced.

Purchase Order has not been posted to the ledgers.

Invoice scheduled to be reprocessed

Invoice cannot be created because the Purchase Order has not been posted.

Error occurs when the PO has not posted. If the PO is not posted, the PO cannot be invoiced.

The error must be resolved in Banner.

If error occurs in Prod:

Option 1:

  1. Open a Ellucian ticket.
  2. Once resolved, verify the POs has posted and are not in a Complete and Approved state.
  3. Check FOAAPPD for documents that are pending posting. To see if the POs or Invoices are stuck.
  4. If you have access to FGRACTG, you can view the .log file for any warnings.

Option 2: 

  1. Check to see if any other POs are failing, to ensure that posting is running.
  2. Look up the API error email for the PO (Note: If you have access to the tables associated with Unimarket, you can look in the FZRCXML log for the error that needs to be fixed).
  3. Fix the PO.
  4. Resend the invoice, in Unimarket.

IF the posting process is running: The customer has recently upgraded Oracle to version 19c. Which will need to have the below grant performed by the DBA in IT. To give permissions to the FISHRS user, to reprocess the invoice for a retrofit order. This will allow FISHRS to use DBMS_JOB functions from the FTMSDAT record, for the “INV DELAY” when the invoice is reprocessed.
 

The issue with the Oracle 19c upgrade was the DBMS_Jobs not being a default with the DBMS_Scheduler, assigned as the Oracle default job. The solution was to grant the FISHER user permission to “create job,” so that it can perform the DBMS_Job. To reprocess an invoice if the PO hasn't posted at the time it attempted to hit Banner.

 

Option 3: If the PO cannot be fixed, then:

  1. Inactivate the current INV_Delay record, in FTVDAT.
  2. Wait the X number of minutes that the reprocess would have occurred to allow the reprocess fail (do not try again, since the FTVSDAT record is inactive).
  3. Create the new FTVDSDAT record with the same value like 10 or 15 minutes.

If error occurs in Demo:

Option 1: Update the INV_DELAY to a longer timeframe like 999 (Note: This does fix the PO and the team would still need to identify/resolve the error). This may be a viable option if the customer does not have posting running all the time, in TEST any longer.


Option 2: 

  1. Inactivate the current INV_Delay record in FTVDAT.
  2. Wait the X number of minutes that the reprocess would have occurred to allow the reprocess fail (do not try again, since the FTVSDAT record is inactive).
  3. Create the new FTVDSDAT record with the new value like 9999.
   

 

Amount & Calculation Errors

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
Amount exceeds toleranceUnimarket's matching tolerance is higher than Banner'sManual Action: AP must manually create the invoice in Banner or adjust the PO/Invoice in Unimarket to fit within Banner's stricter tolerances.
Approved unit price should be positiveBanner APIs do not allow a $0.00 price for free/discounted items.1. Edit in Banner: Set price to $0.0001. 
2. Permanent Fix: Contact Unimarket to enable the "$0.00 to $0.0001" interface modification.
Percent and Amount do not match (Split Lines)A known Banner API bug when a line is split across 3+ accounts; rounding differs by a penny.Manual Action: Open the invoice in Banner and manually adjust the split amounts to match the subtotal.

 

Vendor & Data Validation Errors

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
Vendor Invoice Already ExistsThe invoice was resent manually, or the invoice number is already used in Banner (outside Unimarket).1. Check Banner: If the Banner Invoice Document Number exists but is incomplete, complete it. 
2. If duplicate: Add a suffix (e.g., "-A") to the vendor invoice number in Banner and complete.
Invalid combination of address type and sequence for vendorThe Vendor Maintenance tab in FTMVEND is missing the default Address Type for AP.

1. Update FTMVEND with the default AP address/sequence. 

2. Resend Invoice from Unimarket.

Invalid value for vendorThe Vendor ID on the PO (Old) does not match the Vendor ID on the Invoice (New).Check Unimarket: Ensure the Supplier record was updated correctly. You may need to manually process the invoice in Banner.
User does not have authority post 

In Unimarket, review the accounting string the user is approving the invoice for.

Verify the user has posting authority for the accounting string on the FOMPROF screen, in Banner. 

 

Status & Fiscal Year Errors

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
PO is Closed / CanceledThe PO status in Banner does not allow new activity.1. Reopen PO in Banner if payment is valid. 
2. Resend Invoice from Unimarket.
Document has incomplete docs: Incomplete Invoice exists against Purchase Order

This occurs when a user attempts to close a Purchase Order in Unimarket while an associated invoice in Banner remains in an "Incomplete" status.

1. Locate Invoice: Search for the specific invoice in Banner using form FAAINVE (Invoice/Credit Memo Header). 

2. Report Tool: Alternatively, run the FGRIDOC (Incomplete Document Listing) report to find all documents preventing the PO from being finalized. 

3. Complete/Approve: Once the invoice is completed and approved in Banner, the PO can be successfully closed in Unimarket.

FUND is no longer activeMost common with Grant/Sponsored Accounts: a change is attempted on an order where the FUND Term Date in Banner has passed.

1. Discuss with Grant/Finance Office to reopen the FUND

2. Alternatively, Change the funding used on the Invoice in Banner.

Encumbrance doesn't exist in the fiscal year that the Invoice Transaction Date Falls.Encumbrances haven't rolled in Banner yet.Manually change the transaction date on the invoice in Banner. Or update the FZREPRF configuration to allow the system to use the PO transaction date.

 

System & Environment Issues

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
Deadlock Detected (ORA-00060)System congestionIf the invoice isn't in FOIDOCH, resend it. If it is there but "Suspended," delete it from Banner and resend.
Value Error / Precision too large (ORA-06502)Occurs on invoices over $1MUpgrade your interface code to version 4.5
Wrong Deployment ModeUsually happens after a Clone of Prod to TestAsk IT to update the connector.properties file to the correct environment name.