Troubleshooting Unimarket-to-Banner PO Integration Errors

  • Updated

This guide provides Functional Users in Procurement and Finance Offices with instructions for troubleshooting common errors encountered during the transmission of Purchase Orders (POs) 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-TO). These emails contain the document ID and the specific API error message.

 

Interface Error Logging Tables (FISHRS Database Schema)

TableContent LoggedPurpose
FZBEPRCRequest 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 messages.

 

General Troubleshooting & Reconciling Steps

Purchase Orders that encounter an error in Banner will often exist in an Incomplete status. Use these steps to validate and begin resolving the issue:

StepBanner Form / ReportAction
1. Validate Document StatusFGRIDOC (Incomplete Documents Report)Consistently run this report to identify all orders and invoices that are Incomplete and need reconciliation or completion.
2. Review Error DetailsAPI Error Email / FZBEPRC / FZRCXMLUse the error email subject line (e.g., PROD: Error in OrderRequest (12345)) and document ID to find the precise error message logged in the tables.
3. Complete/Fix DocumentFPAPURR (Purchase Orders)If the document is Incomplete, use this form to resolve the error(s) and complete the document accordingly.

 

Common Purchase Order (PO) Errors

Use the table below to quickly identify the error, its cause, and the required action:

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
Vendor Record Error for PO (Address Type, Vendor ID, or Sequence Invalid)PO Transaction Date is before the Vendor Effective Date in FTMVEND. OR Vendor Address Type/Sequence is missing or inactive in FTMVEND.

1. Check FTMVEND: Backdate the Vendor's effective start date OR ensure default Address Type/Sequence is assigned for PO/AP. 

2. Resend Order from Unimarket and check Banner to see if the order appears.

 
If the dates do not match, please update the record in Banner and resend the PO in Unimarket.
 
If the recommendations above does not resolve this issue. Please provide a full screenshot of FOIDOCH screen for the vendor (including the Address tab) to Unimarket Support team.

Order Already ExistsA previous error occurred, and the order was resent from Unimarket, but the header already exists in Banner as Incomplete.

1. Check FOIDOCH for 3-way match/approval status. 

2. If Incomplete, view FPAPURR, resolve the specific error from the API email, and complete the document.

Invalid Purchase Order CodeA user attempted to close a PO in Unimarket that does not exist in Banner.

Review the order in Unimarket, to confirm:

  • There are no invoices against the order and 
  • Receiving has been manually closed. 

No action required. This is a non-impacting informational error.

Vendor ID error (e.g., Path //SupplierID[1]... not found or Invalid value for vendor)... not found or Invalid value for vendor)]The Vendor ID is missing or incorrect in the Manage Supplier record in Unimarket.

1. Check Unimarket: Verify the correct Vendor ID is present. 

2. Contact Unimarket Support to configure a default Vendor ID sequence for better error messages.

ShipTo location code is invalidThe ShipTo code used is not valid or inactive in Banner form FTMSHIP.

1. Check FTMSHIP: Reactivate the code or confirm the code's effective date is before the Transaction Date of the PO. 

2. Update Unimarket or manually update the PO in FPAPURR if a resend fails to pick up the updated code.

Document has incomplete docs: Incomplete Invoice exists against Purchase Order UP122375.

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) or resend the close message from Unimarket.

Purchase Order cannot be invoiced. 

Purchase order has been canceled.

 

Investigate why the PO was closed/canceled in Banner. 

If payment is valid, reopen the PO in Banner and resend the invoice. If the cancellation was correct, cancel the invoice in Unimarket.

Location XXX is invalid.
  1. Missing Code: The location code (e.g., S09) has not been set up in your ERP's validation tables.
  2. Inactive Status: The code exists but has been terminated or marked as inactive for the current fiscal period.
  3. Mapping Issue: The code in Unimarket does not exactly match the code in the ERP (case sensitivity or leading zeros).
  1. Check the ERP Record: Look up the location code in your ERP (in Banner, check the FTVLOCN form). Ensure the code is active and the "Terminated" date is blank or in the future.
  2. Verify Unimarket Profile: Check the user's default shipping address or the specific line item on the requisition to see if the location was entered correctly.
  3. Resend after Fix: Once the code is reactivated in the ERP, go to the Unimarket portal and Resend the failed document.

Purchase order does not exist. 

Must be created before it can be referenced

This error indicates that the Purchase Order mentioned in the invoice cannot be found in the Banner PO tables (FPBPOHD)

Step 1: Manual Resend from Unimarket

  1. Go to Marketplace and locate the specific Order.
  2. Select More Actions > Order Message.
  3. This attempts to re-push the cXML to Banner. Wait 5–10 minutes and check Banner to see if the order has been created.

Step 2: Vendor Maintenance Check (FTMVEND)

If the order still does not appear in Banner, there is likely a validation issue with the vendor record. Have your Banner Administrator review the following:

  • Form: FTMVEND (Vendor Maintenance).
  • Tab: Vendor Maintenance.
  • Requirements: * Ensure the Procurement and Accounts Payable address defaults have valid Type Codes.
    • Verify that these addresses also have an associated Sequence Number.
    • If these are missing or null, the API will fail to create the PO header.

Purchase order has not been posted. 

Cannot be referenced

This error suggests that while the Purchase Order record exists in Banner, it is in an "Incomplete" or "Suspended" status. And has not yet, posted to the ledgers.

To find the root cause of why the PO is stuck, your technical team should query the integration log tables.

  • Schema: FISHRS
  • Target Tables: FZRCXML or FZBEPRC
  • Search by the PO number FZRCXML_DOC_ID and this field should provide you with the Error Message; FZRCXML_ERROR_MSG.


Common Findings in FZRCXML:

  • NSF (Non-Sufficient Funds): The PO is held because the budget is exceeded.
  • Invalid Accounting: A FOAPAL element used on the PO is now closed or inactive.
  • Vendor Hold: The vendor has been placed on hold in Banner after the Unimarket requisition was approved.

Purchase Order cannot be invoiced. 

Purchase Order not completed or approved.

 
  • Take a look at the order in Banner and determine why it’s not complete or approved.
     
    You may need to back out/remove it and then try re-sending the PO (within Unimarket).
UP122375: Unable to select PO. 

Review the FGIENCD screen. If the status is designated to open (O), the error message is expected. 

If you aren't expecting any additional invoices against this PO, we recommend manually closing the order in FPAEOCD.

Commodity code XXXXX is not valid as of XX-NOV-XXXX 
  • Cancel the PO and
  • Create a new PO with a commodity code, that is active in Banner.

 

Note: Once a PO is in Banner (in a Completed and Approved state), the commodity code cannot be updated.

 

Common Accounting or Budget Errors

These errors relate to accounting/FOAPAL or budget issues.

Error Sample / Subject LinePrimary Cause in BannerUser Action to Resolve
Program Code RequiredThe ORGN code on the FOAPAL does not have a default PROG code setup in Banner, and the PROG was not entered in Unimarket.

1. Update the ORGN default PROG in Banner. 

2. Manually update the PO in FPAPURR OR delete the PO and resend from Unimarket.

Buyer User Does not have proper Fund/Orgn AccessThe Buyer's user ID is missing the required Fund/Organization access on Banner forms like FOMPROF.

1. Grant the Buyer the necessary Fund/Orgn access in Banner. 

2. Reprocess the order in Banner or delete and resend from Unimarket.

Mixed Expense Accounting (GL, Operational, Fixed Asset Accounts)General Ledger, Operational Expense, and Fixed Asset accounts were used on the same order.

1. Manually update the PO in FPAPURR to separate the account types onto different documents or lines. 

Note: Newer Unimarket versions catch this error at checkout.

Purchase Order is valid but failed the available budge/balance checkInsufficient budget available (e.g., multiple large POs approved simultaneously outstripped the budget before encumbrance).

1. Check Budget: Use FGIBAVL to confirm budget availability. 

2. Resend the PO to Banner once the budget issue is resolved.

Accounting Period Closed in BannerThe PO Transaction Date is not within an open accounting period for the Chart of Accounts in Banner.Reopen the accounting period in Banner and then resend the order from Unimarket.
M ixing asset and non-asset accounts results in an incomplete fixed asset record

Banner’s Fixed Asset API expects a clean relationship between the procurement document and the asset record.

When a single Purchase Order or Invoice contains a mix of asset and non-asset accounting codes on the same line or document, it often results in an incomplete or "orphaned" fixed asset record.

By asset and non-asset, this could also mean a regular expense account and a capital account.  
 
Capital accounts are typically tied to fixed asset tagging, in Banner. And there's a restriction within the Banner API, that does not allow regular expense accounts and capital accounts to be charged on the same PO. 

Note: If you're unsure if an account is set-up as an asset account or not, your Accounting team/Controller's Office may be able to confirm that for you.

  1. Identify the Document: Locate the Purchase Order or Invoice in FZBEPRC or FZRCXML to see how the accounts were distributed.
  2. Manual Correction in Banner:
    • Access the FFAMAST (Fixed Asset Master) or FAAINVE (Invoice Inventory) forms.
    • You will likely need to manually complete the asset information (Manufacturer, Model, Serial Number) that failed to pull from the Unimarket cXML.
  3. Adjust the Encumbrance: If the error happened on a PO, ensure the encumbrance in FMAPO reflects the correct capital amount. So, the subsequent invoice doesn't repeat the error.

 

Common Change Order and System Errors

These errors relate to blanket orders, change orders, or system configuration.

Error Sample / Subject LinePrimary Cause (Where to Check)Action to Resolve
Change or Update attempted before PO Posted (ORA-00001: unique constraint... violated)A change (e.g., cancelation) was attempted on a PO that is still in process and has not yet been posted in Banner.

1. Verify Posting Process: Ensure the standard PO posting process is running. 

2. Wait for the PO to post, then resend the change/update message from Unimarket.

Blanket Order Not Found for Release Order (Parent PO with orderID UP122375 not found!)The Parent Blanket PO is either Incomplete in Banner or was never successfully posted.

1. Check FOIDOCH or FPAPURR: Resolve the underlying error on the Blanket PO first. 

2. Resend the Blanket PO, then resend the Release Order.

Change Order where the 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, Cancel the order in Unimarket.

Blanket Release Order Could not create JV detail for POThe encumbrances have not rolled to the next fiscal year and the JV is using the system date to post the release order in the new fiscal year.Create a manual E035 Journal in Banner to ensure the balance is the same in both software's.
Cannot Cancel: Type “delete” is not supportedCancel Order is enabled in Unimarket, but the Banner Interface is not configured to handle the Request Type="Delete" integration message.

1. Manually cancel the PO in Banner

2. Contact Unimarket Support to upgrade the interface to include the Cancel PO code.

FOMPROF User Organization - Data Entry not allowedThe user ID used to post the PO has a home Organization (FOMPROF record) that is not marked as Data Enterable in FTMORGN.

1. Check FTMORGN: Verify the user's home org in FOMPROF is Data Enterable ('Y'). 

2. Change the user's home org in FOMPROF to a Data Enterable one and resend the PO.

Deadlock Detected (ORA-00060: deadlock detected)Banner is receiving too many requests for processing at once (system congestion).

PO Not in Banner 

  1. Verify the PO is not in Banner by viewing in FOIDOCH or FPIPURR.
  2. If it is not in Banner, resend the PO from Unimarket.

PO in Banner and NOT Posted

  1. If the PO does appear in FOIDOCH, the status field is likely going to be blank/not approved
  2. Use FPAPURR to delete the Incomplete PO record, and then resend the PO from Unimarket.
The Account is Locked (ORA-28000: The account is locked)The dedicated integration user account (UNICON) is locked (often after a database refresh/clone).Contact IT to unlock the UNICON account and update the password in the connector.properties file.
Clone of Prod to a DEV or PPRD Banner Instance (Wrong Deployment Mode "Production")The Banner Connector configuration is incorrect for the target Banner environment (e.g., Development/Test).Contact IT to verify the correct Deployment Mode is configured in the Banner Connector properties file for the specific Banner instance.