Defining a New Mapping Type Instance
The articles below describe how to define a new mapping type instance based on an existing mapping type in the Universal Mapping Assistant SuiteApp.
Defining a Mapping Type Instance
A mapping type instance defines the acceptable values for a given mapping type. A domain-specific app can submit such values in the following format:
{
type: string,
id: string,
name: string,
values: any,
translationCollection?: string | null,
suggester?: string | null,
configuration: object
}
In the example above:
-
type represents the ID of the mapping type that the mapping type instance refers to. This shouldn't be confused with the internal ID, which is account-specific. For more information, see Defining a New Mapping Type.
-
id is a string that identifies the mapping type instance in the context of its mapping type.
-
name is the human-readable name of the mapping type instance that you see on the Universal Mapping Assistant page.
-
values is a list of available target values for the mappings created in the context of the mapping type instance. The format of such list depends on the specific mapping type instance.
-
translationCollection is the ID of a translation collection that holds the translations for the available values and for the mapping type instance name. It's optional and can be omitted if the mapping type instance doesn't support translations.
-
suggester is the path to a component that will provide mapping suggestions. If your mapping type instance doesn't need or support suggestions, you can omit this field or set it to null.
-
configuration is an object that further defines the mapping type instance. Its format depends on the definition of the selected mapping type.
Below is an example of a valid mapping type instance specification:
{
type: 'UMA_SAFT_2_0_ACCOUNTS',
id: 'NO_SAFT_2_0_ACCOUNTS',
name: 'mti_name',
values: {
groupingCategories: [
{ uid: 'cat_1', name: 'Category 1' }
],
groupingCodes: [
{ category: 'cat_1', code: 'cod_1', uid: 'code_1', name: 'code1' },
{ category: 'cat_1', code: 'cod_2', uid: 'code_2', name: 'code2' }
]
},
translationCollection: 'custcollection_nor',
suggester: '/SuiteApps/com.netsuite.universalmappingassistant/src/suggesters/saft2acc/EmbeddingSuggester',
configuration: {
countries: ['NO']
}
}
In this example, the target values under values use uid as their stable identity. Each uid is expected to be unique within the submitted values payload.
Registering a Mapping Type Instance
As shown in the example below, you can register a mapping type instance through the dedicated customscript_uma_sl_map_inst_installer Suitelet:
import * as NsHttps from 'N/https';
async function installMappingTypes() {
await NsHttps.requestSuitelet.promise({
scriptId: 'customscript_uma_sl_map_inst_installer',
deploymentId: 'customdeploy_uma_sl_map_inst_installer',
body: JSON.stringify({
type: 'UMA_SAFT_2_0_ACCOUNTS',
id: 'NO_SAFT_2_0_ACCOUNTS',
...
})
});
}
When receiving a definition, the Suitelet validates the following:
-
that such definition is in the expected format
-
that the referenced mapping type exists
-
that each value is in the format expected by the selected mapping type
The Suitelet can create approximately 2200 new grouping categories and grouping codes per request.
In case of a failure it returns the following:
{
success: false,
message: 'The error description goes here'
}
In case of a success it returns the following:
{
success: true,
taskId: 'xxxx' // This can be used by the country specific app to monitor the Scheduled Script execution status
}
When a mapping type instance is registered for an existing (type, id) pair, the Universal Mapping Assistant updates it and reconciles target values by uid. The Target values omitted from the submitted payload are treated as obsolete values and are removed.
When the installed values of a mapping type instance change, users who select that mapping type instance can see a Mapping Definitions Updated banner. Dismissing the banner acknowledges the current definition for that user. If the definition changes again later, the banner is shown again.
Validation failures can include additional context such as stage, target, and detail. For more information, see Validation of Mapping Type Instance Values.
Defining Your Own Suggester
You can define your own Suggester component by implementing the interface specified below if:
-
The mapping type that you're referencing doesn't provide a default Suggester component
-
The default component doesn't fit your business requirements
type Suggester = {
getSuggestions: (sourceData: any[], mappingTypeInstance: MappingTypeInstance) => Promise<({[key: string]: Value} | null)[]>;
}
The getSuggestions function accepts a collection of source data rows, as returned by the source controller and the definition of your mapping type instance. It returns a collection of suggested mappings. For each element of the source collection, it either provides an object with the required properties, or null, if no suggestion is available.
Available Mapping Types
A mapping type instance must be based on an existing mapping type. This can either be a custom mapping type, as described in Defining a New Mapping Type, or an existing one provided by the Universal Mapping Assistant SuiteApp. For more information, see Available Mapping Types and Validation of Mapping Type Instance Values.
Existing mapping types provided by the Universal Mapping Assistant SuiteApp:
-
GL Accounts SAF-T 2.0
For more information, see Mapping Type: GL Accounts SAF-T 2.0.
-
Methods of Payment
For more information, see Mapping Type: Methods of Payment.