How to Build a Native .NET 8/10 Integration for Rockwell's Fiix CMMS (Without the Headache)

C-SHA256 | | Typed .NET Client Library | High (DI Injection) | Managed via IHttpClientFactory | Mock Server Included | Automated Signing |

Why This Matters: The typed approach provides 103 strongly-typed DTOs mapped 1:1 with the underlying schema engine. This eliminates manual JSON parsing and reduces integration code by approximately 60%. Furthermore, the inclusion of a local Mock API server decouples development from sandbox availability, enabling continuous integration pipelines to run integration tests without network dependencies.

Core Solution

The recommended architecture utilizes a native .NET 8/10 client library that acts as a first-class ecosystem citizen. The implementation relies on IServiceCollection extensions backed by IHttpClientFactory to manage connection lifecycles, while automating the cryptographic signing process.

Architecture Decisions

1. Dependency Injection: The client is registered as a typed service, ensuring that configuration is centralized and instances are managed by the container.
2. Connection Management: IHttpClientFactory is used to pool connections, preventing socket exhaustion and handling DNS updates automatically.
3. Automated Signing: An HTTP message handler intercepts outgoing requests to compute and attach HMAC-SHA256 headers, removing cryptographic logic from business code.
4. Mock Simulation: A standalone RPC simulation engine allows for zero-dependency testing, mirroring the live API behavior locally.

Implementation Guide

1. Service Registration

Configure the client in Program.cs using the provided extension method. This binds the configuration to the client lifecycle and activates the automatic signing handler.

using Microsoft.Extensions.DependencyInjection;
using FiixIntegration.Core;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFiixGateway(config =>
{
    config.Endpoint = builder.Configuration["Fiix:BaseUrl"];
    config.Credentials = new FiixAuthCredentials
    {
        AppKey = builder.Configuration["Fiix:AppKey"],
        AccessKey = builder.Configuration["Fiix:AccessKey"],
        SecretKey = builder.Configuration["Fiix:SecretKey"]
    };
});

2. Service Consumption

Inject the typed client interface into your application services. The interface exposes strongly-typed methods for common operations, such as asset management and work order processing.

public class AssetHealthMonitor
{
    private readonly IFiixApiService _gateway;

    public AssetHealthMonitor(IFiixApiService gateway)
    {
        _gateway = gateway;
    }

    public async Task FlagCriticalAssetAsync(string assetCode)
    {
        // Fetch asset using strongly-typed DTO
        var asset = await _gateway.Assets.FetchByCodeAsync(assetCode);
        
        // Update status using enum mapping
        asset.MaintenanceStatus = AssetStatus.Critical;
        asset.LastInspection = DateTimeOffset.UtcNow;

        // Synchronize changes via RPC pipeline
        await _gateway.Assets.SynchronizeAsync(asset);
    }
}

3. Offline Testing Strategy

For unit tests and CI/CD pipelines, configure the client to point to the local Mock API server. This eliminates network latency and rate-limit constraints during development.

// Test configuration
var testServices = new ServiceCollection();
testServices.AddFiixGateway(config =>
{
    config.Endpoint = "http://localhost:5000/mock-api"; // Mock server URL
    config.UseMockMode = true;
});

Pitfall Guide

Production integrations with Fiix require careful attention to specific operational constraints. The following pitfalls are common in custom implementations and how to mitigate them.

Pitfall	Explanation	Mitigation Strategy
HMAC Timestamp Drift	The API validates request timestamps. If the server clock drifts significantly from the API server, requests are rejected with authentication errors.	Ensure the host environment is synchronized via NTP. The client library should include clock skew tolerance logic.
RPC Payload Depth	Fiix uses nested RPC structures. Manual serialization often fails to handle deep object graphs or specific field naming conventions.	Rely exclusively on the provided 103 DTOs. Avoid custom serialization logic for core entities.
Socket Exhaustion	Creating new HttpClient instances per request consumes ephemeral ports, leading to SocketException under load.	Use IHttpClientFactory via the library's registration method. Never instantiate HttpClient directly in business logic.
Sandbox Dependency	Development stalls when the sandbox environment is locked by other teams or undergoing maintenance.	Utilize the Mock API server for local development and CI pipelines. Reserve sandbox usage for final validation.
Rate Limiting Violations	Burst requests to asset or work order endpoints can trigger temporary IP bans.	Implement retry policies with exponential backoff. The client library should expose hooks for resilience patterns.
Credential Leakage	Storing SecretKey in plain text configuration files poses a security risk.	Use secret management tools (e.g., Azure Key Vault, Docker Secrets). Ensure credentials are injected at runtime.
Version Drift	API schema changes can break custom DTOs, causing runtime deserialization errors.	Use a library that adheres to SemVer and updates DTOs in lockstep with API releases. Monitor release notes for schema changes.

Production Bundle

Action Checklist

• Secure Credentials: Store AppKey, AccessKey, and SecretKey in a secure secret manager, not in source control.
• Enable Mock Mode: Configure the Mock API server for all unit tests and local development environments.
• Implement Resilience: Add Polly policies for retry and circuit breaking to handle transient network faults.
• Validate DTOs: Ensure all data mappings use the strongly-typed DTOs provided by the client library.
• Monitor Connections: Track socket usage and connection pool metrics to verify IHttpClientFactory is functioning correctly.
• Sync Clocks: Verify NTP synchronization on all production hosts to prevent HMAC timestamp failures.
• Review Logs: Enable detailed logging for HTTP requests to assist in debugging authentication or payload issues.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-Throughput IoT Ingestion	Typed Client with Batch Processing	Reduces RPC overhead and leverages connection pooling.	Lowers compute costs by optimizing request volume.
Offline Development	Mock API Server	Eliminates dependency on sandbox availability.	Reduces development time and infrastructure costs.
Legacy .NET Framework	Custom Wrapper	Native library targets .NET 8/10; legacy apps require adaptation.	Higher maintenance cost; consider migration path.
Rapid Prototyping	Typed Client with Mock	Accelerates iteration with immediate feedback loops.	Minimizes initial setup time.

Configuration Template

Use the following appsettings.json structure to configure the client. Adjust values based on your environment.

{
  "Fiix": {
    "BaseUrl": "https://your-subdomain.fiixcmms.com/api/v2/",
    "AppKey": "your-app-key",
    "AccessKey": "your-access-key",
    "SecretKey": "your-secret-key",
    "MockMode": false,
    "RetryPolicy": {
      "MaxRetries": 3,
      "BackoffSeconds": 2
    }
  }
}

Quick Start Guide

1. Install Package: Add the FiixCmms.Client package to your project via NuGet.
2. Configure Secrets: Set your Fiix credentials in your environment or secret manager.
3. Register Service: Call AddFiixGateway in Program.cs with your configuration.
4. Inject Client: Inject IFiixApiService into your services and begin using strongly-typed methods.
5. Run Tests: Start the Mock API server and execute integration tests without network dependencies.