Configuring Upsert Operation Adapter Services
Use the Upsert Operation template to configure an adapter service that inserts records or updates records of a Salesforce object. When attempting to add new records, you can use the upsert operation instead of the create operation to avoid the potential of inserting duplicate records. The upsert operation wraps the upsert call of the Salesforce.com Web service API.
Important:
In the Salesforce.com Partner WSDL version 25.0, all records must have the same object type in an upsert() call. When you select multiple Salesforce objects, Salesforce.com throws an exception.
For the upsert operation, you specify the value of a field that the operation uses to determine whether a record already exists. The field must be:
For standard objects, a field with the idLookup property. This is usually the object's ID, Name field, or both.
For custom objects, a field with the external ID attribute.
If the record does not already exist, the upsert operation inserts it. If the record does exist, the upsert operation updates it. You cannot create or update the values of the fields, which are auto generated by Salesforce.com.
As a response, the Salesforce.com upsert call returns an UpsertResult object. The adapter service returns the information from the UpsertResult object as output.
Output Variable | Description |
created | Boolean Whether the upsert operation inserted or updated the specified record. The value of created is true if the upsert operation inserted the record or false if the upsert operation updated the record. |
id | String The ID of the created or updated record when success is true. If success is false, id is null. |
success | Boolean Whether the upsert call successfully inserted/updated the record. |
errors | String List If success is false, errors provides the error codes and descriptions of the errors that the upsert call encountered. |
The input signature of the adapter service uses an sobjects Document List, which holds the field values the upsert operation uses. At run time, pass the adapter service one Document within the sobjects Document List for each record on which you want to act.
The output signature of the adapter service contains a results Document List. Each Document in the input sobjects Document List maps to an output Document in the results Document List.
To configure an adapter service that uses the Upsert Operation template
2. Start Designer.
3. Right-click the package in which the service should be contained and select New > Adapter Service.
4. Select the parent namespace, type a name for the adapter service, and click Next.
5. Select Adapter for Salesforce as the adapter type and click Next.
6. Select the appropriate Adapter Connection Name and click Next.
Important:
Ensure the Salesforce.com user account identified by the connection has all the required permissions to insert/update records in the Salesforce object that you will select later in the procedure.
7. From the list of available templates, select the Upsert Operation template and click Finish.
The adapter service editor for the adapter service appears. You can select the Adapter Settings tab at any time to confirm adapter service properties such as the Adapter Name, Adapter Connection Name, and Adapter Service Template, as necessary.
8. To identify the Salesforce object on which you want the adapter service to act and the field to use to determine whether a record already exists:
a. Select the Schema tab.
b. In the Salesforce Object column, select the Salesforce object for which you want to insert/update records from the drop-down list.
Designer updates the ID Field Name field with values based on the Salesforce object that you select.
Note:
The Upsert Operation service supports creating/updating records for a single Salesforce object at a time. Adding rows in the Salesforce Object column does not affect the ID Field Name list.
c. From the ID Field Name list, select the field that you want to use to determine whether a record already exists in the Salesforce object.
At run time, pass a value for this field as input into the adapter service. If the value matches an existing record, the adapter service updates the record. If the value does not match an existing record, the adapter service inserts a new record.
9. Include the ID Field Name that you selected earlier in the procedure to the input parameters to provide a variable for passing the value that the upsert operation uses to determine whether a record exists.
a. Select the Upsert Operation tab.
b. Click the 
icon to add one field row to the table. c. If the newly added field is not the field you specified for ID Field Name, select that field from the list in the Input Parameter column.
d. Select the check box in the Use Field column for the field.
Note:
If you do not include the ID Field Name field on the Upsert Operation tab, the upsert operation will insert new records, generating IDs for each record. If you do include the ID Field Name field and a value supplied does not match an existing record, the upsert operation inserts the new record using the value you supply for the field.
10. To identify the fields of the records for which you want to supply information:
a. Select the Upsert Operation tab.
b. Click the 
icon to populate the table with the fields of the selected Salesforce object. c. For each field that you want to supply, select the check box in the Use Field column.
Important:
When using an upsert operation adapter service, be sure to specify field values that maintain the referential integrity of the Salesforce object.
Note:
The Upsert Operation template lists only fields that can be created and updated.
If the adapter service inserts a record, these are the fields the adapter service supplies for the new record. If the adapter service updates a record, these are the fields the adapter service updates. The fields you specify become part of the input signature for the adapter service.
At run time, the adapter service determines whether the values specified for the fields are valid, for example, ensuring that a date value is specified for a field that has a java.util.Date data type. If an invalid value is detected, the adapter issues an error message and does not attempt to insert/update the record.
d. To upsert a record in a table that has a reference to a record in another sObject, select the fields in an sObject designated with External IDs. The Relationship Name column shows the sObject record that the selected External ID field relates to. For information about how to assign an External ID to a record field, see
Assigning External IDs to sObject Record
Fields. 11. Select File > Save to save the adapter service.
