Data lookup utils (#888)

* Create DataLookupUtils.js

* Create readme.md

Author: ajcooper72

Script Includes/Data Lookup Table Utils/DataLookupUtils.js

@@ -0,0 +1,109 @@
+var DataLookupUtils = Class.create();
+
+DataLookupUtils.prototype = {
+    initialize: function (tableName, sortByColumn) {
+        this.tableName = tableName;
+        this.columnNames = this._getColumnNames(tableName);
+        this.queryColumns = this.columnNames;
+
+        sortByColumn = sortByColumn || false;
+        this.sortColumn = sortByColumn ? DataLookupUtils.SORT_BY_COLUMN : DataLookupUtils.SORT_BY_ORDER; // optional, use the field being retrieved or the built in order field
+    },
+
+    /**
+     * query lookup data
+     * can accept either an array of keys, or multiple parameters
+     * e.g
+     *    getLookupData('key1', 'key2', 'key3');
+     *    getLookupData(['key1', 'key2', 'key3']);
+     */
+    getLookupData: function (_keys) {
+        var keys = [];
+        if (_keys && typeof _keys != 'object') {
+            for (var _arg in arguments) {
+                keys.push(arguments[_arg]);
+            }
+        } else {
+            keys = _keys;
+        }
+
+        if (keys.length >= this.queryColumns.length) {
+            NiceError.raise(gs.getMessage("Too many keys ({0}) provided.  Maximum is {1}", [keys.length.toString(), (this.queryColumns.length - 1).toString()]));
+        }
+
+        try {
+            var fieldIdx = 0;
+            var fieldName = this.queryColumns[fieldIdx];
+            var gq = new global.GlideQuery(this.tableName)
+                .where('active', true);
+
+            if (keys.length > 0) {
+                // loop through the keys
+                keys.forEach(function (key, idx, arr) {
+                    gq = gq.where(fieldName, key);
+                    fieldName = this.queryColumns[++fieldIdx];
+                }, this);
+            }
+
+            gq = gq.orderBy(this.sortColumn == DataLookupUtils.SORT_BY_COLUMN ? fieldName : 'order')
+                .whereNotNull(fieldName)
+                .select(fieldName)
+                .map(function (_x) {
+                    // just need the data, not the other stuff
+                    return _x[fieldName];
+                })
+                .reduce(function (arr, e) {
+                    // remove duplicates
+                    if (arr.indexOf(e) == -1) arr.push(e);
+                    return arr;
+                }, []);
+
+            return gq;
+        } catch (e) {
+            NiceError.raise(e);
+        }
+    },
+
+    /**
+     * override the columns to use for lookups
+     * 
+     */
+    setColumns: function (columns) {
+        if (columns.length == 0) return;
+
+        this.queryColumns = [];
+        columns.forEach(function (_col) {
+            if (this.columnNames.indexOf(_col) > -1) {
+                this.queryColumns.push(_col);
+            } else {
+                NiceError.raise(gs.getMessage('Cannot find column {0}.  Valid columns are {1}', [_col, this.columnNames.join(', ')]));
+            }
+        }, this);
+
+    },
+
+    /**
+     * build the list of column names for the table
+     * use the default system view for the table and exclude all system and inherited fields
+     * column order determines key lookup
+     */
+    _getColumnNames: function () {
+        return new global.GlideQuery('sys_ui_list_element')
+            .where('list_id.name', this.tableName)
+            .where('list_id.view', 'Default view')
+            // ignore any system or inherited fields from the table
+            .where('element', 'NOT IN', ['sys_class_name', 'sys_created_by', 'sys_created_on', 'sys_id', 'sys_mod_count', 'sys_name', 'sys_package', 'sys_policy', 'sys_scope', 'sys_updated_by', 'sys_updated_on', 'sys_update_name', 'active', 'order'])
+            .whereNull('list_id.sys_user') // make sure we get the system view
+            .orderBy('position')
+            .select('element')
+            .reduce(function (arr, e) {
+                arr.push(e.element);
+                return arr;
+            }, []);
+    },
+
+    type: 'DataLookupUtils'
+};
+
+DataLookupUtils.SORT_BY_ORDER = 0;
+DataLookupUtils.SORT_BY_COLUMN = 1;

Script Includes/Data Lookup Table Utils/readme.md

@@ -0,0 +1,37 @@
+# Data Lookup Table Utils
+
+This script include provides a quick method of looking up data from any table extended from dl_matcher (Data Lookup Matcher Rules).  
+
+It will build a list of the columns for the specified table and then allow you to query based on an array of values.
+
+For example, using the dl_u_priority table we could lookup the Urgency values for a given Impact as follows;
+
+```javascript
+var lib = new global.DataLookupUtils("dl_u_priority")
+
+var lookupData = lib.getLookupData("1");
+gs.info(lookupData);
+```
+This will return *1,2,3*.
+
+By also passing in a second value we can filter on Urgency and Impact;
+
+```javascript
+var lib = new global.DataLookupUtils("dl_u_priority")
+
+var lookupData = lib.getLookupData(["1", "2"]);
+gs.info(lookupData);
+```
+This will return *2*.
+
+We could also ignore the Impact column and lookup Priority for a given Urgency by setting our own lookup columns;
+
+```javascript
+var lib = new global.DataLookupUtils("dl_u_priority")
+lib.setColumns(["urgency", "priority"]);
+
+var lookupData = lib.getLookupData(["3"]);
+gs.info(lookupData);
+```
+This will return *3,4,5*
+