[//]: # (sidebar_class_name: hidden)


<Header icon={<img src="/docs/logos/salesforce.svg" className="w-9 h-9 inline" />}>Salesforce</Header>

Salesforce is a leading customer relationship management (CRM) platform that provides a comprehensive suite of tools for managing customer relationships, sales, and marketing.

Jitsu’s Salesforce destination allows you to **create**, **update**, **upsert** and **delete** records for any object type.

## Mapping

### Automatic Mapping

:::tip
Most integrations will require setup of [custom mapping](#custom-mapping) using JavaScript Functions.
:::

Salesforce supports a wide range of object types, including custom objects created by clients.
Jitsu provides limited automatic mapping of event types to Salesforce object types:

* identify → Lead
* group → Account
* chosen event&ast; → Contact

&ast; Jitsu can automatically populate fields of the Contact object type if the `SALESFORCE_SOBJECT` is set to Contact within a Function. See [Custom Mapping](#custom-mapping) section below for more details.

Jitsu automatically searches for properties whose names match the field names of the corresponding Salesforce Object (as listed in the Field Name column in Salesforce Object Manager’s Fields & Relationships table). These properties are resolved from the following paths: `event.traits`, `event.properties`, `event.context.traits`.


<Tabs>
  <TabItem value="lead" label="identify to Lead">
| Salesforce 'Lead' property | Jitsu event path           | Jitsu alternative event path   |
|----------------------------|----------------------------|--------------------------------|
| Company                    | traits.company             | properties.company             |
| LastName                   | traits.last_name           | properties.last_name           |
| FirstName                  | traits.first_name          | properties.first_name          |
| Email                      | traits.email               | properties.email               |
| City                       | traits.address.city        | properties.address.city        |
| State                      | traits.address.state       | properties.address.state       |
| Country                    | traits.address.country     | properties.address.country     |
| PostalCode                 | traits.address.postal_code | properties.address.postal_code |
| Street                     | traits.address.street      | properties.address.street      |
  </TabItem>
  <TabItem value="account" label="group to Account">
| Salesforce 'Account' property | Jitsu event path           | Jitsu alternative event path   |
|-------------------------------|----------------------------|--------------------------------|
| Name                          | traits.name                |                                |
| AccountNumber                 | groupId                    |                                |
| NumberOfEmployees             | traits.employees           | properties.employees           |
| BillingCity                   | traits.address.city        | properties.address.city        |
| BillingState                  | traits.address.state       | properties.address.state       |
| BillingCountry                | traits.address.country     | properties.address.country     |
| BillingPostalCode             | traits.address.postal_code | properties.address.postal_code |
| BillingStreet                 | traits.address.street      | properties.address.street      |
| Phone                         | traits.phone               | properties.phone               |
| Description                   | traits.description         | properties.description         |
| Website                       | traits.website             | properties.website             |
  </TabItem>
  <TabItem value="contact" label="Contact">
| Salesforce 'Contact' property | Jitsu event path           | Jitsu alternative event path   |
|-------------------------------|----------------------------|--------------------------------|
| LastName                      | traits.last_name           | properties.last_name           |
| FirstName                     | traits.first_name          | properties.first_name          |
| Email                         | traits.email               | properties.email               |
| MailingCity                   | traits.address.city        | properties.address.city        |
| MailingState                  | traits.address.state       | properties.address.state       |
| MailingCountry                | traits.address.country     | properties.address.country     |
| MailingPostalCode             | traits.address.postal_code | properties.address.postal_code |
| MailingStreet                 | traits.address.street      | properties.address.street      |
  </TabItem>
</Tabs>


### Custom Mapping

Using Functions unlocks the full capabilities of Jitsu’s Salesforce destination, including:

* Support for all Salesforce object types, including custom objects.
* Ability to **create**, **update**, **upsert** and **delete** records.
* Full control over object payload sent to Salesforce REST API.

Custom mapping is controlled with the set of properties that can be added to the root level of the event object:

| Property Name                | Description                                                                                       | Default                                                              |
|------------------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| SALESFORCE_SOBJECT           | Salesforce object type to work with.                                                              | `Lead` for `identify`, `Account` for `group`, otherwise **Required** |
| SALESFORCE_PAYLOAD           | Salesforce Object payload                                                                         | See [Default Payload](#default-payload)                              |
| SALESFORCE_OPERATION         | API operation: **insert**, **update**, **upsert** or **delete**                                   | insert                                                               |
| SALESFORCE_MATCHERS          | For **update**, **upsert** and **delete**  operation, matchers used to find record to operate on. | `{}`                                                                 |
| SALESFORCE_MATCHERS_OPERATOR | Logical operator used to combine matchers: `OR` or `AND`                                          | `OR`                                                                 |

#### Selecting Object Type

The `SALESFORCE_SOBJECT` property specifies the Salesforce object type to work with. It can be any standard or custom object type in Salesforce:

```javascript
export default async function(event, context) {
  event.SALESFORCE_SOBJECT = "Contact"; // Specify the Salesforce object type
  return event
}
```

For **custom object** types, use the API name of the custom object (as listed in the API Name column in Salesforce Object Manager table). Typically, custom object names end with `__c` suffix.

```javascript
export default async function(event, context) {
  event.SALESFORCE_SOBJECT = "My_Custom__c"; // Specify the Salesforce object type
  return event
}
```

#### API Operations

The `SALESFORCE_OPERATION` property specifies the API operation to perform on the Salesforce object type defined in the `SALESFORCE_SOBJECT` property. The supported operations are:

* **insert**: Create a new record.
* **update**: Update an existing record.
* **upsert**: Update an existing record or create a new one if it doesn't exist.
* **delete**: Delete an existing record.

**update**, **upsert** and **delete** operations require the `SALESFORCE_MATCHERS` property to be specified to find the **Record ID** of the record to operate on.
See [Object Matchers](#object-matchers) section below for more details.

#### Customizing Object Payload

The `SALESFORCE_PAYLOAD` property allows you to specify the payload for the Salesforce object type defined in the `SALESFORCE_SOBJECT` property.

This property should be an object containing the fields and values to be sent to Salesforce.
For example, to create a new Contact record, you can specify the payload as follows:

```javascript
export default async function(event, context) {
  event.SALESFORCE_SOBJECT = "Contact"; 
  event.SALESFORCE_PAYLOAD = {
    LastName: event.traits.last_name || "John",
    FirstName: event.traits.first_name ||  "Doe",
    Email: event.traits.email || "johndoe@example.com",
    MailingCity: "Springfield",
    MailingState: "CA",
    MailingCountry: "USA",
    MailingPostalCode: "90210",
    MailingStreet: "123 Example Street"
   };
  return event
}
```

Jitsu won't add any additional properties to the provided payload, but it can remove properties that are not present in the Salesforce object type specified in the `SALESFORCE_SOBJECT` property.

##### Computed Values

For `update` or `upsert` API operations, it may be necessary to compute some field values based on the values already stored in Salesforce. For example, you may want to accumulate a numeric field value or concatenate a string field.

Jitsu supports operators that use both the existing stored value and the value from `SALESFORCE_PAYLOAD` to compute the final value sent to Salesforce.

To apply an operator on a field value, instead of providing a direct value, you should specify an object with `op` and `value` properties inside the `SALESFORCE_PAYLOAD`, as shown below:

```javascript
export default async function(event, context) {
  event.SALESFORCE_SOBJECT = "Lead";
  event.SALESFORCE_OPERATION = "update";
  event.SALESFORCE_PAYLOAD = {
    // add value of `cost` property to the existing value of `Total_Spend__c` field
    Total_Spend__c: {
      op: "add",
      value: event.properties.cost 
    }
  };
  return event
}
```

###### Supported operators:

* `setOnce` - sets the field value to the provided value only if the field does not have value yet.
* `add` - adds the provided value to the stored field value.
* `subtract` - subtracts the provided value from the stored field value.
* `multiply` - multiplies the stored field value by the provided value.
* `divide` - divides the stored field value by the provided value.
* `concat` - concatenates the stored string field value with the provided string value.
* `prefix` - prepends the provided string value to the stored string field value.
* `dateAdd` - adds the provided number of **seconds** to the stored date field value.
* `dateSubtract` - subtracts the provided number of **seconds** from the stored date field value.

For binary operators, if the stored field value is not yet set, Jitsu uses safe default values: `0` for numbers, an empty string for strings, and the current date for date fields.

##### Default Payload

When no `SALESFORCE_PAYLOAD` property specified, Jitsu uses [Automatic Mapping](#automatic-mapping) to populate the payload for the Salesforce object type specified in the `SALESFORCE_SOBJECT` property.

Additionally, Jitsu automatically searches for properties whose names match the field names of the corresponding Salesforce Object (as listed in the Field Name column in Salesforce Object Manager’s Fields & Relationships table). These properties are resolved from the following paths: `event.traits`, `event.properties`, `event.context.traits`.

#### Object Matchers

Required for **update**, **upsert** and **delete** operations.

The `SALESFORCE_MATCHERS` property  should contain a javascript object with properties that will be used to find the record to operate on.
The properties should match the field names of the corresponding Salesforce Object (as listed in the Field Name column in Salesforce Object Manager’s Fields & Relationships table).


If provided matchers do not match any record or match multiple records, Jitsu will log an error and skip the event.

**Example**: Update Contact with LastName "Doe" and set MailingPostalCode to "90211":

```javascript
export default async function(event, context) {
  event.SALESFORCE_SOBJECT = "Contact";
  event.SALESFORCE_OPERATION = "update";
  event.SALESFORCE_MATCHERS = {
      LastName: "Doe"
  }
  event.SALESFORCE_PAYLOAD = {
    MailingPostalCode: "90211",
  };
  return event
}
```

:::tip
If you already have the **Record ID** of the record to operate on, you can use it directly in the `SALESFORCE_MATCHERS` property:

```javascript  
//...
event.SALESFORCE_MATCHERS = { 
  Id: "0012300000abcdefGHI" // Record ID of the Contact
}
//...
```
That allows to avoid extra API call to find the Record ID by matchers.
:::

##### Combining Matchers

`SALESFORCE_MATCHERS` object can contain multiple properties to match against the record in Salesforce.

By default, Jitsu uses `OR` operator to combine matcher properties. E.g. if you specify `SALESFORCE_MATCHERS` as follows:

```javascript
//...
event.SALESFORCE_MATCHERS = {
  LastName: "Doe",
  FirstName: "John"
}
//...
```
It will match any record that has either `LastName` equal to "Doe" or `FirstName` equal to "John".

You can change the operator to `AND` by setting the `SALESFORCE_MATCHERS_OPERATOR` property:

```javascript
//...
event.SALESFORCE_MATCHERS_OPERATOR = "AND";
event.SALESFORCE_MATCHERS = {
  LastName: "Doe",
  FirstName: "John"
}
//...
```

This will match only record that has both `LastName` equal to "Doe" and `FirstName` equal to "John".


## Configuration

<DestinationConfiguration type="salesforce" />