Helper Functions

Helper refers to a Java Class providing a set of particular Feeder methods. Calling Helper functions always requires the writing of Helper.functionName().

List of available Helper-functions:

• ensureUnique(obj, name, value) (2 versions)
• formatDate(obj, pattern)
• formatNumber(obj, pattern)
• getByKey(objType, attribute, value)
• getByKey(objType, attribute, value, boolean)
• getByQuery(objType, query)
• getDefaultValue(obj, attribute)
• getEffectedDate(pattern)
• getIncrementalID(objType, attribute, start) (2 versions)
• getUUID()
• getPeriod(date, time unit) [v2]
• parseDate(obj, pattern)
• parseNumber(obj, pattern)

---

ensureUnique(obj, name, value)

Goal

Compose a USERNAME (pattern: firstname.lastname)

Plan

• Validate that both fields FIRSTNAME and LASTNAME are filled.
• Concatenate the values using a dot.
• Convert the unique username to lower case letters.
• In case of another person with the same names, an incremented number will be added to the username.
• Default separator of this function is an underscore (_).

Result

dave.miller, dave.miller_1, dave.miller_2, etc.

var fn = obj.get('FIRSTNAME');
var ln = obj.get('LASTNAME');
if (fn && ln) {
    var value = fn + '.' + ln;
    return Helper.ensureUnique(obj, 'USERNAME', value.toLowerCase().replace(/[\^0-9a-z.]/g,''));
}
return null;

---

ensureUnique(obj, name, value, separator)

Goal

Freely determine a separator before uniqueness-enumeration.

Plan

Utilize the Feeder’s ensureUnique()-function with 4 arguments.

Result

max.freitag, max.freitag-1, max.freitag-2, etc.

Helper.ensureUnique(obj, 'USERNAME', value.toLowerCase().replace(/[\^0-9a-z.]/g,''), '-');

---

formatDate(obj, pattern)

Goal

Format a date according to your needs and return a String

Plan

• Validate that the HIREDATE field is filled
• Then format the value in the desired way, here: “dd.MM.yyyy”
• Available patterns can be found on the SimpleDateFormat site.

Result

Instead of 11/05/2014, a stringed date will appear as 05.11.2014

var date = obj.get('HIREDATE');
if (date != null || date != '') {
    return Helper.formatDate(date, 'dd.MM.yyyy');
}

---

formatNumber(obj, pattern)

Goal

• Format a number entered in a Number field
• Display the formatted number in a calculated Text field of data type Text

Plan

Format the given object based on the given pattern. The following characters can be used to describe a pattern:

Pattern	Effect
#	value is optional
0	when empty filled with zero
#0	1; 2; 10
00	01; 02; 10
#,##0.#	1; 1,200
#,##0.0	1.0; 1,200.1

Result

• The entered value ‘3’ will be displayed as ‘03’
• Please be aware that the data type will be a Text/ String and NOT a Number

var input = obj.get('NUMBERFIELD');
if(input){
    return Helper.formatNumber(input,'00');
}

---

getByKey(objType, attribute, value)

Goal/ Common Use Case

• Looking up a particular user record using the scripting feature
• Commonly this is done in imports or exports (!)

Plan

• Use the getByKey-function
• Use a strong attribute with unique values (e.g. EMAIL or USERID)

Important

Flag the strong attribute with the Create Index option for accelerating the search!

Result

• This example will look up an employee in the SFUser object using the EMAIL address field and the lookup value max.mayer@acme.com
• If a matching data record is found, the USERID of the record is read out and written to the MANAGER field of the current record that is being created/updated
• If the loop up values are not 100% unique, then Feeder will return the first record found (e.g. there are two John Doe’s in your data set)

var emp = Helper.getByKey('SFUser','EMAIL','max.mayer@acme.com');
if (emp != null) {
    obj.set('MANAGER', emp.get('USERID'));
}
else{..}

Hint

The sample code is taken from an import script (!). You can recognize it by the obj.set(‘..’).

---

getByKey(objType, attribute, value, boolean)

Goal/ Common Use Case

• Configure a calculated field (!) that reads from another field
• Set the boolean to true for allowing the lookup

Plan

• Get the record’s manager record
• Extract the manager’s USERID in order to look her up in the database
• Then her position code gets pulled and written to the calculated field

Important

Flag the strong attribute with the Create Index option for accelerating the search!

try {
var hasManager = obj.get('MANAGER');

if (hasManager) {
    var mgrID = hasManager.get('USERID')
    var mgrRecord = Helper.getByKey('SF_User', 'USERID', mgrID, true);

    if (mgrRecord) {
        var mgrPosition = mgrRecord.get('POSITIONCODE');
        if (mgrPosition) {
            return toStr(mgrPosition);
        }
    }
}
} catch (e) {
  return 'error in field calculation';
}

Important

For field calculations it is strongly recommended to use the try-catch-statements. This will allow closing a record although an error in the calculation might have occurred.

---

getDefaultValue(obj, attribute)

Setup

• COMPANY and COMPANY_DESC attributes
• The value in COMPANY_DESC depends on the value in COMPANY and might be hidden
• Your enterprise has a multitude of companies all over the word

Goal/Result

You do not want to fill in all standard values of COMPANY_DESC-riptions but you want a script to realize this behavior.

Plan

Within the COMPANY_DESC attribute, tick ‘Calculated’,’on every update’ and ‘Script’. Finally add the following line of code.

return Helper.getDefaultValue(obj,'COMPANY_DESC');

---

getByQuery(objType, query)

Goal

Find the first data set that matches the query argument.

Note

• The function is inept for mass queries, as it will return the very first match only.
• Please flag the named attributes with Create Index for accelerating the search!

var result = Helper.getByQuery('SFUser', {
 'COUNTRY' : 'Germany',
 'CITY' : 'Munich'
});

var result = Helper.getByQuery('SFUser', {
 '$or' : [
  {'COUNTRY' : 'Germany','CITY' : 'Munich'},
  {'COUNTRY' : 'Denmark','CITY' : 'Copenhagen'},
 ]
});

---

getEffectedDate(pattern)

Result

• Get the effective date and format it according the indicated pattern.
• The result will be a String and NOT a true Date.

Showcase

If the effective date is not explicitly indicated within an employee entry, it will behave as follows.

Prerequesites

Time slices for:

• July (01.07. - 31.07.)
• August (01.08. - 31.08)[current]
• September (01.09. - 30.09.)
• “Today’s” date: 24.08.2014

Use Cases	Function returns	Example
Time slices module has not been activated	today’s date	24.08.2014
No time slices have yet been created	today’s date	24.08.2014
Multiple time slices, working in the current time slice	today’s date	24.08.2014
Multiple time slices working in an older time slice (July)	the last day of this time slice	31.07.2014
Multiple time slices working in a newer time slice (September)	the first day of the time slice	01.09.2014

var efDate = Helper.getEffectedDate('dd.MM.yyyy');

Another example can be found within the Export Data section.

---

getIncrementalID(objType, attribute, start)

Hint

When testing the upload of employees in the Browser frontend (Test Button), a random incremental ID will be used in order to not waste IDs from the current numerical series! If Mapping by Script is used, this is achieved by using the specific isTestImport check variable.

Goal

Determine the global starting point of incremented IDs. Use this function when you want the start to be different from 0, otherwise use the flagging option “Increment”.

Plan/Prerequesite

1. Configure the attribute according to the following screenshot.
2. Enter the object type (objType) and attribute name (attr) as Strings (meaning in quotes)
3. Enter the start value as Number (meaning without the quotes).

Result

Function returns a Number. The first employee’s USERID will be 14, the 2nd employee`s 15 etc.

return Helper.getIncrementalID('SF_User', 'USERID', 14);

Note

The attribute name (attr) has to be identic to the technical name of the attribute that you are currently configuring. Furthermore, the attribute’s data type has to be Number too!

---

getIncrementalID(objType, attribute, start, pattern)

Hint

When testing the upload of employees in the Browser frontend (Test Button), a random incremental ID will be used in order to not waste IDs from the current numerical series! If Mapping by Script is used, this is achieved by using the specific isTestImport check variable.

Goal

Determine the global starting point of incremented IDs and determine their pattern, e.g. in case that you want leading zeros.

Plan

1. Configure the attribute according to the following screenshot.
2. Enter the object type (objType), attribute name (attr) and pattern as Strings (meaning in quotes)
3. Enter the start value as Number (meaning without the quotes).

Result

Function returns a String, thus the attributes data type has to be a String too! The first employee’s USERID will be 010001.

return Helper.getIncrementalID('SF_User', 'USERID', 10001 , '000000');

---

getUUID()

Goal

Conform a unique ID to certain desires and output a String. For example no separators and only capital letters shall be used.

Plan

Create a Universally Unique Identifier using the Helper.getUUID() function. Then apply pattern matching and replace all “-” characters. Ultimately cast all letters to upper case.

Result

57ced62f-8a49-4c20-b5ec-587a57a139c1 will be a formatted: 57CED62F8A494C20B5EC587A57A139C1.

return toStr(Helper.getUUID()).replace(/-/g,'').toUpperCase();

---

getPeriod(date, time unit) [v2]

Goal

• Calculate the period since a given date.
• The time unit can be year or month or day

Plan

• Create a new NUMBER field, for ex. named “AGE”
• Select the Calculated flag + On every update + Script options
• Fill in the following code

Result

• Feeder will return the number of years up to today

var dateofBirth = obj.get('DOB');
if (dateofBirth != null && dateofBirth != '') {
  return Helper.getPeriod(dateofBirth, 'year');
}
return 0; // optional

---

parseDate(obj, pattern)

Goal

Format date and get a java.util.Date back.

Plan

Pass a desired pattern.

Result

Instead of a stringed “11/13/2014”, a true Date will be displayed as 13.11.2014.

for (var i = 0; i < headers.length; i++) {
    if (headers[i] && columns[i]) {
        var key = toStr(headers[i]);
        var col = toStr(columns[i]);
        switch (key) {
           case 'HIREDATE' :
           var date = Helper.parseDate(col, 'dd.MM.yyyy');
           if(date != null) {
              obj.set('HIREDATE', date);
           break;
           }
        default:
           obj.set(key, col);
           break;
        }
    }
}

---

Hint

“I want to implement a field that displays a date…”

Possible solution: The field type is TEXT/STRING and the field gets calculated.

var dd = new Date();
return dd.toString();     /* Tue Sep 23 2014 17:07:15 GMT+0200 (CEST) */

var d = new Date();
return d.toUTCString();   /* Tue, 23 Sep 2014 15:15:00 GMT */

var d = new Date();
return d.toDateString();  /* Tue Sep 23 2014 */

var d = new Date();
var n = d.toISOString();  /* 2014-09-23T15:18:13.603Z */

---

parseNumber(obj, pattern)

Goal

• Convert a de-facto String representation (e.g.”10011,5”) into a real data type number.
• The data type of the target field is Number.
• The column header name of the import file is the same as the target field’s name (TOTAL_CASH).

Plan

• Use the parseNumber(obj,pattern) function in the import script.
• obj: The object to parse. The object can be: Number or a different object where the toString() method returns a Number representation.
• pattern: The pattern to be applied.
• /D: specifies the decimal separator.
• /G: specifies the group separator.

Result

In the excerpt below (see Sample Import Script (Manager Lookup)), the number value will be parsed and formatted with dots as group separator and comma as decimal separator (10.011,5).

var i, name, value
for (i = 0; i < headers.length; i++) {
     name = toStr(headers[i]);
     value = columns[i];
     switch (name) {
        //other cases

     case 'TOTAL_CASH':
        obj.set(name, Helper.parseNumber(value,'#,##0.#/D,/G.'));
        break;
    }
    break;
    default:
        obj.set(name, value);
}