Guidelines For Working with NetSuite External IDs

This article is relevant if you are working with NetSuite External IDs.

Background

NetSuite External ID (commonly referenced as externalid) is a means for creating a unique record ID independent of NetSuite’s auto-generated Internal ID (internalid). It is most commonly used when you seek to produce an integration between NetSuite and a third-party application.

Consider a Human Resource (HR) application that maintains important employee information.  Suppose that from within NetSuite, you would like to offer a way to hyperlink to the HR application. The external ID on the employee record can hold the HR record ID for the respective employee.  It then becomes simple to auto-generate the hyperlink that would transport the NetSuite user to the respective record in the HR application.

Important NetSuite External ID Guidelines

When using external IDs, often a number of questions emerge. Thus, this article helps a NetSuite administrator or developer quickly get oriented to the topic.

Here are key points to understand:

1. Unique Values in Record Domains: external ID values are string-based and must be unique in their domain. Thus, external ID for entities (e.g. customers, vendors), transactions, and custom records must be unique. In my practice, we often prefix a unique ID with something about the respective interested application to help maintain uniqueness. In the example above, we would prefix values with “hr:”
2. Not In Global Index: External IDs are not in the global search index.  You can look them up with saved-search.
3. Exposing External ID: NetSuite’s form technology does not allow you to expose the External ID to the user. A quick workaround is to create an exposed custom field that sources its value dynamically from the external ID.  Another approach is to have a script-based dynamic field be added to the form view in the BeforeLoad event.
4. Updating External ID: the most common referenced approach to update External ID is via CSV upload. Enough said.
5. Script Updates on External ID: updating the external ID from a script is possible. However, there are some considerations: a) you can’t update it from the target record’s BeforeSubmit operation — it must be from the AfterSubmit; and b) scripts to create or update a record can set the externalid like any other field operation.  See below for a code pattern.
6. Unsupported External ID Record Types: NetSuite provides a reference to field types that do not support External ID, see this SuiteAnswers article.  At the time of this writing, these record types are not supported: Accounting Period, Budget Category, CRM Custom Field, Currency Rate, Custom List, Custom Record Custom Field, Custom Record Type, Entity Custom Field, Gift Certificate, Item Custom Field, Item Number Custom Field, Item Option Custom Field, Landed Cost, Other Custom Field, State, Transaction Body Custom Field, and Transaction Column Custom Field.

Setting NetSuite External ID to Null

You may need to set the External ID to null — the default state. This must be done in a script. Thus, the following Mass Update SuiteScript 2.x code pattern can be used. This code pattern can easily be adapted for other External ID operations:

// SEE ADDENDUM BELOW ==== THIS CODE PATTERN DOES NOT SET TO NULL EXTERNAL IDS
define(['N/record'],
	function(record) {
		function each(params) {
			var funcName = "PRI_MU_SetExtID_Null " + params.type + " " + params.id;
			try {
				var r = record.load({type: params.type, id: params.id, isDynamic: true})
				log.debug(funcName, r.getValue({fieldId: 'externalid'}))
				r.setValue({
					fieldId: 'externalid',
					value: null,
					ignoreFieldChange: true
				});
				r.save({ignoreMandatoryFields: true});
				log.debug(funcName, "Record Loaded/ExtID Null/Saved");
			} catch (e) {
				log.error(funcName + " error", e);
			}								
		}
		return {
			each: each
		};
	}
);

Addendum to Script for Setting ExternalID to Null

Further research indicates that SuiteScript 2.0 has challenges setting external ID to Null.   This SuiteScript 1.0 code pattern has been offered up as an approach:

var recordId = '123';
var recordType = 'customrecord1';
var record = nlapiLoadRecord(recordType, recordId);
record.setFieldValue('externalid', '');
nlapiSubmitRecord(record);

I need to perform more testing to confirm the SuiteScript 1.0 pattern above indeed will nullify the externalid.

NetSuite External ID Summary

I like the idea of External IDs primarily because they enforce uniqueness without having to do work for that feature.  Yet, it is important to plan when using them — thus the idea of using a prefix to ensure uniqueness helps to plan for unknown application situations long term.

If you found this article relevant, feel free to sign up for notifications to new articles as I post them. If you would like to work with NetSuite experts dedicated to their craft, let’s have a conversation.