> 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/architecture-and-development-guidelines.md).

# Architecture and development guidelines

System architecture, design patterns, and development guidelines for Birds Smart Connect

This section provides a comprehensive overview of Birds Smart Connect architecture, design patterns, and guidelines for customization and extension.

## Table of Contents

1. [System Overview](#system-overview)
2. [Core Components](#core-components)
3. [Data Flow](#data-flow)
4. [Extension Mechanisms](#extension-mechanisms)
5. [Design Patterns](#design-patterns)
6. [Configuration Model](#configuration-model)
7. [Best Practices](#best-practices)

***

## System Overview

### What is Birds Smart Connect?

Birds Smart Connect is a powerful integration platform for Microsoft Dynamics 365 Finance & Operations that:

* **Connects** D365 F\&O with external systems (ERP, EDI, APIs, file storage, message queues)
* **Transforms** data between different formats (XML, JSON, CSV, EDI, DMF)
* **Automates** data flow using triggered processors
* **Monitors** integration health through comprehensive logging and queuing
* **Extends** through pluggable handlers and connectors

### Key Principles

| Principle                   | Meaning                                             |
| --------------------------- | --------------------------------------------------- |
| **Separation of Concerns**  | Data handling (WHAT) separate from transport (HOW)  |
| **Pluggable Architecture**  | Add new handlers/connectors without modifying core  |
| **Configuration-Driven**    | Processors defined through UI, not code changes     |
| **Asynchronous Processing** | Queue-based with retry and error handling           |
| **Extensibility-First**     | Standard Microsoft Dynamics patterns for extensions |

***

## Core Components

### 1. Processors

**Purpose:** Define how data flows between F\&O and external systems

**Responsibilities:**

* Link data handler with connector
* Configure processor parameters
* Define triggers (batch, real-time, manual)
* Map F\&O fields to external format

**Key Tables:**

* `NANProcessorTable` - Processor master record
* `NANProcessorVariableTable` - Processor parameter values
* `NANProcessorEventTable` - Execution history

### 2. Data Handlers

**Purpose:** Transform and validate data between formats

**Types:**

* **Input Handlers** - Receive data from external systems
* **Output Handlers** - Send data to external systems

**Examples:**

* DMF Import/Export
* REST API data transformers
* EDI parsers
* Electronic Reporting (ER) handlers
* File format converters

**Key Concept:**

```
External System Data → Connector → Handler → D365 F&O
D365 F&O → Handler → Connector → External System Data
```

### 3. Connectors

**Purpose:** Transport data between Smart Connect and external systems

**Types:**

* **REST API** - HTTP/HTTPS endpoints
* **File Transfer** - SFTP, FTP, SMB shares
* **Cloud Storage** - Azure Blob, SharePoint
* **Message Queues** - Azure Service Bus
* **EDI Protocols** - AS2, SFTP-based EDI
* **DMS Systems** - Kofax integration

**Key Concept:**

```
Connector = Protocol + Authentication + Connection Management
```

### 4. Queue System

**Purpose:** Asynchronous message processing with retry logic

**How it works:**

```
1. Message received via trigger
   └─ Batch job, real-time event, or manual entry
   
2. Message queued
   └─ Written to NANQueueTable
   └─ Status = Pending
   
3. Queue processor executes
   └─ Dequeues messages
   └─ Instantiates handler
   └─ Executes processor logic
   
4. Result recorded
   └─ Success: Event logged, message removed
   └─ Failure: Retry count incremented
   └─ Max retries exceeded: Message marked as error
```

**Benefits:**

* Handles peak load gracefully
* Automatic retry with backoff
* Complete audit trail
* Asynchronous processing doesn't block F\&O

### 5. Event Logging

**Purpose:** Complete visibility into data movement

**Logged Information:**

* Processor executed
* Start and end time
* Success or failure
* Error messages
* Message ID for tracking
* Handler and connector used

**Key Table:**

* `NANProcessorEventTable` - All execution events

***

## Data Flow

### Inbound Flow (External → F\&O)

```
1. External System
   └─ File, API call, EDI message, etc.
   
2. Connector Receives Data
   └─ Downloads file, receives HTTP POST, polls queue
   └─ Data loaded into payload
   └─ Authentication verified
   
3. Smart Connect Queue
   └─ Message queued for processing
   └─ Reference stored for tracing
   
4. Processor Triggered
   └─ Handler instantiated with processor ID
   └─ Parameters loaded from NANProcessorVariableTable
   └─ Connector primed (authentication, setup)
   
5. Data Handler Processes
   └─ Input handler receives payload
   └─ Transforms external format → F&O format
   └─ Validates data
   └─ Calls appropriate X++ business logic
   
6. Data in F&O
   └─ Purchase orders created
   └─ GL transactions posted
   └─ Inventory updated
   └─ Sales invoices generated
   
7. Event Logged
   └─ Success: Event marked complete
   └─ Failure: Error details logged, retry queued
```

### Outbound Flow (F\&O → External)

```
1. Trigger in F&O
   └─ Document modified (PO, Invoice, etc.)
   └─ Batch job scheduled
   └─ Manual execution initiated
   
2. Data Handler Triggered
   └─ Handler instantiated
   └─ Reads data from F&O
   └─ Formats for external system
   └─ Adds payload to queue
   
3. Smart Connect Queue
   └─ Message queued
   └─ Outbound message ready
   
4. Connector Sends Data
   └─ Instantiated from processor
   └─ Authentication applied
   └─ Payload sent via appropriate protocol
   └─ Response captured
   
5. External System Receives
   └─ File downloaded
   └─ API endpoint processed
   └─ EDI message parsed
   └─ Queue message consumed
   
6. Event Logged
   └─ Delivery confirmation
   └─ Timestamps and details
   └─ Error handling if failed
```

***

## Extension Mechanisms

### 1. Custom Data Handlers

**When to use:**

* Need to support new data format
* Custom transformation logic required
* New source/destination system
* Specialized validation needed

**How to implement:**

1. Create class extending `NANHandlerIn` or `NANHandlerOut`
2. Override `processPayload()` or `handleOutput()`
3. Configure parameters via UI
4. Register in processor

**See:** [Extending Data Handlers](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-data-handlers.md)

### 2. Custom Connectors

**When to use:**

* Need new transport protocol
* Custom authentication method
* New cloud or file system
* Specialized network protocol

**How to implement:**

1. Create class extending `NANConnecter`
2. Apply `[NANConnecterAttribute]` marker
3. Implement `prime()` and `call()` methods
4. Register connector type (if new)
5. Configure in connector table

**See:** [Extending Connectors](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-connectors.md)

### 3. Custom Processor Types

**When to use:**

* Specialized processor logic
* Custom business rules
* Workflow integration

**How to implement:**

* Extend processor base class (if exists)
* Or use standard processor with custom handler

### 4. Processor Parameters

**How they work:**

* Stored in `NANProcessorVariableTable`
* Handler extracts via `processVariables` map
* No code changes needed for new parameters
* UI supports parameter lookup from tables

**Example:**

```
Handler instance reads parameter from map:
while (processVariables.moveNext())
{
    if (processVariables.currentKey() == 'ApiEndpoint')
    {
        parmApiEndpoint = processVariables.currentValue();
    }
}
```

***

## Design Patterns

### 1. Factory Pattern (Connector Discovery)

Connectors use Microsoft Dynamics 365 standard factory pattern:

```csharp
// Mark connector class with attribute
[NANConnecterAttribute(NANConnecterType::API)]
public class NANConnecterAPI extends NANConnecter { }

// Framework discovers using factory
NANConnecter connector = SysExtensionAppClassFactory::getClassFromSysAttribute(
    classStr(NANConnecter),
    new NANConnecterAttribute(connecterType)
);
```

**Benefits:**

* Loose coupling
* Runtime discovery
* Extensible without modifying core
* Follows Microsoft Dynamics standards

### 2. Reflection Pattern (Handler Discovery)

Handlers use reflection-based instantiation:

```csharp
// Handler class name stored in database
NANProcessorTable processor = NANProcessorTable::find(processId);
// Instantiate handler by name
NANHandler handler = new DictClass(className2Id(processor.HandlerId)).makeObject();
```

**Benefits:**

* Dynamic handler selection
* Handlers stored in database
* Supports third-party handlers

### 3. Strategy Pattern (Handler/Connector Polymorphism)

Different handlers implement same interface:

```
NANHandlerIn interface:
├── NANHandlerInDmf (strategy)
├── NANHandlerInAPI (strategy)
├── NANHandlerInCustom (strategy)
└── ... each implements processPayload() differently
```

### 4. Template Method Pattern (Handler Processing)

Base class defines algorithm, subclasses implement steps:

```csharp
// NANHandlerIn defines overall process()
public boolean process()
{
    try
    {
        return this.processPayload();  // Implemented by subclass
    }
    catch { /* error handling */ }
}

// Subclass implements specific step
public class NANHandlerInDmf extends NANHandlerIn
{
    protected boolean processPayload() { /* DMF-specific logic */ }
}
```

### 5. Observer Pattern (Event Logging)

Framework observes handler execution and logs events:

```
Handler execution
    ↓
Framework observes success/failure
    ↓
NANProcessorEventTable updated
    ↓
Dashboard/monitoring shows results
```

***

## Configuration Model

### Processor Configuration Hierarchy

```
NANProcessorTable (Master)
├── Processor ID
├── Handler Class Name (what to do)
├── Connector ID (how to transport)
├── Trigger Type (when to run)
├── Enable Telemetry (optional monitoring)
│
├─→ NANProcessorVariableTable (Parameters)
│   ├── ApiEndpoint
│   ├── DefinitionGroup
│   ├── Entity
│   └── ... (handler-specific)
│
├─→ NANConnecterTable (Transport)
│   ├── Service URL
│   ├── Authentication Type
│   ├── Credentials
│   └── ... (connector-specific)
│
└─→ NANQueueTable (Processing)
    ├── Queue entries
    ├── Retry count
    ├── Status (Pending, Completed, Error)
    └── Timestamp
```

### Parameter Lookup

Handlers can define parameter lookups for UI dropdowns:

```csharp
public void lookupParmValues(FormStringControl _control, str _parmField)
{
    // Implement lookup UI for 'ApiEndpoint' parameter
    // Values come from custom table
    // Selected value stored in NANProcessorVariableTable
}
```

***

## Best Practices

### 1. Handler Development

**Do:**

* ✅ Use try-catch for external system calls
* ✅ Set `goNoGo = false` on errors
* ✅ Provide meaningful error messages in `logInfo`
* ✅ Validate configuration parameters
* ✅ Document required parameters
* ✅ Use `super()` to call base class methods
* ✅ Reset map enumerators after iteration

**Don't:**

* ❌ Hardcode configuration values
* ❌ Use static fields for state (thread safety issues)
* ❌ Ignore error conditions
* ❌ Assume parameters are present (validate them)
* ❌ Modify NANProcessorTable directly

### 2. Connector Development

**Do:**

* ✅ Create connections in `prime()`, not `call()`
* ✅ Implement appropriate authentication
* ✅ Set `supportsWebMethods = true` if handling HTTP verbs
* ✅ Validate configuration before use
* ✅ Handle connection timeouts gracefully
* ✅ Use standard HTTP status code checking
* ✅ Implement all required HTTP methods

**Don't:**

* ❌ Create new connections for each request (performance)
* ❌ Hardcode credentials (use configuration)
* ❌ Ignore SSL/certificate validation (security)
* ❌ Leave connections open without timeout
* ❌ Assume successful response without checking status code

### 3. Error Handling

**Do:**

* ✅ Catch both CLRError and X++ exceptions
* ✅ Log detailed error information
* ✅ Provide user-friendly error messages
* ✅ Set appropriate flags (`goNoGo`, `error`)
* ✅ Distinguish between transient and permanent errors

**Don't:**

* ❌ Swallow exceptions silently
* ❌ Log generic "Error occurred" messages
* ❌ Leave `goNoGo` flag unset
* ❌ Retry permanent failures indefinitely

### 4. Performance

**Do:**

* ✅ Process large datasets in batches
* ✅ Reuse connections and clients
* ✅ Use streams for large payloads
* ✅ Set appropriate timeout values
* ✅ Profile custom handlers for bottlenecks

**Don't:**

* ❌ Load entire files into memory
* ❌ Make synchronous waits
* ❌ Process records one at a time in loops
* ❌ Ignore batch size recommendations

### 5. Security

**Do:**

* ✅ Validate all input data
* ✅ Use HTTPS for external APIs
* ✅ Store credentials securely (use connector credentials)
* ✅ Implement certificate validation
* ✅ Log security-relevant events
* ✅ Sanitize error messages (don't expose credentials)

**Don't:**

* ❌ Hardcode credentials in code
* ❌ Use HTTP for sensitive data
* ❌ Skip certificate validation
* ❌ Log passwords or API keys
* ❌ Trust input without validation

### 6. Testing

**Do:**

* ✅ Unit test handler logic with mock data
* ✅ Test error conditions
* ✅ Integration test with live system
* ✅ Test with various data sizes
* ✅ Document test cases
* ✅ Use Spy/mock objects for external systems

**Don't:**

* ❌ Only test the happy path
* ❌ Skip error scenario testing
* ❌ Rely only on integration tests
* ❌ Forget edge cases (empty data, special characters)
* ❌ Hardcode test data in production code

***

## Common Architectural Patterns

### 1. Simple Pass-Through Handler

```
External Data
    ↓
Handler (minimal transformation)
    ↓
F&O Table
```

**Example:** API → JSON handler → Sales order table

### 2. ETL Handler

```
External Data
    ↓
Handler (Extract)
    ↓
Handler (Transform)
    ↓
Handler (Load to F&O)
```

**Example:** Legacy system → Multiple validation handlers → F\&O

### 3. Broadcast Outbound

```
F&O Event
    ↓
Handler (format for multiple destinations)
    ↓
Connector 1 (File)
Connector 2 (API)
Connector 3 (EDI)
```

**Example:** Sales order → XML handler → File share + API + EDI

### 4. Hierarchical Data

```
Header Handler
    ↓
Child Handler 1
Child Handler 2
```

**Example:** Purchase order header → Line items with separate handlers

***

## Extension Point Summary

| Extension Point          | Mechanism                        | When to Use                           |
| ------------------------ | -------------------------------- | ------------------------------------- |
| **Data Handlers**        | Class inheritance + reflection   | New data format, transformation logic |
| **Connectors**           | Attribute-based factory          | New protocol, auth method, system     |
| **Processor Parameters** | UI configuration                 | Handler-specific options              |
| **Event Logging**        | Built-in (no extension needed)   | Monitoring/diagnostics                |
| **Queue Processing**     | Built-in (no extension needed)   | Async processing                      |
| **Triggers**             | Forms/tables with event handlers | Custom triggering logic               |

***

## Resources

### Detailed Guides

* [Extending Data Handlers](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-data-handlers.md) - Complete handler development guide
* [Extending Connectors](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-connectors.md) - Complete connector development guide
* [Testing and Debugging](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/testing-and-debugging.md) - Quality assurance guide

### Configuration

* [Processor Configuration](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/setup-and-configuration/processors.md) - How to set up processors
* [Connectors and Connectivity](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/connectors-and-connectivity.md) - Connector setup guide
* [Data Handlers Reference](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/data-handlers.md) - All built-in handlers

### Concepts

* [System Overview](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/overview-and-concepts/system-overview.md) - High-level concepts
* [Core Concepts](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/overview-and-concepts/core-concepts.md) - Terms and definitions

***

## Next Steps

1. **New to Smart Connect?**
   * Start with [System Overview](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/overview-and-concepts/system-overview.md)
   * Then [Core Concepts](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/overview-and-concepts/core-concepts.md)
2. **Want to extend with a handler?**
   * Read [Extending Data Handlers](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-data-handlers.md)
   * Review [Data Handlers Reference](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/data-handlers.md) for examples
3. **Want to extend with a connector?**
   * Read [Extending Connectors](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/architecture-and-development-guidelines/extending-connectors.md)
   * Review [Connectors and Connectivity](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/connectors-and-connectivity.md) for examples
4. **Setting up Smart Connect?**
   * See [Processors Setup](https://github.com/9altitudes/GTM-GitBook/tree/main/gitbook/products/birds-smart-connect/setup-and-configuration/processors.md)
   * See [Connectors Setup](https://docs.dynalogic.com/birds-smart-connect/setup-and-configuration/connectors-and-connectivity.md)

***

**Last updated:** 2026-11-13\
**Status:** Complete


---

# 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/architecture-and-development-guidelines.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.
