> ## 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.

# Get started

> Complete end-to-end configuration guide for integrating with Salesforce CRM platform

Before you configure the Salesforce Connector, make sure you have the following credentials and connectivity:

* Follow the steps in [Get started](/connectors/getting-started).
* **Salesforce access**: An active account in the Salesforce production or sandbox environment.
* **Network connectivity**: Verify that your network routes traffic between the Salesforce environment and Grand Central iPaaS. For supported options, see [Network connectivity](/platform/network-connectivity).

## Configuration guide

Follow these steps to initialize and authorize your Salesforce Connector.

### 1. Establish connectivity

Share connectivity details between Grand Central and Salesforce as described in [Network connectivity](/platform/network-connectivity).

### 2. Salesforce authentication

The Salesforce Connector uses OAuth 2.0 authentication for API access. To configure authentication, create a Secrets Operations (SOPS) secret. For more information, see [How to create SOPS](/platform/developer-guides/build/configure-connector).

<Info>
  To share credentials between Salesforce and Grand Central, consider using 1Password.
</Info>

### 3. Environment configuration

To initialize the Salesforce Connector, define the required environment variables in your `gc-applications-live` repository.

These variables are stored in `values.yaml` for configuration common to all connectors, and in the following files for connector-specific configuration:

| Connector                          | Property                  | Description                                                |
| ---------------------------------- | ------------------------- | ---------------------------------------------------------- |
| `gc-salesforce-party-connector`    | `party-v0.values.yaml`    | Outbound party v0 connector for CRM operations             |
| `gc-salesforce-party-connector`    | `party-v2.values.yaml`    | Outbound party v2 connector for CRM operations             |
| `gc-salesforce-activity-connector` | `activity-v0.values.yaml` | Outbound activity connector (create, update, get by party) |

For the full property list, including defaults and descriptions, see [Reference](/connectors/crm/salesforce/reference).

### Define common parameters

These variables are stored in `values.yaml` and are used across all Salesforce connectors:

| Parameter               | Description                                                 | Example value                  |
| ----------------------- | ----------------------------------------------------------- | ------------------------------ |
| `existingSecretName`    | Reference to SOPS secret containing Salesforce credentials. | `salesforce`                   |
| `gc.sf.client.loginUrl` | Login URL for Salesforce environment.                       | `https://login.salesforce.com` |

<Warning>
  Store all sensitive credentials (client ID, client secret, username, password, and optionally refresh token) in a SOPS secret. Never include credentials directly in values files.
</Warning>

The following example shows the `values.yaml` configuration:

```yaml theme={"system"}
# Common Salesforce Configuration
# Place this in: values.yaml
connector:
  existingSecretName: salesforce
  properties:
    # Salesforce Connection Settings
    # gc.sf.client.loginUrl: <Salesforce_Login_URL>
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

### Define party v0 connector parameters

Configure the party v0 connector with secret reference (`party-v0.values.yaml`):

```yaml theme={"system"}
# Salesforce Party v0 Connector Configuration
# Place this in: party-v0.values.yaml
connector:
  existingSecretName: salesforce
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

### Define party v2 connector parameters

Configure the party v2 connector with secret reference (`party-v2.values.yaml`):

```yaml theme={"system"}
# Salesforce Party v2 Connector Configuration
# Place this in: party-v2.values.yaml
connector:
  existingSecretName: salesforce
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

### Define activity connector parameters

The `activity-v0.values.yaml` file configures create, update, and get-activities-by-party for Salesforce Task and Event sObjects. It includes SOQL field lists, Who (Contact) fields, recurrence maps, and party ID validation.

```yaml theme={"system"}
# Salesforce Activity Connector Configuration
# Place this in: activity-v0.values.yaml
connector:
  existingSecretName: salesforce
  properties:
    # SOQL SELECT columns for get-activities-by-party (Task / Event)
    gc.sf.task.query.fields: "Id, AccountId, WhatId, WhoId, OwnerId, Subject, Description, Status, Priority, TaskSubtype, CallType, ActivityDate, IsReminderSet, ReminderDateTime, IsRecurrence, RecurrenceType, RecurrenceStartDateOnly, RecurrenceEndDateOnly, RecurrenceInterval, RecurrenceDayOfMonth, RecurrenceActivityId, Owner.Name, Owner.Email"
    gc.sf.event.query.fields: "Id, AccountId, WhatId, WhoId, OwnerId, Subject, Description, Location, EventSubtype, ActivityDate, DurationInMinutes, IsReminderSet, ReminderDateTime, Recurrence2PatternText, Owner.Name, Owner.Email"
    # Event recurrence: RRULE FREQ -> GC frequency.unit (create/update invert)
    gc.sf.event.recurrence.frequency.units: "DAILY:Days,WEEKLY:Weeks,MONTHLY:Months,YEARLY:Years"
    # Task weekly RecurrenceDayOfWeekMask
    gc.sf.task.recurrence.day.of.week.mask: "SUNDAY:1,MONDAY:2,TUESDAY:4,WEDNESDAY:8,THURSDAY:16,FRIDAY:32,SATURDAY:64"
    # Event RRULE BYDAY tokens
    gc.sf.event.recurrence.byday: "SUNDAY:SU,MONDAY:MO,TUESDAY:TU,WEDNESDAY:WE,THURSDAY:TH,FRIDAY:FR,SATURDAY:SA"
    # Contact columns using polymorphic Who (TYPEOF Who WHEN Contact THEN ...)
    gc.sf.who.contact.fields: "Name, Email, Phone"
    regex.party-id.pattern: "^[a-zA-Z0-9]{15,18}$"
    regex.party-id.failure-message: "partyId must be a 15 or 18 character Salesforce id."
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

Place the values files at the following paths:

```text theme={"system"}
iPaaS/azure/runtimes/{runtime}/values/gc-salesforce/
├── values.yaml
├── party-v0.values.yaml
├── party-v2.values.yaml
└── activity-v0.values.yaml
```

***

## Testing your integration

To access the Unified API, include your Grand Central subscription key in the request header. If you don't have a key, contact the Grand Central Support Team to request one.

| Header    | Value                     |
| --------- | ------------------------- |
| `api-key` | `<your_subscription_key>` |

Test the API using the <a href="https://github.com/bb-ecos-ecos/grandcentral-documentation/blob/main/Postman-Collection/Salesforce%20CRM%20Collections/Salesforce%20CRM%20Collections.postman_collection.json" target="_blank">Postman collection</a>.

## Troubleshooting

If your connector isn't responding as expected, check these common scenarios.

<AccordionGroup>
  <Accordion title="5XX: Internal server error / Core system is down" icon="lock">
    **Cause:** The Grand Central gateway cannot establish a handshake with the Salesforce endpoint. This typically indicates an upstream service outage at Salesforce or a network routing failure.

    **Solution:** Verify the operational status of the Salesforce environment. Check the Salesforce status page or contact Salesforce support. If the service is operational, contact [Grand Central Support](mailto:support@grandcentral.io).
  </Accordion>

  <Accordion title="5XX: Timeout from core / Read timeout / SocketTimeoutException" icon="wifi-slash">
    **Cause:** The request to Salesforce exceeded the configured timeout period. This may indicate performance issues at Salesforce or network latency problems.

    **Solution:** Verify the operational status of the Salesforce environment and check for any performance degradation. If the service is operational and performing normally, contact [Grand Central Support](mailto:support@grandcentral.io).
  </Accordion>

  <Accordion title="401: Invalid authentication credentials" icon="key">
    **Cause:** The OAuth credentials provided during setup are incorrect, expired, or you lack the required permissions in Salesforce.

    **Solution:** Re-verify your credentials with your Salesforce administrator and ensure you have the required permissions. Contact the Grand Central team to update the connection credentials if needed.
  </Accordion>

  <Accordion title="NOT_FOUND / MALFORMED_ID errors" icon="magnifying-glass">
    **Cause:** The party ID or activity ID (Salesforce Contact / Task / Event ID) you include in the request is invalid or does not exist in Salesforce.

    **Solution:** Verify that the ID is a valid Salesforce identifier (15 or 18 characters). Check that the Contact, Task, or Event exists in your Salesforce org and the ID format is correct.
  </Accordion>

  <Accordion title="429: Rate limit exceeded" icon="gauge-high">
    **Cause:** The number of incoming requests exceeds the defined threshold for your subscription tier. This "429 Too Many Requests" response protects the stability of the Grand Central and Salesforce infrastructure.

    **Solution:** Review your app's request patterns to identify unexpected spikes. If you need higher throughput, contact the Grand Central team to request a higher rate limit.
  </Accordion>
</AccordionGroup>

***

## Need more help?

<Card title="Contact support" icon="envelope" href="mailto:support@grandcentral.io">
  Contact the Grand Central team for help with environment setup or rate limit increases.
</Card>