Technical Tuesday: Universal Search in Acumatica

For this week’s Technical Tuesday, I will be showing how to configure the universal search capabilities available inside Acumatica. Universal search is initiated from the Search Bar in the top-left of all Acumatica screens and provides rapid access to screens, files, wikis, and indexed objects inside Acumatica.

Environment: 5.30.1138

Data: SalesDemo demo data from partner portal

Scenario Overview

Business Problem

Finding data inside your ERP system is critical. The speed at which you can find information is directly proportional to the usefulness of your ERP (Enterprise Resource Planning) implementation.

Acumatica provides a Universal Search bar that helps you navigate directly to objects contained in the software. You can search screen titles, files, wikis, and indexed objects in Acumatica.

The screen above shows the wiki article (Help > Interface Guide > Search > Searching in Acumatica ERP), where you can learn the capabilities of the universal search feature.

Acumatica Universal Search balances the need to find data against processing speed and server load. By selectively indexing data objects, Universal Search minimizes processing overhead without impacting results. For example, indexing the country field on a contact record will not be useful if all of your customers are located in the United States.

The decision of what to index will vary significantly by customer. For a local electronics distributor, fields like customer name and inventory are more important that the postal code. A distributor dealing with big ticket serialized items will want to index the serial number field.

Demonstration Scenario

Out of the box, Acumatica search can find many business objects maintained in the database. Based on your needs, you can extend the global search engine capabilities to include fields like postal code and serial number.

This article describes how to modify which business objects are indexed within Universal Search so you can serve the needs of specific customers.

Acumatica Implementation

In this article, we split the job into two tasks:

1. Understand which fields are indexed
2. Understand how to change the default indexing

Step 1: Understanding which Fields Are Indexed

Universal Search includes selected fields. If you know what to look for, you can see which fields are indexed.

• Each object in Acumatica can have a field called NoteID. The NoteID contains information about which fields in the object are indexed.
• In NoteID there is a special attribute called PXSearchable that contains information about which fields are searchable.

To illustrate, let’s look at indexing in the Contact object. To do this, follow these steps …

a) Create a customization project. Navigate to System > Customization > Manage > Customization Projects (SM.20.45.05) and create a new project. I created a project called UniversalSearch.

b) Select the screen you want to customize. Double click the UniversalSearch project to open it. Then, select the option to ‘Customize Existing Screen.’ Select the screen: Organization > Customer Management > Work Area > Manage > Contacts (CR.30.20.00).

c) Select the object you want to learn about. There are many objects available to Acumatica screens. If you click the ‘Add Data Fields’ tab, you can see a field called Data View with a drop down box. This drop down contains all the data objects that are available to the screen (a.k.a. the screen schema). The ‘Contact’ data view is the one that we are interested in. To get that object, click the ‘Attributes’ tab, select ‘ Form: Contact,’ and click ‘view source’ as illustrated below.

d) Open the NoteID field. Within the Source Code, find the NoteID field and expand it.

Here is the text from the NoteID field:

#region NoteID

public abstract class noteID : PX.Data.IBqlField { }

{ typeof(Contact.contactType), typeof(Contact.displayName) },

new Type { typeof(Contact.eMail), typeof(Contact.phone1), typeof(Contact.phone2), typeof(Contact.phone3), typeof(Contact.webSite) },

WhereConstraint = typeof(Where<Current, NotEqual, And<Current, NotEqual>>),

Line1Format = “{0}{1}{2}”, Line1Fields = new Type { typeof(Contact.salutation), typeof(Contact.phone1), typeof(Contact.eMail) },

Line2Format = “{1}{2}{3}”, Line2Fields = new Type { typeof(Contact.defAddressID), typeof(Address.displayName), typeof(Address.city), typeof(Address.state), typeof(Address.countryID) }

)]

[PXNote(

DescriptionField = typeof(Contact.displayName),

Selector = typeof(Search<Contact.contactID, Where<Contact.contactType, Equal, Or<Contact.contactType, Equal>>>),

ShowInReferenceSelector = true)]

public virtual Guid? NoteID { get; set; }

e) Interpret the data. The NoteID contains several pieces of information related to how the data is indexed and displayed. There are several parameters:

1. Category (SearchCategory.CR). This describes the area in Universal Search to which the Contact search belongs – the customer management module in this case. If you begin your search in customer management and select the first option these results will be returned. If you search within inventory or sales orders, the Contact object will not be included. If you “Search for in All Entities” then all results are included no matter where you are in the system.
2. Title (“{0} {1}”). This describes how the title text is displayed for results.
3. Title Text (new Type { typeof(Contact.contactType), typeof(Contact.displayName) }). This parameter describes the fields which replace the {0} and {1} in the title description. In this case the Contact Type and Display Name are used.
4. Index Fields (new Type { typeof(Contact.eMail), typeof(Contact.phone1), typeof(Contact.phone2), typeof(Contact.phone3), typeof(Contact.webSite) }). These are the fields that are indexed for the search. This is the parameter to use if you want to add or remove fields from the Universal Search! In this case you can see that Email address, phone 1, phone 2, phone 3, and website are all included in Universal Search results. First name and last name do not need to be included because they are key fields for the table and are therefore automatically indexed.
5. Programming Stuff (WhereConstraint = typeof(Where<Current, NotEqual, And<Current, NotEqual>>)). Not important for our discussion here.
6. Detail Line 1 (Line1Format = “{0}{1}{2}”). This describes line 1 of the search results.
7. Detail Line 1 Text (Line1Fields = new Type { typeof(Contact.salutation), typeof(Contact.phone1), typeof(Contact.eMail) }). These values replace the parameters in the Detail Line 1 format.
8. Detail Line 2 (Line2Format = “{1}{2}{3}”). This describes line 2 of the search results.
9. Detail Line 2 Text (Line2Fields = new Type { typeof(Contact.defAddressID), typeof(Address.displayName), typeof(Address.city), typeof(Address.state), typeof(Address.countryID) }). These values replace the parameters in the Detail Line 2 format.

Step 2: Including an additional object in universal search

In this example, we add the position field to the index so we can search based on position. To begin, search for ‘solutions representative’ in Universal Search. The search should not return any results.

a) Find data element name. Navigate to the screen where the field you want to index resides. In this case it is Organization > Customer Management > Work Area > Manage > Contacts (CR.30.20.00). Then click Customization in the upper right and select Inspect Element. Move the question mark cursor over the field you want to index and click it.

The result is below.

As you can see, the Position field is located in the Contact Data Class … this means we can add it to the existing index we reviewed in the prior section. The name of the field to index is Contact.Salutation.

b) Add data element to index. After determining the object (PX.Objects.CR.Contact) and our field name (Contact.Salutation), we can modify the data access class (DAC). To do this:

1. Open the UniversalSearch customization, click Data Access, select the “+” sign to add an existing data table. In the pop-up box, select TableName “PX.Objects.CR.Contact.”

2. Click Add Field -> Change Attributes of Base Field, then select the NoteID field. See screen shots below.

3. In Customize Attributes select ‘Replace Original’ and add the new field you want to index in the appropriate location. See below for the coding change. It is a good idea to include the field you are indexing in the results. In this case the Position field is already included on line 1.

4. To activate your change, publish the UniversalSearch customization.

Step 3: Rebuild Full-Text Entity Index

After establishing the new search criteria, Acumatica will automatically index any new values added to the Position field in the Contact record. To index all existing data, we need to rebuild the full-text entity index.

To do this, navigate to System > Management > Manage > Rebuild Full-Text Entity Index and select the Contact entity or simply Process All.

Now, repeat the search you did before … and … RESULTS!

Conclusion

The Acumatica search engine is powerful, flexible, and efficient. As demonstrated, you can add and remove fields from the Universal Search indexing engine as required by users.

The Universal Search engine makes it easy to find:

• Screens in Acumatica
• Files based on the file name
• Wiki articles such as Help Files
• Business Objects

Most importantly, you can easily navigate to the business objects returned by Universal Search. With one click the appropriate screen and data record is displayed for taking the next action.

APPENDIX: Enabling Full-Text Search

Acumatica takes advantage of database capabilities to perform ‘semantic searches.’ A semantic search is an intelligent search that takes into account the context of your search terms to return the most relevant results.

For example, if you type ‘yellow poplar bark’ into the search bar, a semantic search algorithm will favor an article describing types of tree bark over an article that talks about dogs.

Semantic search is enabled for standard installations of MySQL and Microsoft SQL Server – except for Microsoft SQL Express. To enable or disable semantic search on Microsoft SQL Server, view this article: http://sqlish.com/installing-full-text-search-on-sql-server/ or http://stackoverflow.com/questions/12525106/sql-server-2012-install-or-add-full-text-search.

Context searches based on where you are located in the Acumatica application will only work if Full-Text Search is enabled. For example:

Search for ‘bartend’ in Accounts Receivable where full-text search IS NOT enabled:

In all entities …

Compare with searching for ‘bartend’ in Accounts Receivable where full-text search IS enabled:

Note that results are returned in the context of where you are searching.