upsert
The upsert operation is used to add a new instance or to update an instance of a record in NetSuite. It is similar to the upsertList operation, which allows users to add or update more than one record at a time.
The upsert operation is similar to both the add and update operations, but upsert can be run without first determining whether a record exists in NetSuite. A record is identified by its external ID and its record type. If a record of the specified type with a matching external ID exists in the system, it is updated. If it does not exist, a new record is created.
Because external ID is mandatory for this operation, upsert is supported only for records that support the external ID field. Also, this operation prohibits the passing of internal ID values.
To prevent duplicate records, you should use external IDs and the upsert and upsertList operations to add records to NetSuite.
Limitations on upsert
-
Although records of a particular type may be used in multiple integration scenarios, each record instance can only have a single external ID value. To maintain data integrity, only a single integrated application can set and update external ID values for each record type. External ID values for all records of a particular type must all come from the same external application.
-
Upsert cannot complete updates during an initialize / initializeList operation, when a record is transformed into a record of another type. In this case, upsert only adds and does not update records.
-
Updates through the upsert operation are also subject to the same limitations as updates through the update operation. For details of these limitations, see update.
Request
The UpsertRequest type is used for the request. It contains the following fields.
|
Element Name |
XSD Type |
Notes |
|---|---|---|
|
record |
Record |
Contains an array of record objects. The record type is an abstract type so an instance of a type that extends record must be used—such as Customer or Event. |
Response
The UpsertResponse type is used for the response. It contains the following fields.
|
Element Name |
XSD Type |
Notes |
|---|---|---|
|
response |
WriteResponse |
Contains details on the status of the operation and a reference to thecreated or updated record. |
Faults
-
This operation can throw one of the following faults. See SOAP Fault Status Codes for more information.
-
InvalidSessionFault
-
InvalidCredentialsFault
-
ExceededRequestLimitFault
-
ExceededUsageLimitFault
-
ExceededRecordCountFault
-
ExceededRequestSizeFault
-
UnexpectedErrorFault
-
-
This operation returns the following run-time error if the passed record type does not support the external ID field:
INVALID_RCRD_TYPE: <record_type> does not support external ID and cannot be used with upsert -
This operation returns the following run-time error if passed data includes internal ID:
USER_ERROR: You cannot set internalId with upsert. -
This operation returns the following run-time error if passed data does not include external ID:
USER_ERROR: This operation requies a value for externalId.For more information about error codes, see Error Status Codes.
Sample Code
SOAP Request
<soap:Body>
<upsert xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record xmlns:q1="urn:relationships_2017_1.lists.webservices.netsuite.com" xsi:type="q1:Customer" externalId="THISISMYEXTID">
<q1:entityId>XYZ 2 Inc</q1:entityId>
<q1:companyName>XYZ 2, Inc.</q1:companyName>
<q1:email>bsanders@xyz.com</q1:email>
</record>
</upsert>
</soap:Body>
SOAP Response
<soapenv:Body>
<upsertResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
<baseRef internalId="973" externalId="THISISMYEXTID" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2017_1.platform.webservices.netsuite.com"/>
</writeResponse>
</upsertResponse>
</soapenv:Body>
C#
private void upsertCustomer()
{
// This operation requires a valid session
this.login( true );
Customer customer = new Customer();
// Get externalId for upsert
_out.write( "\nEnter externalId for customer record to be created or updated : " );
customer.externalId = _out.readLn().ToUpper();
// Set name and email
customer.entityId = "XYZ 2 Inc";
customer.companyName = "XYZ 2, Inc.";
customer.email = "bsanders@xyz.com";
// Invoke upsert() operation
WriteResponse response = _service.upsert( customer );
// Process the response
if (response.status.isSuccess )
{
_out.info(
"\nThe upsert operation was successful :" +
"\ninternalId=" + ((RecordRef) response.baseRef).internalId +
"\nexternalId=" + ((RecordRef) response.baseRef).externalId +
"\nentityId=" + customer.entityId +
"\ncompanyName=" + customer.companyName);
} else {
_out.error( getStatusDetails( response.status ) );
}
}
Java
public void upsertCustomer() throws RemoteException,ExceededUsageLimitFault,
UnexpectedErrorFault, InvalidSessionFault,ExceededRecordCountFault
{
// This operation requires a valid session
this.login(true);
Customer customer = new Customer();
// Get extenalId for add or update
_console.write("\nEnter externalId for customer record to be updated : ");
customer.setExternalId(_console.readLn());
// Set name and email
customer.setEntityId("XYZ 2 Inc");
customer.setCompanyName("XYZ 2, Inc.");
customer.setEmail("bsanders@xyz.com");
// Invoke upsert() operation
WriteResponse response = _port.upsert(customer);
// Process the response
if (response.getStatus().isIsSuccess())
{
_console.info("\nThe following customer was created/updated successfully:"
+ "\nkey=" + ((RecordRef) response.getBaseRef()).getInternalId()
+ "\nexternalId=" + ((RecordRef) response.getBaseRef()).getExternalId()
+ "\nentityId=" + customer.getEntityId()
+ "\ncompanyName=" + customer.getCompanyName()
+ "\nemail=" + customer.getEmail());
}
else
{
_console.error(getStatusDetails(response.getStatus()));
}
}