> ## 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 Microsoft Dataverse CRM platform

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

* Follow the steps in [Get started](/connectors/getting-started).
* **Microsoft Dataverse access**: An active Dataverse environment with required API permissions.
* **Network connectivity**: Verify that your network routes traffic between the Dataverse environment and Grand Central iPaaS. For supported options, see [Network connectivity](/platform/network-connectivity).

## Configuration guide

Follow these steps to initialize and authorize your Microsoft Dataverse Connector.

### 1. Establish connectivity

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

### 2. Microsoft Dataverse authentication

The Microsoft Dataverse 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 Microsoft Dataverse and Grand Central, consider using 1Password.
</Info>

### 3. Environment configuration

To initialize the Microsoft Dataverse 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-dataverse-party-connector`         | `party-v0.values.yaml`         | Outbound party connector for CRM operations                     |
| `gc-dataverse-party-inbound-connector` | `party-inbound-v0.values.yaml` | Inbound party connector to receive party updates from Dataverse |

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

### Define common parameters

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

| Parameter        | Description                                     | Example value         |
| ---------------- | ----------------------------------------------- | --------------------- |
| `retryFlag`      | Enable automatic request retries.               | `true`                |
| `retry.statuses` | HTTP status codes that trigger automatic retry. | `429,500,502,503,504` |

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

```yaml theme={"system"}
# Common Microsoft Dataverse Configuration
# Place this in: values.yaml
connector:
  properties:
    # Retry Configuration
    # retryFlag: <true|false>
    # retry.statuses: <Status1>,<Status2>,...
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

Place the values files at the following paths:

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

### Define party outbound connector parameters

The following variables apply to outbound requests from Grand Central to Dataverse (`party-v0.values.yaml`):

| Parameter                | Description                                                           | Example value                                      |
| ------------------------ | --------------------------------------------------------------------- | -------------------------------------------------- |
| `dataverse.serviceUri`   | Target API endpoint for Dataverse including API version.              | `https://ssdev.api.crm.dynamics.com/api/data/v9.2` |
| `dataverse.resourcePath` | Resource path for Dataverse entity (for example, contacts for party). | `/contacts`                                        |

The following example shows the party v0 configuration:

```yaml theme={"system"}
# Microsoft Dataverse Party v0 Outbound Configuration
# Place this in: party-v0.values.yaml
connector:
  properties:
    # Dataverse Connection Settings
    # dataverse.serviceUri: <Dataverse_API_Endpoint>
    # dataverse.resourcePath: <Resource_Path>
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

### Define party inbound connector parameters

Configure how Grand Central receives asynchronous updates from Dataverse for create, update, and delete events (`party-inbound-v0.values.yaml`):

| Parameter             | Description                                       | Example value                                               |
| --------------------- | ------------------------------------------------- | ----------------------------------------------------------- |
| `asb.event.version`   | Version of the Async Service Bridge (ASB) schema. | `1.0.0`                                                     |
| `asb.event.type`      | The ASB event type for outgoing messages.         | `com.backbase.party.event.spec.v1.PartyUpdateEvent`         |
| `asb.event.source`    | The ASB source for outgoing messages.             | `com.backbase.party`                                        |
| `asb.event.topic`     | The ASB topic for outgoing messages.              | `party-updates`                                             |
| `asb.producer.apiUri` | The callback URI for receiving incoming events.   | `http://asb-producer-v0.synchub-producer.svc.cluster.local` |

The following example shows the party inbound configuration:

```yaml theme={"system"}
# Microsoft Dataverse Party Inbound Configuration
# Place this in: party-inbound-v0.values.yaml
connector:
  customLabels:
    app.gcservices.io/synchub-enabled: "true"
    app.gcservices.io/synchub-type: "producer"
  properties:
    # ASB Configuration
    # asb.event.type: <Event_Type>
    # asb.event.source: <Event_Source>
    # asb.event.version: <Event_Version>
    # asb.event.topic: <Topic_Name>
    # asb.producer.apiUri: <Producer_API_URI>
  traits:
    knativeservice:
      minScale: 0
    logging:
      level: INFO
```

<Info>
  Register your Grand Central inbound endpoint as a webhook in Dataverse, and filter the events to only the tables and columns you need.
</Info>

***

## Testing the connector

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 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/tree/main/Postman-Collection" target="_blank">Postman collection</a>.

<Info>
  **Webhook registration:** To process asynchronous updates, register your environment callback URL in your Dataverse webhook configuration.
</Info>

## 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 Microsoft Dataverse endpoint. This typically indicates an upstream service outage at Microsoft or a network routing failure.

    **Solution:** Verify the operational status of the Dataverse environment. Check the Microsoft status page or contact Microsoft 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 Microsoft Dataverse exceeded the configured timeout period. This may indicate performance issues at Microsoft or network latency problems.

    **Solution:** Verify the operational status of the Dataverse 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 OAuth token" icon="key">
    **Cause:** The OAuth app credentials provided during setup are incorrect, expired, or you lack the required permissions in Dataverse.

    **Solution:** Re-verify your Dataverse app registration credentials with your Microsoft 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_REQUEST errors" icon="magnifying-glass">
    **Cause:** The party ID (Dataverse contact ID) provided in the request is invalid or does not exist in Dataverse.

    **Solution:** Verify that the party ID is a valid Dataverse contact ID. Check that the contact exists in your Dataverse environment, and that 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 Microsoft Dataverse 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>