Search the Aria Knowledgebase for
User Documentation, APIs, SDKs, and more!

 

Home > User Documentation > NetSuite Connector > Aria NetSuite Plugin

Aria NetSuite Plugin

Overview

The Aria NetSuite Plugin allows users to apply implementation-specific customizations to the Aria Connector. Field-level mapping is defined in the plugin as well as any level of custom business logic. The plugin is deployed into your NetSuite account and linked to the connector and is developed using NetSuite’s SuiteScript. A boilerplate plugin is installed as part of the Aria NetSuite bundle installation. 

Users must copy the boilerplate plugin, customize it, and then link the new plugin to the Aria NetSuite Connector.

The plugin is referenced at several points by the connector while processing a message from Aria. For example:  

  • Plugin Initialization: Invoked when the plugin is first loaded at the start of request processing. Users must initialize the plugin-assigned mapping and event handlers that are used by the connector during message processing.
  • On Request: The plugin passes the complete payload of the request as received from Aria. Note that one request may contain many messages. This hook is intended for logging requests, if desired.
  • Mapping Definition: A structure that defines field-level mapping and additional hooks for specific record types. 
  • Before Submit: Invoked before a record is submitted to NetSuite.
  • After Submit: Invoked after a record is submitted to NetSuite.

​Plugin Initialization

The Plugin Initialization method, initialize(), is called when a request is received from Aria and NetSuite loads the connector.  This method sets up the connector environment including: 

Options

Plugin Initialization Value Description
ARIA.ns.EXID_PREFIX = 'aria'; // default When Aria creates a record in NetSuite, it assigns an external ID. This helps ensure that duplicate records are not created in NetSuite and helps the connector find related records. All external IDs are prefixed with the value defined here.
ARIA.ns.LOG_MESSAGES = 'ALL';  // ALL, ERROR, NONE Controls message level logging.
ARIA.ns.JE_MAP = {…}; Transactions that are entered into NetSuite as Journal Entries use the GL Accounts defined here. ARIA.ns.JE_MAP is assigned an object with a property for each transaction type number that creates a journal entry.

Method ARIA_PLUGIN_IMP.loadGlMapping() provided in the boilerplate plugin will load values in a custom record, allowing these values to be managed in the NetSuite UI.

Record Maps

Record Maps define field level mapping of Aria XML messages to NetSuite record fields. In addition, filters may be applied here to prevent posting of some records into NetSuite. Mapping is defined elsewhere in the plugin, but maps are assigned in the plugin as follows:

  • ARIA.ns.recordmaps['customer'] = ARIA_PLUGIN_IMP.recordmaps.customer;
  • ARIA.ns.recordmaps['transaction'] = ARIA_PLUGIN_IMP.recordmaps.transaction;
  • ARIA.ns.recordmaps['voidTransaction'] = ARIA_PLUGIN_IMP.recordmaps.voidTransaction;
  • ARIA.ns.recordmaps['payment'] = ARIA_PLUGIN_IMP.recordmaps.payment;
  • ARIA.ns.recordmaps['sale'] = ARIA_PLUGIN_IMP.recordmaps.sale;
  • ARIA.ns.recordmaps['reversal'] = ARIA_PLUGIN_IMP.recordmaps.reversal;
  • ARIA.ns.recordmaps['item'] = ARIA_PLUGIN_IMP.recordmaps.item;
  • ARIA.ns.recordmaps['plan'] = ARIA_PLUGIN_IMP.recordmaps.plan;
  • ARIA.ns.recordmaps['service'] = ARIA_PLUGIN_IMP.recordmaps.service;

Translators

Record maps may reference translators. Translators perform logic when assigning Aria record field values to a NetSuite record field. Mapping an Aria text value to a NetSuite internal ID is an expected use case for a translator. Translators are referenced by name during the mapping process. Translator references are placed in the ARIA object ARIA.ns.translators as shown:

  • ARIA.ns.translators['subsidiary'] = ARIA_PLUGIN_IMP.translators.subsidiary;

ARIA_PLUGIN_IMP.translators.subsidiary is a function. The key of the ARIA.ns.translators map entry is the name of the translator. The name of the translator is used in the record map definition.

Hooks

Hooks may be called at a defined point of message processing. If the plugin does not define and assign a hook, the message process continues uninterrupted. The following hooks are available. Hooks are optionally defined in the plugin and registered with the connector.

Hook

Description
onRequest(request)
@param string value of the raw request body		 Called by the connector with the request as received from Aria.  The request is a string value of the XML request. This may be useful for logging. 

Register:
ARIA.ns.hooks.onRequest = ARIA_PLUGIN_IMP.onRequest;

beforeSubmit(xmlRec, nsRecordType, nsRecord)
@xmlRec dom of the Aria record being processed
@nsRecordType NS script ID of the record
@nsRecord the NS record about to be submitted

 Called after mapping is completed and the NetSuite record is loaded, just before submitting to NetSuite. This is an opportunity to perform some final adjustment before submitting.

Register:

ARIA.ns.hooks.beforeSubmit = ARIA_PLUGIN_IMP.beforeSubmit;

afterSubmit(xmlRec, nsRecordType, nsRecord, id)
@xmlRec dom of the Aria record being processed
@nsRecordType NS script ID of the record
@nsRecord the NS record about to be submitted
@id the NetSuite internal ID of the record posted

 Called after submitting record if no error.
ARIA.ns.hooks.afterSubmit = ARIA_PLUGIN_IMP.afterSubmit; Called immediately after record is submitted to NetSuite. This is an opportunity to perform some supplementary logic proceeding before proceeding to the next record or returning to responses to Aria.

Complete Initialize example

function initialize() {     nlapiLogExecution('DEBUG', 'ARIA_PLUGIN_IMP','initialize+);
 
    // options
    ARIA.ns.LOG_MESSAGES = 'ALL';  // ALL, ERROR, NONE
 
    ARIA.ns.EXID_PREFIX = 'aria';
 
    ARIA_PLUGIN_IMP.loadGlMapping();
 
    // maps     ARIA.ns.recordmaps['customer'] =
        ARIA_PLUGIN_IMP.recordmaps.customer;     ARIA.ns.recordmaps['transaction'] =
        ARIA_PLUGIN_IMP.recordmaps.transaction;     ARIA.ns.recordmaps['payment'] = ARIA_PLUGIN_IMP.recordmaps.payment;     ARIA.ns.recordmaps['sale'] = ARIA_PLUGIN_IMP.recordmaps.sale;     ARIA.ns.recordmaps['reversal'] =
        ARIA_PLUGIN_IMP.recordmaps.reversal;     ARIA.ns.recordmaps['item'] = ARIA_PLUGIN_IMP.recordmaps.item;     ARIA.ns.recordmaps['plan'] = ARIA_PLUGIN_IMP.recordmaps.plan;     ARIA.ns.recordmaps['service'] = ARIA_PLUGIN_IMP.recordmaps.service;     ARIA.ns.translators['attention'] =
        ARIA_PLUGIN_IMP.translators.attention;     ARIA.ns.translators['subsidiary'] =
        ARIA_PLUGIN_IMP.translators.subsidiary;     ARIA.ns.translators['currency'] =
        ARIA_PLUGIN_IMP.translators.currency;     ARIA.ns.translators['paymentMethod'] =
        ARIA_PLUGIN_IMP.translators.paymentMethod;
    // hooks     ARIA.ns.hooks.beforeSubmit = ARIA_PLUGIN_IMP.beforeSubmit;     ARIA.ns.hooks.afterSubmit = ARIA_PLUGIN_IMP.afterSubmit;     ARIA.ns.hooks.pricingUpdate = ARIA_PLUGIN_IMP.pricingUpdate;     ARIA.ns.hooks.onRequest = ARIA_PLUGIN_IMP.onRequest;     nlapiLogExecution('DEBUG','ARIA_PLUGIN_IMP','initialize-'); }

Record Maps

Record maps define the mapping of fields of an Aria XML record to a NetSuite record. Record maps must be defined for each record type transferred. Below is a table of records mapped: 

Aria Record

NetSuite Record

Map Name

Notes

Acct

Customer

Customer

 

Transaction

Journal Entry

Transaction

Except event type

Payment (2,3)

Transaction (void)

Journal Entry

voidTransaction

 

Transaction (2,3)

Customer Payment

Payment

 

Invoice

Invoice

Sale

 

Invoice (void)

Credit Memo

Sale

Transform invoice

Reversal

Credit Memo

Reversal

 

Plan

Aria Plan (custom)

Plan

 

Item

Non Inventory Item

Item

 

Service

Non Inventory Item

Service

 

Defining Record Maps

A record map is a data structure that contains information that drives the mapping logic. The following is a definition of an Aria Account to a NetSuite Customer map.

ARIA_PLUGIN_IMP.recordmaps.customer = [   {     type: 'body',     filter : ARIA_PLUGIN_IMP.customerFilter,
    mapList: [
      {aField: 'Subsidiary', nField: 'subsidiary',
        type: 'V', translator: 'subsidiary'},
      {aField: 'F', nField: 'autoname', type: 'L', addOnly: false},
      {aField: 'F', nField: 'isperson', type: 'L' },
      {aField: 'CurrencyCd', nField: 'currency', type: 'T',
        translator: 'currency'},
      {aField: 'FirstName', nField: 'firstname', type: 'V',
        addOnly: false},
      {aField: 'LastName', nField: 'lastname', type: 'V',
        addOnly: false},
      {aField: 'MiddleInitial', nField: 'middlename', type: 'V' ,
        addOnly: false},
 
      {aField: 'Email', nField: 'email', type: 'V', addOnly: false},
      {nField: 'custentity_aria_plan_provision_date', type: 'D'},
      {aField: 'PO Number', isSup: true,
        nField: 'custentity_po_num_nr', type: 'V', addOnly: false},
      {aField: 'CollectionGroup',
        nField: 'custentity_aria_collections_acct_grp', type: 'V',
        addOnly: false,
        translator: 'aria_customListTranslator',
        source: 'customlist_aria_collections_acct_grp'}     },
    {         type: 'list',         name: 'addressbook',         keyList: true,         keyField: 'label',         keyValue: 'ARIA',         mapList: [
            {aField: 'ARIA', nField: 'label', type: 'L',
               addOnly: false},
            {aField: 'Country', nField: 'country', type: 'V',
               translator: 'aria_upperCase', addOnly: false},
            {aField: '', nField: 'addressee', type: 'L',
               translator: 'aria_addressee', addOnly: false},
            {aField: '', nField: 'attention', type: 'L',
              translator: 'attention', addOnly: false},
            {aField: 'Address1', nField: 'addr1', type: 'V',
              addOnly: false},
            {aField: 'Address2', nField: 'addr2', type: 'V',
              addOnly: false },
            {aField: 'Address3', nField: 'addr3', type: 'V',
              addOnly: false },
            {aField: 'City', nField: 'city', type: 'V',
              addOnly: false },
            {aField: 'State', nField: 'state', type: 'V',
              addOnly: false },
            {aField: 'PostalCode', nField: 'zip', type: 'V',
              addOnly: false }         ]     } ];

Type property

The above map contains two sections: a body and a list. The body is for the customer mapping and the list for the customers address book list. The “type” property can be either body or list. Only one body is allowed per map definition.  Each list must have a distinct name that correlates to the record list’s script ID.

Filter property

The body may optionally reference a filter function. In this case, the filter function is ARIA_PLUGIN_IMP.customerFilter. The filter can be used to preempt further processing. The function signature is shown as:

function someFilter (xRec,nRec)
@xRec dom of the Aria record
@nRec current NS record, null if not exist
@return true preempts further processing, false to process further

Map List property

The mapList property is an array of field mapping definition objects processed sequentially. Each mapping definition object has the following properties:

  • aField: xPath expression resolving to a value in the Aria XML record. Note that if the the “type” property is “L” then this is a literal value and the Aria XML is not referenced.
  • nField: The NetSuite script ID of the field being mapped.
  • Type:  V, T, L, D
    •    V set Value, use nlapiSetFieldValue to set NetSuite field (default)
    •    T set Text, use nlapiSetFieldText to set NetSuite field
    •    L literal, use aField liertally with set field value
    •    D Aria date to NetSuite date
  • isSup: The field is a supplemental Aria field. Source supplemental field with name in aField.
  • addOnly: The default is true, process field only on record add ignore on record update.
  • source: For Aria_customListTranslator (see translator below), the NetSuite script ID of the custom list.
  • translator: Name for translator to apply. This must be out of the box or defined in the plugin and registered during plugin initialization. Translators convert a value derived from aField to a value placed into NetSuite field nField.  Translators have the following signature:
    • Function someTranslator(map, xRec, nRec, val)
      • @map mapList entry
      • @xRec dom of Aria XML record
      • @nRec target NetSuite record
      • @val the value sourced using the aField
      • @returns the translated value or null to prevent mapping

Predefined Translators

 The following translator is defined in the Aria connector:
 aria_item_quantity – computes quantity based on Amount / UsageRate

Example:

{aField: '', nField: 'quantity', type: 'V', translator: 'aria_item_quantity'},

aria_upperCase – converts text value to upper case

Example:

{aField: 'CurrencyCd', nField: 'currency', type: 'T', translator: 'aria_upperCase' },

aria_checkbox – converts Aria value 1 to ‘T’ otherwise ‘F’

Example:

{aField: 'RevRecRelated', nField: 'custitem_aria_rev_rec', type: 'V', translator: 'aria_checkbox', addOnly: false},

aria_customListTranslator – looks up ID in a custom list for text value. Note: references source attribute in map definition.

Example:

{aField: 'CollectionGroup', nField:  
  'custentity_aria_collections_acct_grp', type: 'V', addOnly: false,
  translator: 'aria_customListTranslator',
  source: 'customlist_aria_collections_acct_grp'} 

aria_addressee – compiles address addressee

Example:

{aField: '', nField: 'addressee', type: 'L', translator: 'aria_addressee', addOnly: false},

aria_isPerson – returns ‘T’ if NetSuite customer record has a firtsname or a lastname value

Example:

{aField: '', nField: 'isperson', type: 'V', translator: 'aria_isPerson'},

aria_item – returns NetSuite internal id for a ItemNo in NetSuite

Example:

{aField: 'Service/ServiceNo', nField: 'item', type: 'V', translator: 'aria_item'}

aria_plan - returns NetSuite internal id for a PlanNo in NetSuite

Example:

{aField: 'PlanNo', nField: 'custcol_aria_plan', type: 'V', translator: 'aria_plan'}

Logging

The connector performs application logging and message logging. Application logging shows messages generated using SuiteScript’s nlapiLogExecution method during script execution. Message logging shows receipt and result of messages in a NetSuite custom record.

Application logging level is controlled on the script deployment record. Audit or Error level should be used for a production operation, as there is overhead with Debug level. The logging can be used to help with plugin programming and problem investigation. To view, see the Execution Log tab of the script deployment record.

With message-level logging, the payload of message received can be recorded in NetSuite using the custom record “Aria Message Log”.  Along with the payload, you can see the outcome and error information (if any). The logging level for this is set in the initialize method of the plugin and can be ALL, ERROR or NONE.

ARIA.ns.LOG_MESSAGES = 'ALL';  // ALL, ERROR, NONE

You must to post a comment.
Last modified
17:28, 26 Apr 2016

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by MindTouch ®