Using the Upsert Function

In this section:

The Upsert function creates new objects or updates existing objects. It uses a custom field to determine the presence of existing objects.

Upsert is a term created by merging the words update and insert. This function is available for objects if the object has an External ID field or a field with the idLookup field property.

For custom objects, the Upsert function uses an indexed custom field (called an External ID) to determine whether to create a new object or update an existing object.
Top of page
x
Prerequisites

All Salesforce objects in which Upsert can process against require the addition of an External ID field.
x
Procedure: How to Configure an External ID Field

To configure an External ID field:

  1. Log on to the Salesforce Web console.
  2. From the App Setup pane on the left, expand Customize, Accounts, and then click Fields.

  3. In the General Options area, click the External ID check box (Set this field as the unique record identifier from an external system), as shown in the following image.

  4. Click Save.
Top of page
x
Accessing the Upsert Function Using iWay Explorer

iWay Application Adapter for Salesforce exposes the Upsert function in iWay Explorer. The following image shows a sample XML request schema (.xsd) file for the Account Salesforce object.

The following sample input XML document shows two important elements (<ExternalID> and <EXTIDACCT>) taken from the Account XML request schema document:

<Upsert-Account-Request>
            <ExternalId>EXTIDACCT__c</ExternalId>
            <Instance>
                 <Name>NewCoIBM450</Name>
                 <Type>other</Type>
                 <ParentId>0014000000IOLppAAH</ParentId>
                 <BillingStreet>2 Penn Plaza</BillingStreet>
                 <BillingCity>New York</BillingCity>
                 <BillingState>New York</BillingState>
                 <BillingPostalCode>10121</BillingPostalCode>
                 <BillingCountry>USA</BillingCountry>
                 <ShippingStreet>2 Penn Plaza</ShippingStreet>
                 <ShippingCity>New York</ShippingCity>
                 <ShippingState>New York</ShippingState>
                 <ShippingPostalCode>10212</ShippingPostalCode>
                 <ShippingCountry>USA</ShippingCountry>
                 <Phone>212 345 1234</Phone>
                 <Fax>212 890 345</Fax>
                 <AccountNumber>12345</AccountNumber>
                 <Website>www.newco.com</Website>
                 <Sic>3456</Sic>
                 <Industry>Retail</Industry>
                 <AnnualRevenue>30000</AnnualRevenue>
                 <NumberOfEmployees>1000</NumberOfEmployees>
                 <Ownership>Public</Ownership>
                 <TickerSymbol>newco</TickerSymbol>
                 <Description>New Account NE</Description>
                 <Rating>Hot</Rating>
                 <Site>New York</Site>
                 <OwnerId>00540000000zYqdAAE</OwnerId>
                 <CustomerPriority__c>High</CustomerPriority__c>
                 <SLA__c>Gold</SLA__c>
                 <Active__c>Yes</Active__c>
          <NumberofLocations__c>3.14159265358979E0</NumberofLocations__c>
                 <UpsellOpportunity__c>Maybe</UpsellOpportunity__c>
                 <SLASerialNumber__c>1234</SLASerialNumber__c>
                 <SLAExpirationDate__c>1967-08-13</SLAExpirationDate__c>
                 <IWAYCUST1__c>Test</IWAYCUST1__c>
                 <IWAYCUST2__c>Test1</IWAYCUST2__c>
                 <DUNS__c>123456789</DUNS__c>
                 <EXTIDACCT__c>450</EXTIDACCT__c>
            </Instance>
</Upsert-Account-Request>

<ExternalID> is the External ID field name defined for the EXTIDACCT Account object. <EXTIDACCT> is defined by the user, which has a value of 450 in this example. If the Upsert request finds a record with this value, the Account record is updated. If no record is found with this value, then a new record is inserted.

iWay Software