FSM Field Mapping Reference
This reference is intended for administrators and developers who define field mappings and mapping formats.
In an object map, each property name identifies a returned value. Its mapping string identifies the NetSuite search column or formula that supplies that value.
{
"record": "task",
"filters": ["internalid", "anyof", "${event.internalid}"],
"map": {
"id": "internalid",
"title": "title",
"caseId": "case.internalid",
"statusText": "status#"
}
}
This example applies to a CRM Task event. Each returned object has the property names id, title, caseId, and statusText. The joined search column case.internalid supplies the linked case ID. The # flag reads the displayed status text instead of its stored value.
The following table shows how the map's shape affects the result.
|
Map Shape |
Result from a Resolved Search |
|---|---|
|
A string, such as |
An array of individual values, one for each returned row. |
|
An object, such as |
An array of objects with the configured property names. |
|
An array, such as |
An array containing an array of mapped values for each returned row. |
A search returning no rows produces an empty array. The Select's selected value is separate from its options: returning choices doesn't map the chosen value back to a record field.
For more information about field mapping, see the following topics:
Mapping Flags
Flags change how a mapping is read or written. Their placement on the read or write side of a mapping matters.
|
Flag |
Effect |
|---|---|
|
|
Read the field's display text. On a write mapping, set the field by text instead of its stored value. |
|
|
Read or write an array of values, such as a multiselect field. The |
|
|
Identify the primary value in a mapped object, such as the ID in a Select value. |
|
|
Merge search rows with the same mapped key into one result object. |
|
|
Sort the search column in ascending order. |
|
|
Sort the search column in descending order. |
|
|
Group the search column. |
|
|
Count the search column. |
|
|
Sum the search column. |
|
|
Average the search column. |
|
|
Return the minimum search-column value. |
|
|
Return the maximum search-column value. |
|
|
Force a field write even when its current value compares equal to the supplied value. |
The | separator assigns different read and write mappings. For information about separate read and write mappings, see Reading and Saving Different Fields.
The = and * flags control the enclosing mapped object through its first string mapping. Place the primary or merge-key mapping first in that object. Reordering these entries can change the result even when the individual mapping strings remain unchanged.
Mapping Formats
A format suffix can convert a mapped value for reading, writing, or filtering. For example, "internalid[integer]" reads an integer, and "isinactive[boolean]" reads a Boolean value.
The following table lists common formats.
|
Suffix |
Purpose |
|---|---|
|
|
Treat the value as text. |
|
|
Convert a NetSuite checkbox value to or from a Boolean value. |
|
|
Convert a whole-number value. |
|
|
Convert a decimal-number value. |
|
|
Apply List/Record value formatting and filtering. |
|
|
Apply the corresponding temporal format. |
Choose a format appropriate to the NetSuite field and the receiving element. A format doesn't make an invalid field ID valid or change the underlying NetSuite field type. For information about temporal values and element validation, see FSM Mobile Element Reference.
Mapping Select Values
A single Select uses an object containing an id and a label. A Select with multiple: true uses an array of these objects. Its options and its saved value must have compatible shapes.
Single Selection
The following map entry reads an FSM Task Type selection and writes the selected ID back to the task:
{
"taskType": {
"id": "=custevent_nx_task_type",
"label": "custevent_nx_task_type#|"
}
}
The id entry is first. The = flag identifies it as the object's primary value. FSM returns the selection object when the ID is populated. An empty primary value produces null. On save, the selected ID is written to custevent_nx_task_type. The label is for display.
The = flag is not required simply to read an ordinary field's stored value. It is used here to control how the selection object is loaded and saved.
Multiple Selections
The following example illustrates a custom multiselect field:
Replace custrecord_example_services with the multiselect field ID on the resource's record type.
{
"selectedServices": {
"id": "custrecord_example_services=[]",
"label": "custrecord_example_services#[]|"
}
}
The ID mapping combines = and []. FSM pairs the returned IDs and labels to produce an array of selection objects. Saving the value writes the selected IDs to the multiselect field. An empty selection is represented by an empty array.
This mapping is for a multiselect field. A Table element representing sublist lines needs a separate array mapping. For information about mapping table rows to NetSuite sublists, see Mapping Table Values to Sublists.
Formulas in Field Maps
Prefer direct or joined field mappings that provide the required value. For guidance on reducing formulas and replacing formula filters, see Reducing Formulas in FSM Searches.
A formula mapping starts with the NetSuite formula column type, followed by : and the formula. Use a formula type appropriate to the returned value, such as formulatext for text or formulanumeric for numbers.
{
"label": "formulatext:{title}||' ('||{internalid}||')'",
"notesPreview": "formulatext:SUBSTR({message},1,250)"
}
The first entry combines the task's title and ID into display text. The second returns the first 250 characters of its message. Both entries are read-only because neither entry has a write destination.
The || inside a formula concatenates SQL text values. It differs from the single | that separates a mapping's read and write sides. Formula field references, such as {message}, also differ from FSM template tags, such as ${event.internalid}.
NetSuite evaluates search formulas. FSM Mobile expressions evaluate properties in the FSM Mobile form. For information about FSM Mobile expressions and template tags, see FSM Expressions and Template Tags.
Formula and Text Limits
NetSuite search text columns have a 4,000-byte result limit. This is not a guarantee of 4,000 characters when text contains multibyte characters. For information about search text limits, see Search Result Limits.
When only a short preview is required, truncate the source text before using it in longer text operations. If several long fields are combined, limit the individual inputs and allow for separators in the combined result. Truncating the final result alone doesn't necessarily avoid an error in an earlier operation. A preview mapping doesn't preserve or update the full source text.
Regular-expression patterns have their own limit. Oracle's SQL reference specifies a maximum of 512 bytes for the pattern used by REGEXP_LIKE. This limit applies to the pattern, rather than the text being searched. For more information, refer to Pattern-matching Conditions.
Mapping Table Values to Sublists
A Table element defines FSM Mobile rows and their child elements. It doesn't by itself define how those rows are stored in a NetSuite sublist.
A sublist mapping uses an array of row mappings. The write side of each mapping identifies the sublist and field, such as expense.memo. The read side uses the valid search column or formula, which can have a different name.
For example, this fragment illustrates the memo and amount mappings used for expense report lines:
{
"expenses": [
{
"memo": "memo|expense.memo",
"amount": "amount|expense.amount"
}
]
}
This example is a mapping fragment, rather than a complete expense report definition. A complete transaction resource also needs its record identity, line selection, duplicate-row merge mapping, required line fields, and applicable transaction behavior. Preserve the feature's standard transaction model and mappings when extending it.
The first string mapping in a row object identifies its sublist scope. Keep mappings within that row object consistent with the intended sublist. The [] multiselect flag is a different mechanism and doesn't supply sublist line mappings.
Saving an array mapped to an entire sublist can remove existing lines that are absent from the supplied array. Don't use a filtered or incomplete line array as a complete editable sublist without accounting for the omitted lines.