Home | Table of Contents | SalesforceWriter | CloverETL 4.6.1
--- | --- | ---
Prev | Writers | Next

## SalesforceWriter

# Not available in Community Designer

Short Description
Ports
Metadata
SalesforceWriter Attributes
Details
Examples
Compatibility
See also

### Short Description

SalesforceWriter writes, updates, or deletes records in Salesforce using SOAP API.

Component | Data output | Input ports | Output ports | Transformation | Transf. req. | Java | CTL | Auto-propagated metadata
--- | --- | --- | --- | --- | --- | --- | --- | ---
SalesforceWriter | database | 1 | 2 |  |  |  |  |

### Icon

### Ports

Port type | Number | Required | Description | Metadata
--- | --- | --- | --- | ---
Input | 0 |  | For data records to be inserted, updated, or deleted | input0
Output | 0 |  | For accepted data records | input0 plus ObjectId field
Output | 1 |  | For rejected data records | input0 plus Error message field

If you do not map error port and an error occurs, the component fails.

### Metadata

SalesforceWriter propagates metadata from left to right.

The metadata on the right side on first output port have an additional field ObjectId. If operation is upsert, the output metadata on first output port also have an additional field Created.

The metadata on the right side on second output port have and additional field Error.

Metadata cannot use Autofilling Functions.

### SalesforceWriter Attributes

Attribute | Req | Description | Possible values
--- | --- | --- | ---
Basic
Connection | yes | A Salesforce connection. See Salesforce connection. | e.g. MySFConnection
Salesforce object | yes | An object affected by operation | e.g. Account
Operation |  | Operation performed on the Salesforce object | insert (default) | update | upsert | delete
Input mapping |  | Mapping of fields to be inserted/updated/deleted in Salesforce | Map by name (default)
Output mapping |  | Mapping of successfully inserted/updated/deleted fields | Map by name (default)
Error mapping |  | Mapping of records that were not inserted/updated/deleted | Map by name (default)
Advanced
Upsert external ID field | (yes) | Field of object specified in Salesforce object which will be used to match records in Upsert operation. Mandatory for Upsert operation. Not used in any other operation. | e.g. Id
Batch size |  | Size of the batch. The default and maximum batch size is 200. In some cases, it is beneficial to reduce the batch size to a lower number, because e.g. the APEX triggers exceed the 10s limit for the call and the whole write fails. | e.g. 150

### Details

##### Supported Operations

Insert - inserts new records

Update - updates existing records

Upsert - inserts or updates records

Delete - moves records to recycle bin.

According to the operation you have chosen, different output metadata in Input mapping are displayed in transform editor.

##### SOAP or Bulk API

If you write less than 1500-2000 records, it is better to use SOAP API because it will use less API requests.

#### Writing Attachments

SalesforceWriter supports writing attachments. You can either receive the attachment from byte fields or and read the attachment from files.

The both options are mutually exclusive. If both options are specified, reading the attachment from byte fields has higher priority over reading the attachment from files.

##### Attachments from byte fields

Attachment can be read from input metadata field of byte or cbyte data type. The field containing the attachment is to be mapped to byte field, e.g. Body field in Attachment object.

##### Attachments from files

To read attachments from files, map field with file URL to a string field with _FileURL suffix, which is below the corresponding byte field, e.g. Body_FileURL field in Attachment object.

You can map only one file per record. Wild cards in file name are not supported.

#### Notes and Limitations

When specifying Salesforce objects and fields, always use the API Name of the element.

SOAP API does not support HardDelete operation. If you need HardDelete operation, use SalesforceBulkWriter.

##### Limits introduced by Salesforce API

Single API soap call cannot contain more than 200 objects.

Single soap message cannot exceed 50MB (encoded as UTF-8).

The component will do its best to bundle as many objects (records) as possible together into a single call to reduce number of used API requests. In most cases all 200 records will fit into the 50MB limit, so the component will need 1 API request for 200 records.

When writing very long text fields or attachments it's possible that a smaller number of records will take all 50MB. In such case the component sends as many records as possible in every call but ensures that the soap message will not exceed 50MB limit. Rest of the records will be sent in another call. Users don't need to worry about sizing the messages themselves. If they want however, they can monitor the bundling of records. The number of records and expected size of the message is included in graph log on DEBUG level.

##### Usage of API calls

The component uses several API calls during its run:

1. Login

2. Describe schema of target object - to extract metadata

3. 1 call per every 200 records or 50MB of data, whichever comes first

### Examples

Inserting records
Updating records
Upserting records
Deleting records
Inserting attachments received from byte fields
Inserting attachments from files

#### Inserting records

This example shows a basic use case with insertion of records.

Insert records with new contacts into Salesforce. Input data fields have the same field names as Salesforce data fieds.

##### Solution

Connect input port of SalesforceWriter with data source.

Create a Salesforce connection.

In SalesforceWriter, fill in Connection and Salesforce object.

Attribute | Value
--- | ---
Connection | Connection from the second step
Salesforce object | Contact

We do not have to specify the operation, as insert is the default one. We do not have to specify Input mapping, as metadata field names are the same as Salesforce field names and the default mapping (by name) is used.

You can attach an edge to the first output port to obtain object ids of inserted records. You can attach an edge to the second output port to obtain records that have not been inserted.

#### Updating records

This example shows updating of Salesforce objects.

Punch Cards Ltd. has changed its name to United Floppies Ltd. Update the name in Account table/object.

##### Solution

Create a salesforce connection, read Id of the company with SalesforceBulkReader, change the company name, update the record in Salesforce with SalesforceWriter.

Attribute | Value
--- | ---
Connection | Connection from the first step
Salesforce object | Account
Operation | Update
Input mapping | See the code below

    //#CTL2

    function integer transform() {
     	$out.0.Id = $in.0.Id;
     	$out.0.Name = "United Floppies Ltd.";

     	return ALL;
    }

#### Upserting records

This example shows upserting records.

There is a list of contacts (name and surname) and new phone number. Update the phone numbers of the contacts. If there is no such contact, create a new one.

##### Solution

Read records from Contact table with SalesforceBulkReader. Join them with the records from the list. The result of join operation should contain only the records from the list. Write the records from the list only.

In the SalesforceWriter, set Connection, Salesforce object, Operation, and Input mapping.

Attribute | Value
--- | ---
Connection | Connection from the first step
Salesforce object | Contact
Operation | Upsert
Input mapping | See the code below
Upsert external ID field | Id

    //#CTL2

    function integer transform() {
     	$out.0.Id = $in.0.Id;
     	$out.0.FirstName = $in.0.FirstName;
     	$out.0.LastName  = $in.0.LastName;
     	$out.0.Phone     = $in.0.Phone;

     	return ALL;
    }

#### Deleting records

This example shows deleting records.

A contact Ab C has been inserted by mistake. Delete the contact.

##### Solution

Create a salesforce connection, read the contact Id with SalesforceBulkReader, and use the Id to delete it with SalesforceWriter.

In SalesforceWriter set Connection, Salesforce object, and Operation.

Attribute | Value
--- | ---
Connection | Connection from the first step
Salesforce object | Contact
Operation | Delete

#### Inserting attachments received from byte fields

This example shows writing attachments into Salesforce. The content of the file is received from a byte field of input port metadata.

Insert an attachment to Account 'Floppies United'.

##### Solution

Create a Salesforce connection.

Read id of the 'Floppies United' account with SalesforceBulkReader.

Read attachment with FlatFileReader into a byte field. The metadata on output port on FlatFileReader use EOF as delimiter; set record delimiter and default field delimiter empty.

Merge the data streams with Combine.

Write the attachment with SalesforceWriter.

In SalesforceWriter, use Connection, Salesforce object, and Input mapping attributes.

Attribute | Value
--- | ---
Connection | Connection from the first step
Salesforce object | Attachment
Input mapping | See the code below.

    //#CTL2

    function integer transform() {
     	$out.0.ParentId = $in.0.Id;
     	$out.0.Body     = $in.0.FileContent;
     	$out.0.Name     = $in.0.FileName;

     	return ALL;
    }

| Note
In SalesforceWriter you can read files to be uploaded directly. In input mapping, map URL of the file to Body_FileURL field.

#### Inserting attachments from files

This example shows writing attachments to Salesforce. The content of the attachment is not received from byte fields, but read from files.

Input data to SalesforceWriter contains ContactID, Filename, and path to the file. Write the files to the Salesforce as attachments.

##### Solution

Create a Salesforce connection. In SalesforceWriter, set Connection, Salesforce object, and Input mapping attributes.

Attribute | Value
--- | ---
Connection | Connection from the first step
Salesforce object | Attachment
Input mapping | See the code below.

    //#CTL2
    function integer transform() {
    	$out.0.ParentId = $in.0.id;
    	$out.0.Name = $in.0.name;
    	$out.0.Body_FileURL = $in.0.filename;

    	return ALL;
    }

### Compatibility

#### 4.4.0-M1

SalesforceWriter is available since 4.4.0-M1. It uses Salesforce SOAP API version 37.0.

#### 4.5.0-M2

Since CloverETL 4.5.0-M2, SalesforceWriter uses Salesforce SOAP API version 39.0.

#### 4.5.0

Since CloverETL 4.5.0, you can set batch size.

### See also

SalesforceReader
SalesforceBulkReader
SalesforceBulkWriter
SalesforceWaveWriter
Common Properties of Components
Specific Attribute Types
Common Properties of Writers
Writers Comparison
Salesforce connection

Prev | Up | Next
SalesforceBulkWriter | Home | Table of Contents | SalesforceWaveWriter