> For the complete documentation index, see [llms.txt](https://docs.dynalogic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/connectors-and-connectivity.md).

# Connectors and connectivity

Configure connectors to integrate Smart Connect with external systems and data sources.

Connectors are the gateway between Smart Connect and external systems. They define how data flows in and out of your Dynamics 365 Finance & Operations environment. This page covers connector setup, certificate management, and both Core and DMS connector types.

## What is a connector?

A connector defines a connection to an external system or data source. Each connector specifies:

* **Connection type** – How Smart Connect communicates (API, SFTP, HTTP, etc.)
* **Authentication** – Credentials and certificates for secure access
* **Data format** – How data is structured (XML, JSON, CSV, EDI, etc.)
* **Integration point** – Which Smart Connect queues or processors use this connector

## Connector selection and setup guide

### When to create a new connector

You need a connector whenever Smart Connect needs to communicate with an external system:

* **Real-time data sync** – Direct API calls to external systems
* **File-based integration** – Reading/writing to files (SFTP, network drives)
* **Document processing** – Routing to Document Warehouse (UBL, Exaccount, Tungstan)
* **Third-party services** – Cloud services, SaaS platforms, EDI partners
* **Legacy system integration** – On-premises systems with HTTP/SFTP access

### Connector selection matrix

Choose your connector type based on your integration scenario:

| Scenario                                             | Recommended type | Authentication                | Best for                   |
| ---------------------------------------------------- | ---------------- | ----------------------------- | -------------------------- |
| Cloud API integration (Salesforce, ServiceNow, etc.) | API              | OAuth 2.0 or API Key          | Real-time, secure web APIs |
| Secure file transfer to partners                     | SFTP             | SSH Keys or username/password | Batch file processing      |
| Local network or on-premises files                   | File             | Network credentials           | File system integration    |
| Legacy web services                                  | HTTP             | Basic Auth or Custom Headers  | Older systems              |
| E-invoicing compliance (EU)                          | UBL (DMS)        | Certificate                   | Document compliance        |
| Accounting document processing                       | Exaccount (DMS)  | API Key                       | Accounting workflows       |
| Purchase order workflows                             | Tungstan (DMS)   | Certificate                   | Procurement workflows      |

### Step-by-step connector creation workflow

Follow this workflow to create a new connector:

**Step 1: Determine external system requirements**

* What authentication method does the system support?
* What's the endpoint URL or file location?
* What data formats are supported (JSON, XML, CSV)?
* Are there IP restrictions or network requirements?

**Step 2: Select authentication method**

* Use the [Authentication method selection guide](#authentication-method-selection-guide) above
* For OAuth: Obtain Client ID and Client Secret
* For Certificate: Request .PFX file from IT department
* For API Key: Generate key in target system
* For SFTP: Generate SSH key pair
* For Basic Auth: Create service account (not personal account)

**Step 3: Create connector in Smart Connect**

* Navigate to **Smart Connect > Definitions > Connectors**
* Click **New**
* Fill in connector details (name, type, endpoint)
* Select authentication type

**Step 4: Configure authentication**

* Follow the authentication-specific procedure above
* Store credentials securely (Smart Connect encrypts automatically)
* Never share credentials in logs, email, or Slack

**Step 5: Test connection**

* Click **Test Connection** button
* Review result message
* ✅ Success: Move to Step 6
* ❌ Failure: Review [troubleshooting](#troubleshooting-connectors) section

**Step 6: Use in processor or queue**

* Connector is now available for processor/queue configuration
* Processors select connectors for outbound communication
* Queues can use connectors for transport
* Document Warehouse connectors route documents

### Creating a connector checklist

Before you use a connector in production, verify:

* [ ] External system endpoint verified and tested
* [ ] Authentication credentials obtained and tested
* [ ] Certificate or API key uploaded to Smart Connect
* [ ] Connector test connection passes
* [ ] Connector description documents its purpose
* [ ] Security review completed (especially for API keys)
* [ ] Firewall/network rules in place (if on-premises)
* [ ] Certificate renewal dates tracked (if certificate-based)
* [ ] Backup authentication method configured (if available)
* [ ] Connectors not used in production disabled

| Field                | Description                               | Required    | Notes                                                    |
| -------------------- | ----------------------------------------- | ----------- | -------------------------------------------------------- |
| Connector name       | Unique identifier for the connector       | Yes         | Use lowercase, hyphen-separated naming                   |
| Description          | Purpose and use of this connector         | No          | Helps team members identify its role                     |
| Connector type       | Connection method (API, SFTP, File, etc.) | Yes         | See connector types below                                |
| URL / Endpoint       | Target system address                     | Conditional | Required for API and HTTP types                          |
| Authentication type  | Certificate, API key, username/password   | Yes         | Depends on target system requirements                    |
| Active               | Enables or disables the connector         | Yes         | Disabled connectors are not used by processors or queues |
| Custom headers (API) | Additional HTTP headers for API calls     | No          | DMS only: used for specialized document APIs             |

### Connector types

#### Core connector types

**API Connector**

* RESTful API integration
* Authentication: API key, OAuth, certificate
* Use case: Real-time data exchange with third-party systems
* Examples: ERP systems, cloud services, SaaS platforms

**SFTP Connector**

* Secure File Transfer Protocol
* Authentication: SSH key pair or username/password
* Use case: File-based integration, batch data transfer
* Examples: Supplier portals, third-party logistics

**File Connector**

* Local or network file system
* Authentication: Network credentials (if remote)
* Use case: On-premises file processing, shared drives
* Examples: Local network drives, UNC paths

**HTTP Connector**

* Basic HTTP/HTTPS without SFTP
* Authentication: Custom headers, basic auth
* Use case: Simple web service integration
* Examples: Legacy web services, custom applications

#### DMS connector types (Document Management System)

{% hint style="info" %}
DMS connectors extend Core connectors to handle specialized document formats and integrate with **Birds Document Warehouse**.
{% endhint %}

**UBL Connector**

* Electronic invoice format (Universal Business Language)
* Authentication: Certificate-based
* Use case: E-invoicing and document exchange
* Document Warehouse integration: Validates UBL XML format, routes to Document Warehouse
* Examples: EU e-invoice compliance, cross-border invoicing

**Exaccount Connector (ExaRaptor)**

* Specialized accounting document connector
* Authentication: API key
* Use case: Accounting document processing
* Document Warehouse integration: Extracts accounting metadata, routes structured data to Document Warehouse
* Examples: Manual journal entries, accounting reports

**Tungstan Connector**

* Purchase order and goods receipt connector
* Authentication: API certificate
* Use case: Purchase workflow automation
* Document Warehouse integration: Captures and validates PO documents, stores in Document Warehouse
* Examples: Supplier purchase orders, goods receipt documents

## Connector authentication methods

Smart Connect supports multiple authentication methods depending on the target system. Choose the appropriate method based on your external system's requirements and security policies.

### Authentication method selection guide

Use this decision tree to select the right authentication approach:

```
Is your system a cloud service or web API?
├─ YES → Does it support OAuth 2.0?
│   ├─ YES → Use OAuth 2.0 (most secure for web APIs)
│   └─ NO → Does it require client certificates?
│       ├─ YES → Use Certificate Authentication
│       └─ NO → Use API Key or Custom Headers
└─ NO → Is it on-premises or file-based?
    ├─ File system/SFTP → Use SSH Keys or Username/Password
    └─ Legacy system → Use Basic Authentication or Custom Headers
```

### OAuth 2.0 Authentication

OAuth 2.0 is recommended for cloud APIs and modern web services. It provides secure token-based access without storing credentials.

#### Prerequisites

* Client ID and Client Secret from the OAuth provider
* Redirect URL (your F\&O instance URL)
* Authorization server endpoint URL
* Token endpoint URL

#### OAuth 2.0 setup procedure

1. **Obtain OAuth credentials from the external system**
   * Log into the target system's developer portal
   * Create a new application or API integration
   * Copy the Client ID and Client Secret to a secure location
   * Register your F\&O redirect URL (typically: `https://[your-instance].cloudax.dynamics.com/auth/oauth-redirect`)
   * Note the Authorization Server URL and Token Endpoint URL
2. **Create the connector in Smart Connect**
   * Navigate to **Smart Connect > Definitions > Connectors**
   * Click **New**
   * Fill in:
     * Connector name: `[system]-oauth` (e.g., `salesforce-oauth`)
     * Description: Purpose of this connector
     * Connector type: `API`
     * URL/Endpoint: OAuth token endpoint URL
     * Authentication type: `OAuth 2.0`
   * Click **Save**
3. **Configure OAuth parameters**
   * In the **Authentication** section, click **OAuth Configuration**
   * Enter:
     * Client ID: From step 1
     * Client Secret: From step 1 (encrypted storage)
     * Authorization endpoint: Authorization server URL
     * Token endpoint: Token endpoint URL
     * Scopes: Required access scopes (e.g., `read write` - check external system documentation)
   * Click **Save**
4. **Test the OAuth flow**
   * Click **Test Connection**
   * Browser redirects to OAuth provider for approval
   * Approve the integration in the external system
   * Browser returns to F\&O with access token
   * Verify: ✅ "OAuth token acquired successfully"
5. **Set token refresh parameters**
   * Access tokens typically expire after 1 hour
   * Smart Connect automatically refreshes tokens using the Refresh Token
   * No manual configuration needed after initial setup

#### OAuth testing and validation

| Test                     | Expected result                     | If fails                                               |
| ------------------------ | ----------------------------------- | ------------------------------------------------------ |
| Test Connection          | "OAuth token acquired successfully" | Check Client ID/Secret, verify redirect URL registered |
| First API call           | Succeeds with valid token           | OAuth token may have expired; test connection again    |
| After 1 hour             | Subsequent calls succeed            | Verify refresh token is valid, check token endpoint    |
| Revoke token in provider | Next call fails with "unauthorized" | Expected behavior; re-test connection to get new token |

#### OAuth troubleshooting

| Problem                 | Cause                                         | Solution                                               |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------ |
| "Invalid client ID"     | Client ID incorrect or not registered         | Verify in OAuth provider console, regenerate if needed |
| "Redirect URL mismatch" | Registered URL doesn't match F\&O instance    | Register correct URL in OAuth provider console         |
| "Access denied"         | Scopes insufficient or user lacks permissions | Check required scopes in provider documentation        |
| "Token expired"         | Token older than expiration time              | Click "Test Connection" to refresh                     |
| "Endpoint not found"    | Wrong authorization/token URL                 | Verify URLs from provider's API documentation          |

### Certificate Authentication

Certificate-based authentication uses X.509 certificates for mutual TLS authentication. Ideal for secure system-to-system integration.

#### Prerequisites

* .PFX or .CER certificate file
* Certificate password (if encrypted)
* CA certificate chain (sometimes required)
* Certificate must be valid and not expired

#### Certificate setup procedure

1. **Prepare the certificate**
   * Request .PFX certificate from your IT department or certificate authority
   * Extract password if the certificate is encrypted
   * Verify certificate validity: `openssl x509 -in cert.pem -noout -dates`
2. **Upload certificate to Smart Connect**
   * Navigate to **Smart Connect > Definitions > Certificates** (search for "NANConnecterCertificateTable")
   * Click **New**
   * Fill in:
     * Certificate name: `[target-system]-cert` (e.g., `sap-procurement-cert`)
     * Description: Purpose and issuer
     * Certificate file: Upload .PFX file
     * Password: Enter certificate password
     * Valid from / Valid to: Auto-populated (read-only)
   * Verify: **Active** checkbox is enabled
   * Click **Save**
3. **Create the connector**
   * Navigate to **Smart Connect > Definitions > Connectors**
   * Click **New**
   * Fill in:
     * Connector name: `[system]-cert`
     * Connector type: `API` or `HTTPS`
     * URL/Endpoint: Target system endpoint
     * Authentication type: `Certificate`
   * Click **Save**
4. **Associate certificate with connector**
   * In the **Authentication** section, select the certificate from step 2
   * Click **Save**
5. **Test the certificate connection**
   * Click **Test Connection**
   * Expected result: ✅ "Connection successful - certificate verified"

#### Certificate renewal procedure

Smart Connect checks certificate validity on every connection. Plan renewals before expiry:

1. **Before expiry (30+ days in advance)**
   * Request new certificate from your CA or IT department
   * Upload new certificate to NANConnecterCertificateTable with a new name or "Version 2" suffix
2. **Update connectors**
   * Edit each connector using the old certificate
   * Select new certificate in Authentication section
   * Click **Save** and test
3. **Archive or deactivate old certificate**
   * Edit old certificate entry
   * Uncheck **Active**
   * Click **Save**

#### Certificate troubleshooting

| Problem                      | Cause                                    | Solution                                           |
| ---------------------------- | ---------------------------------------- | -------------------------------------------------- |
| "Certificate expired"        | Certificate passed expiration date       | Renew certificate and update connector             |
| "Untrusted certificate"      | CA not in trust chain                    | Request CA certificate bundle from system provider |
| "Certificate not yet valid"  | Current date before "Valid from"         | Check system clock, adjust if needed               |
| "Wrong certificate for host" | Certificate CN doesn't match endpoint    | Verify certificate CN matches target URL           |
| "Password incorrect"         | Wrong password for encrypted certificate | Verify password with certificate provider          |

### API Key Authentication

Simple token-based authentication for APIs that use API keys instead of OAuth.

#### Prerequisites

* API key from the target system
* Endpoint URL
* Header name where key should be sent (usually `X-API-Key` or `Authorization`)

#### API key setup procedure

1. **Obtain API key**
   * Log into target system's settings or developer portal
   * Generate or copy API key
   * Verify key has correct permissions/scopes
2. **Create connector**
   * Navigate to **Smart Connect > Definitions > Connectors**
   * Click **New**
   * Fill in:
     * Connector name: `[system]-apikey`
     * Connector type: `API`
     * URL/Endpoint: Target system API URL
     * Authentication type: `API Key`
   * Click **Save**
3. **Configure API key**
   * In the **Authentication** section:
     * API Key: Paste the key (stored encrypted)
     * Header name: `X-API-Key` (or as specified by target system)
   * Click **Save** and test

#### API key best practices

* **Rotate keys regularly** (quarterly or semi-annually)
* **Never share keys** in logs, emails, or Slack
* **Use environment-specific keys** (separate keys for DEV/TEST/PROD)
* **Revoke old keys** after rotation
* **Monitor key usage** if provider supports it

### Basic Authentication

Username and password authentication for legacy systems and on-premises services.

#### Basic authentication setup

1. **Create connector**
   * Navigate to **Smart Connect > Definitions > Connectors**
   * Click **New**
   * Fill in:
     * Connector name: `[system]-basic`
     * Connector type: `HTTP` or `API`
     * URL/Endpoint: Target system URL
     * Authentication type: `Basic`
   * Click **Save**
2. **Configure credentials**
   * In the **Authentication** section:
     * Username: Service account username
     * Password: Service account password (encrypted)
   * Click **Save** and test

#### Credentials security

* **Use service accounts** - Create dedicated low-privilege accounts for integration
* **Rotate passwords quarterly** - Change integration account passwords regularly
* **Disable account login** - Service accounts should not be used for interactive login
* **Monitor account activity** - Check target system logs for integration account access

### SSH Key Authentication (SFTP)

Secure key-based authentication for file transfer protocols.

#### SFTP SSH key setup

1. **Generate SSH key pair** (if not already created)
   * Use `ssh-keygen` or OpenSSH tools
   * Create 2048-bit RSA key minimum
   * Save private key securely, share public key with target system
2. **Upload private key to Smart Connect**
   * Navigate to **Smart Connect > Definitions > Certificates**
   * Click **New**
   * Fill in:
     * Certificate name: `[sftp-server]-ssh-key`
     * Certificate file: Upload private key file
     * Password: Enter passphrase (if key is encrypted)
   * Click **Save**
3. **Create SFTP connector**
   * Navigate to **Smart Connect > Definitions > Connectors**
   * Click **New**
   * Fill in:
     * Connector name: `[sftp-server]`
     * Connector type: `SFTP`
     * URL/Endpoint: `sftp://hostname.example.com:22`
     * Authentication type: `SSH Key`
   * Click **Save**
4. **Associate SSH key**
   * In **Authentication** section, select the SSH key certificate
   * Click **Save** and test

## Custom API headers

For DMS connectors or specialized APIs that require custom HTTP headers beyond standard authentication.

### Setting up custom headers

Custom headers are configured through the Smart Connect custom header form.

Navigate to **Smart Connect > Definitions > Connectors** and locate **Custom Headers** section, or search for "NANConnecterCustomAPIHeaderTable".

1. **Add header**
   * Click **New**
   * Fill in:
     * Header name: HTTP header name (e.g., `X-API-Key`, `X-Custom-Auth`)
     * Header value: Header value (encrypted for security)
     * Connector: Select connector this applies to
     * Active: Enable header
   * Click **Save**
2. **Multiple headers**
   * Add multiple rows for different header requirements
   * Each header is sent on every request

| Field        | Description              | Example          |
| ------------ | ------------------------ | ---------------- |
| Header name  | HTTP header name         | `X-API-Version`  |
| Header value | Header value (encrypted) | `2023-11-01`     |
| Connector    | Target connector         | `salesforce-api` |
| Active       | Enable/disable           | ☑ Yes            |

### Common custom headers for DMS

| Header            | Purpose                    | DMS Connector  |
| ----------------- | -------------------------- | -------------- |
| `X-API-Version`   | API version specification  | Exaccount, UBL |
| `X-Document-Type` | Document classification    | Tungstan, UBL  |
| `X-Warehouse-ID`  | Document Warehouse routing | All DMS        |
| `Accept-Encoding` | Compression type           | All            |

## Certificate and API key management

### Certificate management interface

Certificates for connector authentication are managed through the Smart Connect certificate form.

Open the form by searching for "NANConnecterCertificateTable" in the F\&O search.

**Recommended workflow:**

1. Create new certificate before old one expires
2. Test with new certificate
3. Update production connectors
4. Deactivate old certificate (month after switchover)
5. Archive old certificate (after 12 months)

## Testing a connector

Before using a connector in a queue or processor, test the connection:

1. Go to **Smart Connect > Definitions > Connectors**
2. Select the connector
3. Click **Test Connection**
4. Review the result message
   * ✅ Success: Connection is working
   * ❌ Failed: Check certificate validity, endpoint URL, and network access

## Troubleshooting connectors

| Issue                        | Possible cause                                       | Solution                                                            |
| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| Connection timeout           | Network connectivity, firewall, endpoint unavailable | Verify endpoint URL, check network access, confirm firewall rules   |
| 401 Unauthorized             | Invalid credentials or certificate                   | Verify certificate validity, check expiration date, confirm API key |
| 403 Forbidden                | Missing permissions on target system                 | Contact target system admin, verify account permissions             |
| Certificate error            | Expired or invalid certificate                       | Renew certificate, ensure it's in correct format                    |
| Custom header not sent (DMS) | Header not configured or connector not active        | Verify header configuration, confirm connector is active            |

## Related pages

* [Queues and message handling](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/queues-and-message-handling.md)
* [Document processing and formats](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/document-processing-and-formats.md) (DMS)
* [Data flow and architecture](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/concepts-and-processes/data-flow-and-architecture.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/connectors-and-connectivity.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
