10 Search Filters in SuiteScript 2.0

Created: July 3, 2017

In this edition, we explore creating our own Searches and working with Search Filters in SuiteScript 2.0.

To coincide with this series of articles on Searching, I have also created a series of SuiteScript cookbooks focused on Searching. If you are tired of NetSuite's unrealistic or broken examples, then these cookbooks are for you.

Creating Searches and Filters

We begin by looking at the APIs for creating first a Search then a Filter. In SuiteScript 1.0 we could create an nlobjSearch instance with nlapiCreateSearch. In 2.0, we utilize the N/search module's create method, which behaves much like its 1.0 counterpart. As we create the search, we can specify its Record Type, its Filters, and its Columns.

In order to specify those Filters, we use the N/search module's createFilter method. As you can see there are a lot of options when creating a Filter; we will focus here on the most commonly used of those.

As always, these APIs are best explored through an example. Let's build a Search that finds all active Employees hired within the past 12 months.

Using createFilter

// 1.0
nlapiCreateSearch("employee", null,
    [
        new nlobjSearchFilter("hiredate", "within", "lastRollingYear"),
        new nlobjSearchFilter("isinactive", "is", "F")
    ]
).runSearch().forEachResult(processResult);

function processResult(result) {
    // ...
    return true;
}

// 2.0 - Console
require(["N/search"], function (s) {
    s.create({
        type: s.Type.EMPLOYEE,
        filters: [
            s.createFilter({
                name: "hiredate",
                operator: s.Operator.WITHIN,
                values: "lastRollingYear"
            }),
            s.createFilter({name: "isinactive", operator: s.Operator.IS, values: "F"})
        ]
    }).run().each(processResult);

    function processResult(result) {
        // ...
        return true;
    } 
});

We'll be exploring Search Columns in their own article, so we won't worry about specifying any here.

As the Intro to Searching article already describes the APIs for processing Search Results in detail, what you do with these Search Results is left as an exercise for you.

Using Object Descriptors

In SuiteScript 2.0, there are actually three different approaches we can use when specifying Search Filters. We've already seen how to use the createFilter method, which is the most verbose of the three.

The second approach is to simply use a plain Object with the same properties as we specify in createFilter. Let's modify our previous example to use this approach. Essentially, all we need to do is remove the call to createFilter and leave the Object we were passing to it.

require(["N/search"], function (s) {
    s.create({
        type: s.Type.EMPLOYEE,
        filters: [
            {
                name: "hiredate",
                operator: s.Operator.WITHIN,
                values: "lastRollingYear"
            }, {
                name: "isinactive",
                operator: s.Operator.IS,
                values: "F"
            }
        ]
    }).run().each(processResult);

    function processResult(result) {
        // ...
        return true;
    }
});

Using Filter Expressions

The third approach for specifying Search Filters is through Filter Expressions. If you are already familiar with Search Expressions from 1.0, they have not changed in 2.0; the syntax remains the same.

require(["N/search"], function (s) {
    s.create({
        type: s.Type.EMPLOYEE,
        filters: [
            ["hiredate", s.Operator.WITHIN, "lastRollingYear"], "and"
            ["isinactive", s.Operator.IS, "F"]
        ]
    }).run().each(processResult);

    function processResult(result) {
        // ...
        return true;
    }
});

Filter Expressions are my preferred means of specifying Filters as they are the most flexible, powerful, and concise of the three approaches. There is quite a bit more that Filter Expressions can accomplish, but we'll leave that for a much more advanced and in-depth article all its own.

Filter Manipulation

We've seen how to specify our Search Filters when we create a Search from scratch, but how do we modify the Filters on an existing Search?

SuiteScript 1.0 provided many methods for retrieving and manipulating Search Filters. In 2.0, I believe it gets quite a bit simpler.

define(["N/search"], function (s) {
    var mySearch = s.load({
        // ...
    });
});

In 1.0, we had to use several methods on the nlobjSearch instance to manipulate either the Filters or the Filter Expression. In 2.0, the Filters are accessible via the filters property which is an Array of s.Filter Objects. We can manipulate this property directly as a normal JavaScript Array.

This means we can use standard Array methods like push and concat to add Filters to the Array; we could use methods like pop or shift to remove Filters from the Array. There was no corresponding removal functionality in 1.0.

We can also manipulate the Filters as a Filter Expression directly via the filterExpression property.

We have still barely scratched the surface of Searches in SuiteScript 2.0; if you're looking to accelerate your mastery of searching in SuiteScript with realistic, fully functioning examples, check out my Searching with SuiteScript cookbooks.