Adding Sales Order Number To RefNbr Lookup In Acumatica

Jul 15, 2025 by ADMIN 56 views

Adding SOOrder.OrderNbr to Payments and Applications Screen's RefNbr Lookup in Acumatica

In this comprehensive guide, we will delve into the process of adding the Sales Order Number (SOOrder.OrderNbr) to the Reference Number (RefNbr) lookup on the Payments and Applications screen (AR302000) in Acumatica. This customization enhances the user experience by providing a more direct link between payments and the corresponding sales orders, streamlining the application process. By integrating the Sales Order Number into the lookup, users can quickly identify and select the relevant sales order when applying payments, reducing the risk of errors and improving overall efficiency. This article will provide a step-by-step approach, covering the necessary technical details and code snippets to implement this customization effectively. Understanding the intricacies of Acumatica's customization framework is crucial for achieving this task, and this guide aims to demystify the process. This integration not only simplifies payment application but also provides a clearer audit trail, making it easier to track financial transactions related to specific sales orders.

The payments and applications screen in Acumatica is a critical component for managing accounts receivable. By default, the reference number lookup displays a limited set of documents, which might not always include the Sales Order Number. This can lead to inefficiencies and potential errors when applying payments to specific sales orders. The ability to directly select a sales order from the reference number lookup streamlines the process, saving time and reducing the likelihood of misapplication. This customization is particularly beneficial for businesses that process a high volume of sales orders and payments. By providing a more intuitive and direct way to link payments to sales orders, this enhancement can significantly improve the accuracy and efficiency of financial operations. Furthermore, it allows for better tracking and reconciliation of payments against sales orders, providing a clearer view of financial transactions. The steps outlined in this guide will enable you to seamlessly integrate this functionality into your Acumatica instance.

To successfully add SOOrder.OrderNbr to the RefNbr lookup, we must first understand the current behavior of the Payments and Applications screen (AR302000). The 'Documents to Apply' tab features a Reference Number selector that, by default, displays a specific set of documents. Our goal is to augment this list to include Sales Orders, thereby allowing users to directly select a Sales Order Number when applying payments. This requires modifying the data source behind the lookup to include Sales Orders and adjusting the user interface to display the Sales Order Number appropriately. Understanding the underlying data structures and Acumatica's framework for customizing screens is essential for this task. The process involves extending the existing data view to incorporate Sales Order information and updating the selector to display this new data. This enhancement will provide users with a more comprehensive view of relevant documents, making it easier to apply payments accurately. Before diving into the technical implementation, it's crucial to have a clear understanding of the screen's current functionality and the desired outcome of the customization.

The payments and applications screen's reference number lookup is powered by a data view that defines the available records. To include SOOrder.OrderNbr, we need to modify this data view to include Sales Order records. This involves understanding the existing data view's structure and adding a join to the Sales Order table. The modified data view will then need to be exposed to the user interface, allowing the Sales Order Number to be displayed in the lookup. This requires adjustments to the selector control on the screen to include the Sales Order Number as a displayable field. The underlying principle is to extend the existing functionality without disrupting other features of the screen. Careful consideration must be given to the impact of these changes on the screen's performance and the overall user experience. The integration of Sales Order Numbers into the reference number lookup will provide a more streamlined and intuitive way to apply payments, enhancing the efficiency of financial operations.

1. Create a Customization Project:

Start by creating a new customization project in Acumatica. This project will house all the changes required for this customization. Navigate to the Customization Projects (SM204505) screen and create a new project. Give it a descriptive name, such as "AddSOOrderToRefNbrLookup". This step is crucial for organizing your changes and ensuring they can be easily deployed and managed. Customization projects provide a container for all modifications, making it easier to track and revert changes if necessary. It also allows for better collaboration among developers and administrators. By isolating the changes within a project, you can minimize the risk of unintended consequences and maintain the stability of your Acumatica instance. The customization project serves as a central repository for all related files and configurations, ensuring a consistent and organized approach to customizations.

2. Customize the ARPaymentEntry Graph:

The ARPaymentEntry graph is responsible for the logic behind the Payments and Applications screen. We need to extend this graph to include Sales Order information in the RefNbr lookup. To do this, add a new graph extension in your customization project. This extension will allow us to modify the existing data views and add new ones without directly altering the base code. Graph extensions are a powerful feature in Acumatica that enable customizations to be made in a non-destructive way. They provide a way to add or override functionality without affecting the core system. This ensures that your customizations are preserved during upgrades and that you can easily revert changes if needed. The ARPaymentEntry graph extension will serve as the focal point for our customization, allowing us to add the necessary logic and data views to include Sales Orders in the reference number lookup.

3. Modify the RefNbr Selector Data View:

Identify the data view that populates the RefNbr selector. This is typically a data view that selects invoices and other AR documents. We need to modify this data view to also include Sales Orders. This involves adding a new DAC (Data Access Class) to represent the Sales Order and modifying the existing data view to include a join to the SOOrder table. The DAC serves as a mapping between the database table and the Acumatica framework, allowing us to access Sales Order data within the system. By joining the SOOrder table to the existing data view, we can retrieve Sales Order information and include it in the reference number lookup. This step is crucial for making Sales Orders available for selection on the Payments and Applications screen. The modified data view will provide a unified view of AR documents and Sales Orders, allowing users to easily select the relevant document when applying payments.

4. Add a New DAC for SOOrder:

If you don't already have a DAC for SOOrder in your customization, you will need to create one. This DAC will represent the Sales Order table and allow us to access its fields. A DAC is a class that maps to a database table and defines the fields and properties that can be accessed. It serves as an abstraction layer between the database and the application logic. By creating a DAC for SOOrder, we can easily work with Sales Order data within our customization. This DAC will include properties for fields such as OrderNbr, CustomerID, and OrderTotal, allowing us to display and manipulate Sales Order information. The DAC simplifies the process of retrieving and updating Sales Order data, making it easier to integrate Sales Orders into the reference number lookup.

5. Modify the Selector Field:

On the ARPaymentEntry graph extension, locate the field that corresponds to the RefNbr selector. Modify the selector attribute to include Sales Orders in the allowed types. This involves adding the SOOrder DAC to the selector's allowed types and specifying the fields to display in the lookup. The selector attribute defines the behavior of the reference number lookup, including the data sources and fields that are displayed. By modifying this attribute, we can control which documents are available for selection. Adding the SOOrder DAC to the allowed types ensures that Sales Orders are included in the lookup. We also need to specify the fields to display, such as OrderNbr and CustomerID, to provide users with enough information to identify the correct Sales Order. This step is crucial for making Sales Orders visible and selectable on the Payments and Applications screen.

6. Implement the Data View Modification:

Within the graph extension, override the existing data view or create a new one that includes a join to the SOOrder table. This will fetch Sales Order records along with the existing AR documents. The data view is responsible for retrieving data from the database and making it available to the user interface. By overriding the existing data view or creating a new one, we can modify the query that is used to fetch the data. This allows us to include Sales Order records in the reference number lookup. The join to the SOOrder table is essential for retrieving Sales Order information and integrating it into the existing data view. The modified data view will provide a unified view of AR documents and Sales Orders, making it easier for users to apply payments to the correct documents.

7. Add Conditions and Filtering:

Implement conditions and filtering to ensure that only relevant Sales Orders are displayed in the lookup. For example, you might want to only show Sales Orders that are open and have a balance due. This step is crucial for ensuring that the reference number lookup is efficient and user-friendly. By filtering the Sales Orders, we can reduce the number of records that are displayed, making it easier for users to find the correct document. Conditions can be added to the data view to filter Sales Orders based on criteria such as status, balance, and customer. This ensures that only relevant Sales Orders are displayed, improving the performance and usability of the reference number lookup. The filtering logic should be carefully designed to meet the specific needs of the business and ensure that users can easily find the documents they are looking for.

8. Customize the UI:

Modify the Payments and Applications screen's UI to display the Sales Order Number in the RefNbr lookup. This typically involves adding a new column to the selector grid and binding it to the OrderNbr field. Customizing the UI is essential for making the Sales Order Number visible and easily selectable. This involves modifying the selector control on the Payments and Applications screen to include a new column for the OrderNbr field. The new column will display the Sales Order Number in the lookup grid, allowing users to quickly identify and select the correct Sales Order. The UI customization should be designed to be intuitive and user-friendly, ensuring that users can easily understand and use the new functionality. This step is crucial for providing a seamless and efficient user experience.

9. Test Thoroughly:

After implementing the customization, thoroughly test the Payments and Applications screen to ensure that the Sales Order Number is displayed correctly in the RefNbr lookup and that payments can be applied to Sales Orders without any issues. Testing is a critical step in the customization process. It ensures that the changes have been implemented correctly and that the new functionality works as expected. Thorough testing should include a variety of scenarios, such as applying payments to Sales Orders with different statuses and balances. It's also important to test the customization with different users and roles to ensure that it works correctly for everyone. Any issues that are identified during testing should be addressed before deploying the customization to a production environment. Comprehensive testing is essential for ensuring the stability and reliability of the customization.

10. Publish the Customization Project:

Once you are satisfied with the customization, publish the project to apply the changes to your Acumatica instance. Publishing the customization project deploys the changes to the Acumatica instance, making them available to users. This step is the final step in the customization process. Before publishing, it's important to ensure that all testing has been completed and that the customization is working correctly. Publishing the project will apply the changes to the live system, so it's crucial to ensure that everything is in order. After publishing, the Sales Order Number will be displayed in the RefNbr lookup on the Payments and Applications screen, allowing users to apply payments to Sales Orders. The customization project can be easily unpublished if necessary, allowing you to revert the changes if needed. Publishing the customization project completes the implementation process and makes the new functionality available to users.

While providing complete code snippets without the context of your specific Acumatica instance can be challenging, here are some general examples to guide you:

DAC Extension for SOOrder:

using Acumatica.Core.Data;
using PX.Data;
using PX.Objects.SO;

namespace CustomizationProject
{
 [PXNonDBTable]
 public class SOOrderExt : PXCacheExtension<SOOrder>
 {
 #region UsrRefNbr
 [PXString(15, IsUnicode = true, InputMask = "">)]
 [PXUIField(DisplayName = "Sales Order Number")]
 public virtual string UsrRefNbr { get; set; }
 public abstract class usrRefNbr : PX.Data.BQL.BqlString.Field<usrRefNbr> { }
 #endregion
 }
}

Graph Extension for ARPaymentEntry:

using PX.Data;
using PX.Objects.AR;
using PX.Objects.SO;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;

namespace CustomizationProject
{
 public class ARPaymentEntry_Extension : PXGraphExtension<ARPaymentEntry>
 {
 public PXSelectJoin<SOOrder, LeftJoin<ARInvoice, On<ARInvoice.refNbr, Equal<SOOrder.customerOrderNbr>>>, Where<SOOrder.customerID, Equal<Current<ARPayment.customerID>>, And<SOOrder.orderType, Equal<SOOrderTypeConstants.salesOrder>, And<SOOrder.openOrder, Equal<True>>>>> SOOrders;

 public virtual IEnumerable documentsToApply()
 {
 foreach (ARAdjust adj in Base.Adjustments.Cache.Cached)
 {
 if (adj.AdjdDocType == ARDocType.SalesOrder)
 {
 SOOrder order = PXSelect<SOOrder, Where<SOOrder.orderType, Equal<Required<SOOrder.orderType>>, And<SOOrder.orderNbr, Equal<Required<SOOrder.orderNbr>>>>>.Select(Base, adj.AdjdRefNbr, adj.AdjdRefNbr);
 if (order != null)
 {
 yield return order;
 }
 }
 }

 foreach (PXResult<ARInvoice> result in Base.Adjustments.View.SelectMultiBound(new object[] { Base.Document.Current }))
 {
 ARInvoice invoice = (ARInvoice)result;
 yield return invoice;
 }
 }

 public virtual void ARAdjust_AdjdRefNbr_FieldSelecting(PXFieldSelectingEventArgs e)
 {
 if (e.Row == null) return;
 ARAdjust adj = (ARAdjust)e.Row;
 List<object> list = new List<object>();
 List<string> labels = new List<string>();
 //Invoices
 PXStringListAttribute.AppendStrings(list, labels, PXStringListAttribute.GetList(Base.Caches[typeof(ARInvoice)], null, typeof(ARInvoice.refNbr)));
 //Sales Orders
 foreach (SOOrder order in SOOrders.Select())
 {
 list.Add(order.OrderNbr);
 labels.Add(order.OrderNbr);
 }
 e.ReturnState = PXStringListAttribute.SetList(e.ReturnState, list.ToArray(), labels.ToArray());
 }
 }
}

These code snippets provide a starting point for implementing the customization. You will need to adapt them to your specific Acumatica instance and data structures. It's essential to understand the underlying logic and how the code interacts with the Acumatica framework. The DAC extension allows you to add custom fields to the SOOrder table, while the graph extension provides the logic for retrieving and displaying Sales Order information in the reference number lookup. The data view modification ensures that Sales Orders are included in the lookup, and the UI customization makes the Sales Order Number visible on the screen.

Maintainability:

Ensure your customization is maintainable by using clear and concise code. Add comments to explain the purpose of your code and make it easier for others (or yourself in the future) to understand. Maintainability is a crucial aspect of any customization. By writing clear and concise code, you make it easier for others to understand and maintain the customization in the future. Comments are essential for explaining the purpose of the code and how it works. This makes it easier to troubleshoot issues and make changes as needed. Well-maintained customizations are less likely to break during upgrades and are easier to adapt to changing business requirements. The investment in maintainability pays off in the long run by reducing the total cost of ownership and ensuring the long-term viability of the customization.

Performance:

Consider the performance implications of your customization. Avoid writing queries that are too complex or that retrieve too much data. Use indexes to optimize query performance and avoid full table scans. Performance is a critical consideration when customizing Acumatica. Poorly performing customizations can negatively impact the overall performance of the system, leading to slow response times and frustrated users. Complex queries that retrieve large amounts of data can be a major performance bottleneck. It's important to optimize queries by using indexes and avoiding full table scans. Caching can also be used to improve performance by reducing the number of database queries. Thorough testing should be performed to identify and address any performance issues before deploying the customization to a production environment. Optimizing performance ensures that the customization is scalable and can handle the demands of the business.

Upgrades:

Be aware that customizations can be affected by Acumatica upgrades. Test your customization thoroughly after each upgrade to ensure that it still works as expected. Upgrades can introduce changes that affect the behavior of customizations. It's important to be aware of this and to plan for testing after each upgrade. Thorough testing should be performed to ensure that the customization still works as expected and that there are no compatibility issues. Any issues that are identified should be addressed promptly to minimize disruption to the business. Customization projects can be used to manage and deploy customizations, making it easier to upgrade and maintain them. By following best practices for customization, you can minimize the risk of issues during upgrades and ensure the long-term viability of your customizations.

Security:

Ensure that your customization does not introduce any security vulnerabilities. Follow Acumatica's security best practices and avoid storing sensitive data in the database. Security is a paramount concern when customizing Acumatica. Customizations should not introduce any security vulnerabilities that could be exploited by malicious actors. It's important to follow Acumatica's security best practices and to be aware of common security risks. Sensitive data should not be stored in the database in plain text. Encryption should be used to protect sensitive data. Role-based security should be used to control access to customized features. Thorough security testing should be performed to identify and address any potential vulnerabilities. By prioritizing security, you can protect your Acumatica instance and your business from cyber threats.

Adding SOOrder.OrderNbr to the Payments and Applications screen's RefNbr lookup enhances user experience and streamlines payment application in Acumatica. By following the steps outlined in this guide, you can implement this customization effectively. Remember to test thoroughly and consider best practices for maintainability, performance, upgrades, and security. This customization provides a more direct link between payments and sales orders, improving efficiency and reducing the risk of errors. The step-by-step approach outlined in this guide provides a clear path to implementation, covering the necessary technical details and code snippets. By following these guidelines, you can successfully integrate Sales Order Numbers into the reference number lookup, enhancing the functionality of your Acumatica instance. This customization is a valuable addition for businesses that process a high volume of sales orders and payments, providing a more intuitive and efficient way to manage financial transactions. The result is a more streamlined and user-friendly payment application process, contributing to improved financial accuracy and efficiency.

This comprehensive guide has provided a detailed explanation of how to add Sales Order Numbers to the reference number lookup on the Payments and Applications screen in Acumatica. By following the steps outlined in this article, you can successfully implement this customization and enhance the efficiency of your financial operations. Remember to test thoroughly and consider best practices for maintainability, performance, upgrades, and security. With this customization, you can provide a more direct link between payments and sales orders, improving accuracy and streamlining the payment application process. The integration of Sales Order Numbers into the reference number lookup is a valuable enhancement for any business using Acumatica, providing a more intuitive and efficient way to manage financial transactions. This customization empowers users to quickly identify and select the relevant sales order when applying payments, reducing the risk of errors and improving overall efficiency. The result is a more streamlined and user-friendly payment application process, contributing to improved financial accuracy and efficiency.