README

Module for building ServiceNow encoded queries

Docs for formatting are here

Usage

Querying

To get a query string, you should add a query to the builder, then build it. The addQuery function will do a simple equals comparison when no comparator is provided.

var EncodedQueryBuilder = require('sn-encoded-query').EncodedQueryBuilder;
var builder = new EncodedQueryBuilder();
builder.addQuery('field','value');
builder.build(); // Returns field=value

To change the comparison type, put a comparator as the second parameter.

builder.addQuery('field',<comparator>,'value');

And

There are two ways to add an 'And' query. Both of these will render the same output.

builder.addQuery('first_name','Foo');
builder.addQuery('last_name','Bar');
// Result: first_name=Foo^last_name=Bar

builder.addQuery('first_name','Foo').and('last_name','Bar');
// Result: first_name=Foo^last_name=Bar

Or

There are two ways to add an 'Or' query, but they will give different results when built. This is to allow for more complex querys to be built.

builder.addQuery('first_name','Foo');
builder.addOrQuery('last_name','Bar');
// Result: first_name=Foo^NQlast_name=Bar

builder.addQuery('first_name','Foo').or('last_name','Bar');
// Result: first_name=Foo^ORlast_name=Bar

The difference in rendering is to allow for Or's for a single part of the query, or for larger sections. For example, say you need to find all active users named 'Ben' or 'Simon', as well as all inactive users named 'Emma' and 'Brenda', ServiceNow would show the following:

ServiceNow example

The same query is created below:

builder .addQuery('active','true')
        .and('first_name','Foo')
        .or('first_name','FooBar');

builder .addOrQuery('active','false')
        .and('first_name','Foo')
        .or('first_name','FooBar');

// Result: active=true^first_name=Foo^ORfirst_name=FooBar^NQactive=false^first_name=Foo^ORfirst_name=FooBar

Order By

You can add on as many orderby clauses as you like. They will be prioritized by the order they were added.

builder.orderBy('field');
builder.orderByDesc('field');

Group By

You can have one column specified to group by. If you add a second group by, it will override the first.

builder.groupBy('field');

Comparators

The comparators are labeled the same as they are in ServiceNow. To use them you must require them and then pass them to the function.

var StartWith = require('sn-encoded-query').Comparators.StartWith;

builder.addQuery('field', StartsWith, 'val');
builder.build();
// Result: fieldSTARTSWITHval

The list of comparators are:

Between
DateLessThan
DateMoreThan
Direction
Dynamic
EndsWith
GreaterThan
GreaterThanField
GreaterThanOrEqualsField
GreaterThanOrEqualTo
In
Is
IsAnything
IsEmpty
IsEmptyString
IsNot
IsNotEmpty
IsNotSameAs
IsSameAs
LessThan
LessThanField
LessThanOrEqualsField
LessThanOrEqualTo
Like
NotIn
NotLike
NotOn
On
Relative
StartsWith
Trend

Not Implemented

There are a few features that are not implemented yet. I have not yet come across a need for these yet but once I do I will add them in.

Related List Queries
SINCE
MATCH_PAT
MATCH_RGX
INSTANCEOF
VALCHANGES
CHANGESFROM
CHANGESTO
sum
avg
min
max

Contributing

Feel free to fork then submit a pull request here.

Usage no npm install needed!