> ## Documentation Index
> Fetch the complete documentation index at: https://grandcentral.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> Configuration properties, operations, and error mapping for the Salesforce connector.

The Salesforce integration retrieves and updates customer party data and manages activities (Task and Event) in Salesforce CRM through the Salesforce API v56.0. Grand Central delivers the integration as outbound (synchronous) connectors. For setup steps, see [Get started](/connectors/crm/salesforce/get-started).

**Supported version:** Salesforce API v56.0.

| Connector                          | Property file                                  | Purpose                                                         |
| :--------------------------------- | :--------------------------------------------- | :-------------------------------------------------------------- |
| `gc-salesforce-party-connector`    | `party-v0.values.yaml`, `party-v2.values.yaml` | Outbound party retrieval and update for both party API versions |
| `gc-salesforce-activity-connector` | `activity-v0.values.yaml`                      | Outbound create, update, and get activities by party            |

## Configuration properties

### Common properties

Set these properties in `values.yaml`. They apply across Salesforce connectors.

| Property                               | Description                                                          | Default                        |
| :------------------------------------- | :------------------------------------------------------------------- | :----------------------------- |
| `existingSecretName`                   | Name of the SOPS secret that holds the Salesforce OAuth credentials. | `salesforce`                   |
| `gc.sf.client.loginUrl`                | Login URL for the Salesforce environment.                            | `https://login.salesforce.com` |
| `gc.sf.client.authType`                | OAuth authentication type for the Salesforce client.                 | `USERNAME_PASSWORD`            |
| `http.client.connect.timeout`          | HTTP connect timeout, in milliseconds.                               | `5000`                         |
| `http.client.request.timeout`          | HTTP request timeout, in milliseconds.                               | `10000`                        |
| `http.client.socket.timeout`           | HTTP socket timeout, in milliseconds.                                | `5000`                         |
| `http.client.connection.max.per.route` | Maximum HTTP connections per route.                                  | `200`                          |
| `http.client.connection.max.total`     | Maximum total HTTP connections.                                      | `200`                          |
| `retryFlag`                            | Enable automatic request retries on connection failure.              | `false`                        |
| `retry.statuses`                       | HTTP status codes that trigger a retry.                              | `0`                            |
| `redelivery.maximumRetries`            | Maximum number of redelivery attempts.                               | `3`                            |
| `redelivery.delay`                     | Initial delay between redelivery attempts, in milliseconds.          | `200`                          |
| `redelivery.backOffMultiplier`         | Backoff multiplier for redelivery attempts.                          | `2`                            |

### gc-salesforce-activity-connector

Set these properties in `activity-v0.values.yaml`. They configure create activity (`POST /activities`), update activity (`PUT /activities/{activityId}`), and get activities by party (`POST /activities/partyId`).

| Property                                 | Description                                                                                                            | Default                                                                                                      |
| :--------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| `gc.sf.task.query.fields`                | Comma-separated SOQL columns selected for Task rows on get-by-party.                                                   | See the sample in [Get started](/connectors/crm/salesforce/get-started#define-activity-connector-parameters) |
| `gc.sf.event.query.fields`               | Comma-separated SOQL columns selected for Event rows on get-by-party.                                                  | See the sample in [Get started](/connectors/crm/salesforce/get-started#define-activity-connector-parameters) |
| `gc.sf.who.contact.fields`               | Contact fields the connector reads using SOQL `TYPEOF Who WHEN Contact THEN ...` (appended to Task and Event queries). | `Name, Email, Phone`                                                                                         |
| `gc.sf.event.recurrence.frequency.units` | Maps RRULE `FREQ` tokens to Grand Central `frequency.unit` (create/update invert the same map).                        | `DAILY:Days,WEEKLY:Weeks,MONTHLY:Months,YEARLY:Years`                                                        |
| `gc.sf.task.recurrence.day.of.week.mask` | Maps Grand Central day-of-week names to Salesforce `RecurrenceDayOfWeekMask` bit values.                               | `SUNDAY:1,MONDAY:2,TUESDAY:4,WEDNESDAY:8,THURSDAY:16,FRIDAY:32,SATURDAY:64`                                  |
| `gc.sf.event.recurrence.byday`           | Maps Grand Central day-of-week names to RRULE `BYDAY` tokens.                                                          | `SUNDAY:SU,MONDAY:MO,TUESDAY:TU,WEDNESDAY:WE,THURSDAY:TH,FRIDAY:FR,SATURDAY:SA`                              |
| `regex.party-id.pattern`                 | Validation pattern for party identifiers (Salesforce Contact ID).                                                      | `^[a-zA-Z0-9]{15,18}$`                                                                                       |
| `regex.party-id.failure-message`         | Message the connector returns when party ID validation fails.                                                          | `partyId must be a 15 or 18 character Salesforce id.`                                                        |

<Info>
  Create and update map Grand Central activity payloads to Salesforce Task or Event using JOLT specs in `gc-salesforce-activity-connector`, including SDK enrich transforms for Task recurrence bitmask/month and Event duration, start time, and RRULE. Get-by-party runs SOQL against Task and Event using the field lists you set in configuration, then maps results to the Grand Central activity response contract. Set the recurrence map properties in `activity-v0.values.yaml` for create and update; they aren't bundled as defaults in the connector JAR.
</Info>

## SOPS secrets

The connectors read the Salesforce OAuth 2.0 credentials from the `salesforce` SOPS secret. Which secret fields are required depends on `gc.sf.client.authType` (`USERNAME_PASSWORD` by default; also `REFRESH_TOKEN` or `CLIENT_CREDENTIALS`).

| Variable        | Description                                                                                        |
| :-------------- | :------------------------------------------------------------------------------------------------- |
| `client ID`     | Salesforce connected app client ID.                                                                |
| `client secret` | Salesforce connected app client secret.                                                            |
| `username`      | Salesforce integration user name. Required for `USERNAME_PASSWORD`.                                |
| `password`      | Salesforce integration user password. Required for `USERNAME_PASSWORD`.                            |
| `refresh token` | Salesforce OAuth refresh token. Add when using `REFRESH_TOKEN` auth (`gc.sf.client.refreshToken`). |

## Supported operations

The Salesforce connectors expose party and activity operations of the Grand Central Unified API. For the operation-to-endpoint tables, see [Overview](/connectors/crm/salesforce/overview). For the full contract, see the [unified API specifications](/connectors/reference/unified-api-specifications).

| Method                                         | Endpoint                   | Purpose                                |
| :--------------------------------------------- | :------------------------- | :------------------------------------- |
| <span className="http-method-get">GET</span>   | `/parties/{partyId}`       | Get party details.                     |
| <span className="http-method-put">PUT</span>   | `/parties/{partyId}`       | Update party details.                  |
| <span className="http-method-post">POST</span> | `/activities`              | Create a Task or Event activity.       |
| <span className="http-method-put">PUT</span>   | `/activities/{activityId}` | Update a Task or Event activity by ID. |
| <span className="http-method-post">POST</span> | `/activities/partyId`      | Get activities for a party (Contact).  |

### Get activities by party request fields

`POST /activities/partyId` accepts the following fields in the request body (from the Grand Central Unified API). For the full contract, see the [unified API specifications](/connectors/reference/unified-api-specifications).

| Field      | Source           | Description                                                                | Default        |
| :--------- | :--------------- | :------------------------------------------------------------------------- | :------------- |
| `partyId`  | API request body | Salesforce Contact ID used as `WhoId` in Task and Event SOQL.              | N/A (required) |
| `from`     | API request body | Page number for pagination. Values of `0` or less are treated as page `1`. | `1`            |
| `size`     | API request body | Page size. Must be `1` or greater.                                         | `20`           |
| `fromDate` | API request body | Inclusive lower bound filter on Salesforce `ActivityDate`.                 | N/A (optional) |
| `toDate`   | API request body | Inclusive upper bound filter on Salesforce `ActivityDate`.                 | N/A (optional) |

The connector queries Task and Event in parallel, merges the results (Tasks then Events), then applies the `from`/`size` page slice. If `from` and `size` together exceed the fetch limit of `2000`, the connector returns Grand Central error `GC051`.

## Events

`gc-salesforce-party-connector` and `gc-salesforce-activity-connector` are synchronous and don't publish or consume events.

## Error mapping

The connectors map Salesforce error codes to Grand Central status codes. For the full list, see [Error codes](/connectors/reference/error-codes).

## Dependencies

* Salesforce API v56.0 (outbound), reachable through the environment configured by `gc.sf.client.loginUrl`.
* `salesforce-connector-sdk` (shared HTTP configuration, Salesforce OAuth handling, and activity JOLT enrich transforms).