Getting Started with InstallHub

InstallHub is the enterprise package management system built into the BizFirstAi platform. It lets you export data from any source into versioned packages, import those packages into any target system with automatic conflict resolution, and publish packages to a governed marketplace for your organisation.

Platform requirement: InstallHub is part of BizFirstAi. You will need a BizFirstAi account to use the SDK and hosted runtime. Sign up free here.

Installation

Add the InstallHub NuGet package to your .NET project:

dotnet add package BizFirstAi.InstallHub

Basic Usage

The following example creates an InstallHub client, defines an export package, and publishes the first version.

using BizFirstAi.InstallHub;
using BizFirstAi.InstallHub.Export;

// 1. Create the InstallHub client
var client = new InstallHubClient(new InstallHubOptions
{
    ApiKey    = Environment.GetEnvironmentVariable("BIZFIRSTAI_API_KEY"),
    Workspace = "my-workspace"
});

// 2. Create an export package
var package = await client.Packages.CreateAsync(new CreateExportPackageRequest
{
    Name        = "customer-config",
    Description = "Customer configuration and onboarding data",
    SourceType  = ExportSourceType.Database,
    TenantId    = "tenant-001"
});

// 3. Configure the export items
await client.Packages.AddItemAsync(package.Id, new ExportPackageItemRequest
{
    EntityName  = "CustomerSettings",
    FieldMap    = new[] { "Id", "Name", "Config", "CreatedAt" },
    IncludeAll  = false
});

// 4. Publish version 1.0.0
var version = await client.Packages.PublishVersionAsync(package.Id, new PublishVersionRequest
{
    Version      = "1.0.0",
    ReleaseNotes = "Initial release of customer configuration package."
});

Console.WriteLine($"Package published: {version.PackageId} v{version.Version}");
Console.WriteLine($"Download URL expires: {version.SignedUrlExpiresAt}");

Export Packages

Export Wizard (4 Steps)

The Creator App guides operators through four steps to create an export package:

Step 1 — Source Selection: Choose the source type (Database, File, or API) and provide connection details.
Step 2 — Field Mapping: Select entities and map fields to include in the package. Unmapped fields are excluded from the ZIP archive.
Step 3 — Schedule: Configure a one-time or recurring export schedule. Recurring exports produce new versions automatically.
Step 4 — Review & Submit: Review the full configuration before the export runs. The manifest and field map are displayed for confirmation.

Source Types

InstallHub supports three source types for export:

Database: Relational database tables via a connection string. Supports filtering, pagination, and relationship traversal.
File: CSV, JSON, and XML file sources. Files are read, validated, and packaged with schema inference.
API: Any HTTP REST API endpoint. Supports authentication headers, pagination, and response field extraction.

Semantic Versioning

Every package in InstallHub is versioned using semantic versioning. Versions move through a defined lifecycle:

Draft: Under construction. Not visible to importers. Changes are freely allowed.
Released: Published and available for import or marketplace publishing. No further edits to the version content.
Archived: Retired. Preserved for audit and rollback but hidden from active discovery.

Import Packages

Import Wizard (4 Steps)

The import wizard walks operators through validation, mapping, and conflict resolution before any data is modified:

Step 1 — File Upload: Upload the package ZIP. ZipValidationService runs manifest validation, SHA256 checksum verification, and structure validation immediately.
Step 2 — Mapping: Review and adjust the field mapping between the package schema and the target system's schema. Override mappings as needed.
Step 3 — Conflict Resolution: Choose a conflict strategy for each entity type. Review detected conflicts before import begins.
Step 4 — Review & Start: Review the full import plan — dependency order, conflict strategy, estimated records. Confirm to begin.

Import Handlers

InstallHub ships 20 specialized import handlers, each responsible for a specific entity type. Handlers are selected automatically based on the package manifest:

FormHandler, TableHandler, ConfigHandler, TemplateHandler, ScriptHandler
DataHandler, ViewHandler, StoredProcHandler, TriggerHandler, IndexHandler
ConstraintHandler, RoleHandler, UserHandler, SecurityHandler, AuditHandler
MetadataHandler, SchemaHandler, RelationshipHandler, CustomHandler, BaseImportHandler

Import Status States

Every import moves through the following states:

Pending: Import queued, awaiting resource availability.
Validating: ZipValidationService and DependencyResolutionService running.
Configuring: Conflict strategies applied, import plan being built.
Reviewing: Awaiting operator confirmation in the wizard.
Importing: Handlers running, data being written.
Completed: All handlers completed successfully.
Failed: One or more handlers encountered an unrecoverable error.
RolledBack: Import failed and BackupRestoreService has restored the pre-import snapshot.

Conflict Resolution

When an imported record conflicts with an existing record in the target system, InstallHub applies one of three strategies. The strategy can be set globally or per entity type.

Strategy	Behaviour	Best for
Merge	Recursive intelligent merge of the incoming record into the existing record. Fields present in the incoming record overwrite the corresponding existing field. Fields absent in the incoming record are preserved as-is.	Partial updates where existing data should be preserved for fields not included in the package.
Overwrite	The existing record is replaced entirely by the incoming record. No fields from the existing record are retained.	Full replacements where the package is the authoritative source of truth for the entity.
Skip	The existing record is kept unchanged. The incoming record is discarded. No error is raised — the conflict is logged and processing continues.	Additive imports where you only want to create new records, never modify existing ones.

Rollback

BackupRestoreService creates a pre-import database snapshot automatically before every import. If the import fails, InstallHub rolls back to the snapshot atomically — the system is restored to its exact pre-import state with no manual steps.

Backups are GZip-compressed (3–5x reduction in storage size).
Every backup carries a SHA256 integrity hash — restoration refuses if the hash does not match.
Retention is configurable from 7 to 730 days per tenant.

Marketplace — Publishing

Published packages are submitted from the Creator App and go through an admin approval workflow before appearing in the marketplace:

Select a Released version from the package management screen and click Publish to Marketplace.
An admin receives a review notification in the Admin App.
The admin approves or rejects the submission with optional feedback.
Approved packages appear immediately in the marketplace discovery feed.

Marketplace — Discovery

The Marketplace App provides full-text search and filter capabilities for discovering packages:

Search by title, description, or tag.
Filter by category, publisher, or minimum star rating.
Sort by popularity (download count), rating, or recency.
Trending packages are surfaced automatically by download count.
Downloads are served via signed Cloudflare R2 URLs that expire after 60 minutes.

API Reference

InstallHub exposes 50+ API endpoints across three applications. Core endpoint groups:

Export API: Create packages, manage versions, trigger exports, retrieve assets.
Import API: Upload packages, start imports, monitor status, trigger rollbacks.
Marketplace API: Submit packages for approval, search and filter, download, rate and review.

OpenAPI spec: The full OpenAPI specification is available in your BizFirstAi workspace under Settings → API → InstallHub. Authentication uses your workspace API key via the Authorization: Bearer header.