---
# === IDENTITY ===
id: business/erp-integration/business-central-rapidstart/2026
canonical_question: "How does Business Central data migration via RapidStart Services work?"
aliases:
  - "Business Central RapidStart configuration packages for data migration"
  - "How to use RapidStart Services to set up and migrate data in Dynamics 365 Business Central"
  - "Business Central configuration packages Excel import export best practices"
  - "RapidStart Services data templates, validation, and Automation API workflow"
entity_type: erp_integration
domain: business > erp-integration > business-central-rapidstart
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Microsoft Dynamics 365 Business Central"
    vendor: "Microsoft"
    version: "2024 Wave 2 (v25) / 2025 Wave 1 (v26)"
    edition: "Essentials, Premium (SaaS and On-Premise)"
    deployment: "hybrid"
    api_surface: "Configuration Packages (RapidStart), Automation API (REST/OData)"

# === VERIFICATION ===
last_verified: 2026-03-03
confidence: 0.88
version: 1.0
first_published: 2026-03-03

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "2018 — Codeunit 8620 refactored for InStream-based import in BC v13+"
  next_review: 2026-08-30
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "RapidStart is for initial company setup only — do NOT use on production companies with active users"
  - "No hard record limit per package, but packages with >50K records cause significant performance degradation and session timeouts"
  - "Importing configuration packages blocks all other users from the company during processing"
  - "XML processor strips certain special characters — if removal creates duplicate table/field names, export fails"
  - "Cannot import into tables with posted entries (customer/vendor/item ledger entries)"
  - "BLOB fields default to base64 encoding — must match field encoding spec when editing in Excel"
  - "Schema must match between source and target — same table structure, primary keys, field IDs, and data types"
  - "Automation API import/apply operations are asynchronous — subsequent calls fail if previous task still running"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs real-time API integration (not data migration)"
    use_instead: "business/erp-integration/business-central-api-v2/2026"
  - condition: "User needs to migrate from Dynamics NAV to BC Online specifically"
    use_instead: "business/erp-integration/business-central-cloud-migration/2026"
  - condition: "User needs ongoing production data import/export (not initial setup)"
    use_instead: "business/erp-integration/business-central-xmlport/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "initial company setup (greenfield — new BC company)"
      - "data migration (moving from legacy ERP to BC)"
      - "automated tenant provisioning (multi-company setup via API)"
      - "configuration replication (copy setup between companies)"
  - key: data_volume
    question: "What's your data migration volume?"
    type: choice
    options:
      - "< 5,000 records (small company — direct import)"
      - "5,000-50,000 records (medium — chunked packages)"
      - "> 50,000 records (large — use XMLport instead)"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (importing data into Business Central)"
      - "outbound (exporting BC setup to reuse)"
      - "bidirectional (export setup, modify in Excel, re-import)"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/business-central-rapidstart/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-03)"

# === RELATED UNITS ===
related_kos:
  depends_on:
    - id: "business/erp-integration/business-central-api-v2/2026"
      label: "Business Central API v2.0 — required for Automation API package workflow"
  related_to:
    - id: "business/erp-integration/business-central-xmlport/2026"
      label: "Business Central XMLport — production-grade import/export alternative"
  solves:
    - id: "business/erp-integration/business-central-initial-setup/2026"
      label: "Business Central initial company setup and configuration"
  alternative_to:
    - id: "business/erp-integration/business-central-cloud-migration/2026"
      label: "Business Central cloud migration tools (for NAV/GP/SL migrations)"
  often_confused_with:
    - id: "business/erp-integration/business-central-api-v2/2026"
      label: "BC API v2.0 — for runtime integrations, NOT bulk data migration"

# === SOURCES ===
sources:
  - id: src1
    title: "Set Up Company Configuration Packages"
    author: Microsoft
    url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/set-up-standard-company-configuration-packages
    type: official_docs
    published: 2025-12-10
    reliability: authoritative
  - id: src2
    title: "Apply Company Configuration Packages"
    author: Microsoft
    url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/apply-company-configuration-packages
    type: official_docs
    published: 2025-05-07
    reliability: authoritative
  - id: src3
    title: "Introduction to Automation APIs"
    author: Microsoft
    url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/itpro-introduction-to-automation-apis
    type: official_docs
    published: 2025-12-05
    reliability: authoritative
  - id: src4
    title: "Use Excel to Import Data into Business Central"
    author: Microsoft
    url: https://learn.microsoft.com/en-us/dynamics365/business-central/across-import-data-configuration-packages
    type: official_docs
    published: 2025-06-13
    reliability: authoritative
  - id: src5
    title: "Definitive Guide to Configuration Packages in Business Central"
    author: Business Central Geek
    url: https://businesscentralgeek.com/definitive-guide-to-configuration-packages-in-business-central
    type: technical_blog
    published: 2024-08-15
    reliability: moderate_high
  - id: src6
    title: "Loading Configuration Packages from AL (Part 2)"
    author: Stefano Demiliani
    url: https://demiliani.com/2020/04/16/dynamics-365-business-central-loading-configuration-packages-from-al-part-2/
    type: technical_blog
    published: 2020-04-16
    reliability: moderate_high
  - id: src7
    title: "Getting RapidStart Errors in BC/NAV? Here's How to Fix Them"
    author: Dynamics 365 Community
    url: https://community.dynamics.com/blogs/post/?postid=312315b9-c3a3-45c9-91dc-f6447343ccf3
    type: community_resource
    published: 2023-11-02
    reliability: moderate
  - id: src8
    title: "RapidStart: Configuration Packages vs Configuration Worksheets in BC"
    author: Innovia Consulting
    url: https://www.innovia.com/blog/rapidstart-configuration-packages-vs-configuration-worksheets
    type: technical_blog
    published: 2024-03-20
    reliability: moderate_high
---

# Business Central Data Migration via RapidStart Services

## TL;DR

- **Bottom line**: RapidStart Services is Business Central's built-in tool for initial company setup and data migration — use configuration packages to export/import setup tables and master data via Excel or .rapidstart files, but ONLY for new company initialization, never on production companies.
- **Key limit**: No hard record cap, but packages over ~50K records cause severe performance issues; importing blocks all users from the company during processing. [src1]
- **Watch out for**: Importing into a production company with active users will lock everyone out and can corrupt data — RapidStart is for greenfield setup only. Use XMLport for production data operations. [src2]
- **Best for**: New company setup, configuration replication across tenants, master data migration (customers, vendors, items, GL accounts) during initial go-live. [src1]
- **Authentication**: Configuration Worksheet and Package pages are in-app (BC client). Automation API uses OAuth 2.0 Bearer token for programmatic package upload/import/apply. [src3]

## System Profile

Microsoft Dynamics 365 Business Central includes RapidStart Services as a built-in data migration and company configuration tool. It is available in both SaaS (Essentials and Premium editions) and on-premise deployments. RapidStart operates through configuration packages — bundles of table data that can be exported as `.rapidstart` compressed files or Excel workbooks, modified externally, and re-imported to populate a new company.

The tool consists of three core components: the **Configuration Worksheet** (organizes tables into areas and groups), **Configuration Packages** (the data containers exported/imported), and **Configuration Templates** (default field values applied to imported master data records). For automated multi-tenant provisioning, the **Automation API** (`microsoft/automation` namespace) provides REST endpoints to upload, import, and apply RapidStart packages programmatically. [src1, src3]

| Property | Value |
|---|---|
| **Vendor** | Microsoft |
| **System** | Dynamics 365 Business Central v25/v26 (2024-2026) |
| **Tool** | RapidStart Services (Configuration Packages) |
| **Automation API** | microsoft/automation/v2.0/configurationPackages |
| **Editions Covered** | Essentials, Premium (SaaS); all on-premise editions |
| **Deployment** | Cloud (SaaS) + On-Premise |
| **Docs URL** | [Set Up Company Configuration Packages](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/set-up-standard-company-configuration-packages) |
| **Status** | GA (General Availability) |

## API Surfaces & Capabilities

RapidStart is not a traditional API — it is a data migration framework with multiple access surfaces. [src1, src3, src6]

| Surface | Protocol | Best For | Max Records/Batch | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| Configuration Package (UI) | In-app (BC client) | Interactive setup, Excel-based migration | No hard limit (~50K practical) | N/A | No | Yes |
| .rapidstart File | XML compressed | Reusable package distribution between tenants | No hard limit | N/A | No | Yes |
| Excel Export/Import | XLSX via BC | Manual data entry/editing by consultants | No hard limit | N/A | No | Yes |
| Automation API (REST) | HTTPS/JSON + octet-stream | Automated tenant provisioning, CI/CD | Package-level (full .rapidstart file) | BC API rate limits apply | No (async) | Yes |
| AL Code (Codeunit 8620) | In-process | Extension-driven package application | Package-level | N/A | Sync or async | Yes |
| PowerShell (On-Prem) | Import-NAVConfigurationPackageFile | On-premise automation | Package-level | N/A | Sync | Yes |

## Rate Limits & Quotas

### Per-Operation Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Max package file size (Automation API upload) | 350 MB | Automation API PATCH | BC max request body size [src3] |
| Max entities per OData page | 20,000 | Automation API GET | For status polling |
| Concurrent OData requests | 5 processing per user | Automation API | Queued requests wait up to 8 min |
| Operation timeout | 8 minutes | Import/Apply operations | 504 at 10 minutes |
| Practical record limit per package | ~50,000 | All surfaces | Performance degrades severely above this [src5] |

### Session / Environment Limits

| Limit Type | Value | Window | Notes |
|---|---|---|---|
| Automation API rate limit | 6,000 requests per 5-min window | Rolling per user | Shared with all OData API calls |
| Speed limit (production) | 600 requests/minute | Per user | Applies to Automation API calls |
| Speed limit (sandbox) | 300 requests/minute | Per user | Lower in sandbox environments |
| Async task scheduler | 1 import/apply at a time | Per company | Subsequent calls fail until previous completes [src3] |

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| Interactive (BC Client) | Manual setup via Configuration Worksheet/Package pages | Session-based | Session | Most common for consultants [src1] |
| OAuth 2.0 Client Credentials (S2S) | Automated provisioning, CI/CD pipelines | Configurable (default ~1h) | Yes | Requires Entra ID app registration; must be in AdminAgents group for delegated admin [src3] |
| OAuth 2.0 Authorization Code | User-context Automation API calls | Access: 1h, Refresh: until revoked | Yes | For interactive automation tools |
| PowerShell (On-Prem) | Server-side administration | Windows auth session | N/A | Import-NAVConfigurationPackageFile cmdlet [src1] |

### Authentication Gotchas

- Automation API for delegated admins requires the Entra ID application to be added to the **AdminAgents** group — without this, the consent flow returns "Need pre-consent" error. [src3]
- S2S authentication does NOT support `getNewUsersFromOffice365` operations — these require SUPER permission set which cannot be assigned to application users. [src3]
- On-premise PowerShell requires `Set-NAVServerConfiguration -EnableApiServices $true` to enable API access. [src3]

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- **Initial setup only**: Configuration packages are NOT for production companies with active users — they block all user sessions during import. Use XMLport or API for production data operations. [src2]
- **Posted entries excluded**: You cannot import into tables containing posted entries (customer/vendor/item ledger entries, G/L entries). Journal lines can be imported but must be manually posted afterward. [src2]
- **Schema match required**: Source and target databases must have the same table structure, primary keys, field IDs, and data types. Different BC versions or customized schemas will cause import failures. [src1]
- **Special character limitation**: The XML processor that generates .rapidstart files only accepts certain special characters — if removing a character (e.g., `%`) creates duplicate table/field names, export fails with no clear error message. [src1]
- **Blank values overwrite**: When updating existing records, blank columns in the import file REPLACE existing values with blanks — there is no "skip if empty" option natively. [src7]
- **Async task serialization**: Automation API import and apply operations are asynchronous; calling import while a previous apply is still running returns HTTP 400. You must poll status before proceeding. [src3]
- **No partial import**: A package import is all-or-nothing at the table level — you cannot import selected rows from a table within a package. [src5]
- **Direct permissions required**: Import user must have Direct Insert and Direct Modify permissions on all target tables. Indirect permissions are insufficient. [src1]

## Integration Pattern Decision Tree

```
START — User needs to migrate data into Business Central
|-- What's the scenario?
|   |-- New company setup (greenfield)
|   |   |-- Data volume < 5,000 records?
|   |   |   |-- YES -> Configuration Package via Excel (simplest)
|   |   |   +-- NO  -> Data volume < 50,000 records?
|   |   |       |-- YES -> Configuration Package (.rapidstart file)
|   |   |       +-- NO  -> XMLport (RapidStart will be too slow)
|   |   +-- Need to replicate setup across multiple companies?
|   |       |-- YES -> Export .rapidstart, apply via Automation API
|   |       +-- NO  -> Single package import via BC client
|   |-- Multi-tenant provisioning (automated)
|   |   |-- Use Automation API workflow:
|   |       POST configurationPackages (create)
|   |       PATCH .../file/.../content (upload .rapidstart)
|   |       POST .../Microsoft.NAV.import (import — async)
|   |       Poll status until importStatus = "Completed"
|   |       POST .../Microsoft.NAV.apply (apply — async)
|   |       Poll status until applyStatus = "Completed"
|   |-- Production company (already live)
|   |   +-- DO NOT use RapidStart -> Use XMLport or API v2.0 instead
|   +-- Legacy ERP migration (NAV, GP, SL, QuickBooks)
|       |-- Supported migration tool available?
|       |   |-- YES -> Use cloud migration tools (not RapidStart)
|       |   +-- NO  -> Export to Excel/CSV, map fields, import via Config Package
|-- Which data?
|   |-- Setup tables (G/L Setup, No. Series, Posting Groups)
|   |   +-- Configuration Package (designed for this)
|   |-- Master data (Customers, Vendors, Items)
|   |   +-- Configuration Package + Configuration Templates
|   |-- Opening balances (G/L, AR, AP)
|   |   +-- Import journal lines via Config Package, then post manually
|   +-- Transaction history
|       +-- CANNOT import via RapidStart (posted entry tables excluded)
+-- Error tolerance?
    |-- Zero-loss -> Validate Package before Apply, export backup first
    +-- Best-effort -> Apply with Skip Table Triggers, fix errors post-import
```

## Quick Reference

### Configuration Package Workflow

| Step | Action | Page/Tool | Key Setting | Notes |
|---|---|---|---|---|
| 1 | Define package scope | Config. Worksheet or Config. Package Card | Table selection + field selection | Use "Get Tables" to auto-add by type [src1] |
| 2 | Add related tables | Config. Worksheet | "Get Related Tables" action | Conditional relations not auto-added [src1] |
| 3 | Select fields per table | Config. Package Fields | "Set Included" / "Clear Included" | Exclude calculated/system fields |
| 4 | Create templates | Configuration Templates | Default field values | Auto-applies defaults to imported records [src1] |
| 5 | Export to Excel | Config. Package Card | "Export to Excel" | One worksheet per table in package |
| 6 | Populate data in Excel | External (Excel) | Match column headers exactly | Do NOT add/remove/reorder columns |
| 7 | Import from Excel | Config. Package Card | "Import from Excel" | File must originate from BC export [src4] |
| 8 | Validate package | Config. Package Card | "Validate Package" action | Check for type mismatches, missing relations [src2] |
| 9 | Apply package | Config. Package Card | "Apply Package" action | Inserts/updates records into target tables [src2] |
| 10 | Post journals | General/Item/FA Journals | Manual posting | Opening balances require manual post [src2] |

### Automation API Workflow

| Step | HTTP Method | Endpoint | Payload | Status Field |
|---|---|---|---|---|
| 1. Create package | POST | /configurationPackages | `{"code":"PKG","packageName":"PKG"}` | — |
| 2. Upload file | PATCH | /configurationPackages({id})/file('{code}')/content | Binary .rapidstart (octet-stream) | — |
| 3. Import | POST | /configurationPackages({id})/Microsoft.NAV.import | None | importStatus |
| 4. Poll import | GET | /configurationPackages({id}) | None | "Completed" / "InProgress" / "Error" |
| 5. Apply | POST | /configurationPackages({id})/Microsoft.NAV.apply | None | applyStatus |
| 6. Poll apply | GET | /configurationPackages({id}) | None | "Completed" / "InProgress" / "Error" |

[src3]

## Step-by-Step Integration Guide

### 1. Create and configure a configuration package

Open the **Configuration Package** page in Business Central (search for "Configuration Packages"). Create a new package with a code (e.g., `MIGRATE01`) and add the tables you need to migrate. For master data, typical tables include: Customer (18), Vendor (23), Item (27), G/L Account (15), and related setup tables. [src1]

```
// In Business Central client:
// 1. Search for "Configuration Packages"
// 2. Click + New
// 3. Set Code = "MIGRATE01", Package Name = "Initial Data Migration"
// 4. In Lines section, add tables:
//    Table 18 (Customer), Table 23 (Vendor), Table 27 (Item),
//    Table 15 (G/L Account), Table 308 (No. Series)
// 5. For each table, click Fields to select/deselect columns
// 6. Set "Skip Table Triggers" = Yes for legacy data
```

**Verify**: In the Config. Package Card, check that "No. of Tables" shows your expected count and "No. of Records" shows 0 (for empty packages ready to receive data).

### 2. Export to Excel and populate data

Export the empty package structure to Excel, populate each worksheet with your migration data, then import back into Business Central. [src4]

```
// Export:
// 1. On Config. Package Card, click Actions > Package > "Export to Excel"
// 2. Save the .xlsx file
// 3. Open in Excel — one sheet per table
// 4. Fill in rows (one row per record)
//    IMPORTANT: Do NOT change column headers, order, or add new columns

// Import:
// 1. On Config. Package Card, click Actions > Package > "Import from Excel"
// 2. Select your populated .xlsx file
// 3. Check "No. of Package Records" to confirm import count
```

**Verify**: After import, the "No. of Records" column in the package lines should match your Excel row counts. "No. of Package Errors" should be 0.

### 3. Validate the package

Before applying, always validate to catch data type mismatches, missing foreign key references, and constraint violations. [src2]

```
// 1. On Config. Package Card, click Actions > Functions > "Validate Package"
// 2. Wait for validation to complete
// 3. Check "No. of Package Errors" column
// 4. If errors exist, drill down on the error count:
//    - Click the number in "No. of Package Errors"
//    - Config. Package Records page opens
//    - Click "Show Error" on each flagged record
// 5. Common fixes:
//    - Missing lookup values: enable "Create Missing Codes" in Fields page
//    - Type mismatches: fix in Excel and re-import
//    - Length violations: truncate text fields to match BC field length
```

**Verify**: "No. of Package Errors" = 0 for all tables before proceeding to Apply.

### 4. Apply the package

Apply inserts/updates records into the actual Business Central tables. This is the point of no return — always export a backup first. [src2]

```
// 1. BACKUP: Export current package to .rapidstart file first
//    (Actions > Package > "Export Package")
// 2. Click Actions > Functions > "Apply Package"
// 3. Confirm the apply action
// 4. Monitor progress — large packages may take several minutes
// 5. Check "No. of Package Errors" after apply completes
// 6. For any errors:
//    - Drill down to Config. Package Records
//    - Fix individual records inline
//    - Re-apply (only error records will be retried)
```

**Verify**: Navigate to the Customer List, Vendor List, and Item List to confirm records were created. Check "No. of Package Errors" = 0.

### 5. Automate via Automation API (for multi-tenant provisioning)

For automated provisioning of multiple companies, use the Automation API to upload and apply RapidStart packages programmatically. [src3]

```bash
# Step 1: Create the configuration package record
curl -X POST \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"SETUP01","packageName":"Standard Setup"}'

# Step 2: Upload the .rapidstart file
curl -X PATCH \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})/file('SETUP01')/content" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "If-Match: *" \
  --data-binary @setup01.rapidstart

# Step 3: Trigger import (async)
curl -X POST \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})/Microsoft.NAV.import" \
  -H "Authorization: Bearer $TOKEN"

# Step 4: Poll until importStatus = "Completed"
curl -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})" \
  -H "Authorization: Bearer $TOKEN"
# Response includes: "importStatus": "Completed" | "InProgress" | "Error"

# Step 5: Trigger apply (async — only after import completes)
curl -X POST \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})/Microsoft.NAV.apply" \
  -H "Authorization: Bearer $TOKEN"

# Step 6: Poll until applyStatus = "Completed"
curl -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})" \
  -H "Authorization: Bearer $TOKEN"
```

**Verify**: GET the package status — both `importStatus` and `applyStatus` should be `"Completed"`. Check `importError` and `applyError` fields for any error messages.

## Code Examples

### AL: Load and apply a RapidStart package from extension code

```al
// Input:  InStream containing a .rapidstart file
// Output: Package imported and applied to current company
// Uses Codeunit 8620 (Config. Package - Import) — BC v13+

procedure ImportAndApplyPackage(PackageStream: InStream)
var
    ConfigPackageImport: Codeunit "Config. Package - Import";
    ConfigPackage: Record "Config. Package";
    ConfigPackageMgt: Codeunit "Config. Package Management";
    TempBlob: Codeunit "Temp Blob";
    OutStream: OutStream;
begin
    // Load the .rapidstart stream into TempBlob
    TempBlob.CreateOutStream(OutStream);
    CopyStream(OutStream, PackageStream);

    // Import the package (parses and loads into staging tables)
    ConfigPackageImport.ImportRapidStartPackageStream(TempBlob);

    // Find the imported package and apply it
    if ConfigPackage.FindLast() then begin
        ConfigPackageMgt.ApplyPackage(ConfigPackage, ConfigPackage, true);
        Message('Package %1 applied successfully.', ConfigPackage.Code);
    end;
end;
```

[src6]

### AL: Import package from XML stream (v16+)

```al
// Input:  InStream containing decompressed XML from .rapidstart
// Output: Package loaded into Config. Package staging tables
// NOTE: .rapidstart is compressed — decompress before calling

procedure ImportPackageFromXML(XMLStream: InStream)
var
    ConfigXMLExchange: Codeunit "Config. XML Exchange";
begin
    // ImportPackageXMLFromStream requires decompressed XML
    // The .rapidstart file is a compressed archive — extract first
    ConfigXMLExchange.ImportPackageXMLFromStream(XMLStream);
end;
```

[src6]

### PowerShell: On-Premise automated package import

```powershell
# Input:  .rapidstart file path, BC server instance, company name
# Output: Package imported and applied to target company
# Requires: Business Central Administration Shell

# Import the BC management module
Import-Module "C:\Program Files\Microsoft Dynamics 365 Business Central\250\Service\NavAdminTool.ps1"

# Variables
$BCServerInstance = "BC250"
$CompanyName = "CRONUS International Ltd."
$PackageFile = "C:\Migration\setup-package.rapidstart"

# Ensure API services are enabled
Set-NAVServerConfiguration -ServerInstance $BCServerInstance `
    -KeyName ODataServicesEnabled -KeyValue true
Set-NAVServerConfiguration -ServerInstance $BCServerInstance `
    -KeyName ApiServicesEnabled -KeyValue true

# Import the configuration package
Import-NAVConfigurationPackageFile -ServerInstance $BCServerInstance `
    -CompanyName $CompanyName `
    -Path $PackageFile `
    -Force

Write-Host "Package imported successfully. Open BC client to validate and apply."
```

### cURL: Check Automation API package status

```bash
# Input:  Valid OAuth 2.0 Bearer token, company ID
# Output: JSON with package import/apply status

# List all configuration packages and their status
curl -s -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages" \
  -H "Authorization: Bearer $TOKEN" | jq '.value[] | {code, packageName, importStatus, applyStatus, numberOfTables, numberOfErrors}'

# Expected output:
# {
#   "code": "SETUP01",
#   "packageName": "Standard Setup",
#   "importStatus": "Completed",
#   "applyStatus": "Completed",
#   "numberOfTables": 15,
#   "numberOfErrors": 0
# }
```

[src3]

## Data Mapping

### Configuration Package Field Mapping

When importing data from external sources, the Configuration Package mapping feature allows you to transform field values between source and target schemas. Mapping is resolved in the following priority order. [src2]

| Priority | Mapping Type | Description | Example |
|---|---|---|---|
| 1 | Direct field mapping | Explicit mapping on the field itself | Source "CustNo" -> BC "No." |
| 2 | Related table mapping | Mapping via primary key in related table | Source "PayTerms30" -> BC "30 DAYS" (in Payment Terms table) |
| 3 | Configuration template | Default values applied when no mapping exists | Country/Region Code defaults to "US" |
| 4 | No mapping | Field imported as-is (must match BC format) | Names, addresses (direct copy) |

### Common Field Mapping Reference

| Source (Legacy/Excel) | Target (BC Table.Field) | Type | Transform | Gotcha |
|---|---|---|---|---|
| Customer Number | Customer."No." (18.1) | Code[20] | Direct | Max 20 chars — truncated silently if longer [src5] |
| Customer Name | Customer.Name (18.2) | Text[100] | Direct | Max 100 chars in BC |
| Payment Terms | Customer."Payment Terms Code" (18.15) | Code[10] | Lookup | Value MUST exist in Payment Terms table or enable "Create Missing Codes" [src7] |
| Currency | Customer."Currency Code" (18.26) | Code[10] | Lookup | Must exist in Currency table; blank = LCY |
| Tax ID / VAT Reg. | Customer."VAT Registration No." (18.86) | Text[20] | Direct | Format not validated during import — validate post-apply |
| Item Number | Item."No." (27.1) | Code[20] | Direct | No. Series may conflict — disable auto-numbering or pre-assign |
| Unit Price | Item."Unit Price" (27.18) | Decimal | Direct | Decimal separator must match BC regional settings |
| GL Account No | G/L Account."No." (15.1) | Code[20] | Direct | Chart of accounts structure must be set up first |

### Data Type Gotchas

- **Date formats**: Excel date cells must use a recognized date format. Text-formatted dates cause "is not a valid date" errors. Always use Excel's Date cell format, not text. [src7]
- **Decimal separators**: BC uses the locale's decimal separator. If your regional settings use comma (1.234,56) but your Excel data uses period (1,234.56), amounts will be corrupted. Match Excel regional settings to BC server locale. [src5]
- **Option fields (enums)**: Must import the integer value, not the display text. E.g., Customer."Blocked" expects 0/1/2, not ""/Ship/All. Check field metadata for option values. [src7]
- **Boolean fields**: Import as `true`/`false` or `1`/`0`, not "Yes"/"No". [src5]
- **BLOB/media fields**: Base64 encoded by default. If you edit in Excel, you must manually convert back to base64 before import. Encoding must match the field specification in the app. [src1]

## Error Handling & Failure Points

### Common Error Codes

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| "XX is not a valid option. Valid options are: XX" | Invalid option/enum value | Text value instead of integer, or value not in option set | Use integer value from field metadata; check table definition [src2] |
| "The field value is too long" | Field length exceeded | Source data exceeds BC field max length | Truncate data in Excel before import; check field length in table definition [src5] |
| Duplicate table/field name after special char removal | XML serialization conflict | .rapidstart export strips special characters creating name collisions | Rename conflicting fields before export [src1] |
| "The record in table X already exists" | Primary key conflict | Record with same primary key already exists in target | Use "Delete Table Records Before Processing" (caution!) or update existing [src5] |
| Validation sequence errors | Unexpected validation failures | Fields validated in wrong order during import | Uncheck "Validate Field" on problematic fields; re-validate post-import [src7] |
| "BLOB field encoding mismatch" | BLOB import failure | Edited BLOB field with wrong encoding | Ensure base64 encoding matches field spec [src1] |
| HTTP 400 on Automation API import/apply | Async task still running | Called import while previous task not completed | Poll status until previous operation shows "Completed" [src3] |
| "Need pre-consent" (Automation API) | Missing admin group membership | Entra ID app not in AdminAgents group | Add app to AdminAgents group in Partner Center [src3] |

### Failure Points in Production

- **Silent value truncation**: If "Validate Field" is unchecked and you import a text longer than the field allows, BC silently truncates to the field length — e.g., a 25-character name in a Code[20] field becomes 20 characters with no warning. Fix: `Always validate package before applying. Check "No. of Package Errors" after validation.` [src5]
- **Blank columns overwrite existing data**: When updating existing records via RapidStart, any blank cell in the import file REPLACES the existing value with blank/zero. There is no "update only non-empty fields" option. Fix: `Exclude blank columns from the package by deselecting them in the Fields page before import.` [src7]
- **Deleted Excel columns cause import errors**: If you delete columns from the exported Excel template, the import fails because the structure no longer matches the expected package schema. Fix: `Never delete columns from the Excel template — hide unwanted columns instead, or exclude fields in the Config. Package Fields page before export.` [src7]
- **Validation sequence causes cascading errors**: BC validates fields in a specific order during import. If a dependent field is validated before the field it depends on, you get false errors. Fix: `Adjust the "Processing Order" on the Config. Package Fields page to match dependency order, or disable validation on dependent fields.` [src7]
- **Async API operations not complete before next step**: Calling the apply endpoint before import finishes returns HTTP 400. The task scheduler processes one operation at a time per company. Fix: `Implement polling loop: GET the package resource, check importStatus/applyStatus, wait 2-5 seconds between polls.` [src3]
- **Number series conflicts**: If the target company already has Number Series configured, importing master data with pre-assigned numbers that overlap the series range causes conflicts. Fix: `Either disable automatic numbering or ensure imported numbers don't overlap existing series ranges.` [src8]

## Anti-Patterns

### Wrong: Using RapidStart for ongoing production data loads

```
// BAD — RapidStart locks out all users during import
// Using configuration packages for weekly data loads in a live production company

1. Export configuration package from staging DB
2. Import into production BC company (Friday night)
3. Users complain they can't log in Saturday morning
4. Apply takes 6 hours for 100K records
5. Errors discovered Monday — no easy rollback
```

### Correct: Use XMLport or API v2.0 for production data operations

```
// GOOD — Use the right tool for production data
// RapidStart = initial setup only

Option A: XMLport (for bulk, scheduled)
- Design custom XMLport for your specific data structure
- Run during off-hours via Job Queue
- Does not block other users

Option B: API v2.0 (for real-time/near-real-time)
- POST/PATCH individual records via REST API
- Rate limited but non-blocking
- Full error handling per record
```

### Wrong: Importing the entire Excel template including unused columns

```
// BAD — Importing all columns including blanks overwrites existing data
1. Export package to Excel (50 columns per table)
2. Only fill in 10 required columns
3. Leave 40 columns blank
4. Import back into BC
5. RESULT: 40 fields on every record are now blank/zero
```

### Correct: Select only needed fields before export

```
// GOOD — Minimize field selection before export
1. Open Config. Package Fields page for each table
2. Click "Clear Included" to deselect all fields
3. Select ONLY the fields you will populate
4. THEN export to Excel
5. Import — only selected fields are affected
```

[src5, src7]

### Wrong: Skipping validation and applying directly

```
// BAD — Apply without validate
1. Import Excel data into package
2. Immediately click "Apply Package"
3. 500 records fail with cryptic errors
4. Some records partially applied, some not
5. Hours spent fixing data inconsistencies
```

### Correct: Always validate before applying

```
// GOOD — Validate first, fix errors, then apply
1. Import Excel data into package
2. Click "Validate Package"
3. Review "No. of Package Errors" for each table
4. Drill down into errors, fix in Excel or inline
5. Re-import and re-validate until 0 errors
6. THEN click "Apply Package"
7. Export backup .rapidstart before apply (safety net)
```

[src2, src5]

## Common Pitfalls

- **Applying packages to production companies**: RapidStart blocks all user sessions during import/apply. Even "small" imports of 1,000 records can take minutes, locking users out. Fix: `Only use RapidStart during initial company setup. For production, use XMLport or API v2.0.` [src2]
- **Not exporting backup before apply**: Apply is destructive — there is no built-in undo. If data is corrupted or wrong, you must restore from backup. Fix: `Always export the current package as .rapidstart backup before applying. Test in sandbox first.` [src5]
- **Ignoring the "Create Missing Codes" option**: Importing customers with payment terms that don't exist in BC causes validation errors. Fix: `Enable "Create Missing Codes" in the Config. Package Fields page for lookup fields. Or pre-populate lookup tables first.` [src7]
- **Not handling Number Series properly**: If the target company auto-generates numbers via No. Series, imported records with pre-assigned numbers may conflict. Fix: `Import No. Series table first with appropriate starting numbers. Or clear the No. Series assignment before importing master data, then reassign after.` [src8]
- **Treating sandbox API limits as production**: Sandbox environments have lower speed limits (300 req/min vs 600) and may not reflect production performance for Automation API workflows. Fix: `Always test final migration run in a production-equivalent environment. Budget 50-100% more time for sandbox runs.` [src3]
- **Forgetting to post journal entries**: RapidStart imports journal lines but does NOT post them. Opening balances remain unposted until manually processed. Fix: `After applying the package, navigate to each journal (General, Item, FA) and post the imported entries.` [src2]

## Diagnostic Commands

```bash
# Check Automation API package status (all packages)
curl -s -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.value[] | {code, packageName, importStatus, applyStatus, numberOfTables, numberOfErrors}'

# Check specific package import/apply status
curl -s -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({pkgId})" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{importStatus, applyStatus, importError, applyError}'

# Test authentication (get companies list)
curl -s -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.value[] | {id, name, displayName}'

# Check available configuration packages in a company
# (use BC client: search for "Configuration Packages")
# Or via Automation API:
curl -s -X GET \
  "https://api.businesscentral.dynamics.com/v2.0/{env}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages?\$select=code,packageName,importStatus,applyStatus,numberOfTables,numberOfRecords,numberOfErrors" \
  -H "Authorization: Bearer $TOKEN"

# PowerShell: Check BC server API settings (on-premise)
# Get-NAVServerConfiguration -ServerInstance BC250 | Where-Object { $_.Key -like "*Api*" -or $_.Key -like "*OData*" }
```

## Version History & Compatibility

| BC Version | Release Date | Status | Changes to RapidStart | Notes |
|---|---|---|---|---|
| v26 (2025 Wave 1) | 2025-04 | Current | Automation API v2.0 improvements; scheduled job tracking | Latest recommended version |
| v25 (2024 Wave 2) | 2024-10 | Supported | Security groups replace user groups in automation | AdminAgents group required for delegated admin |
| v24 (2024 Wave 1) | 2024-04 | Supported | Performance improvements for large packages | — |
| v22 (2023 Wave 1) | 2023-04 | EOL 2025-10 | — | Minimum for Automation API v2.0 |
| v16 (2020 Wave 1) | 2020-04 | EOL | Config. XML Exchange codeunit added (ImportPackageXMLFromStream) | Key for AL-based package loading [src6] |
| v13 (2018) | 2018-10 | EOL | Codeunit 8620 refactored for InStream-based import | Breaking change for existing AL code [src6] |

### Deprecation Policy

Microsoft follows a minimum 12-month lifecycle for each Business Central major version. RapidStart Services itself is a core platform feature with no announced deprecation, but individual capabilities (e.g., SOAP endpoints) are deprecated with 12+ months notice. The Automation API namespace evolves with each major release — always use v2.0. [src1, src3]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Setting up a new company for the first time | Company is already in production with active users | XMLport or API v2.0 |
| Migrating master data (customers, vendors, items) during go-live | Migrating transaction history or posted entries | Journal imports for opening balances; skip historical transactions |
| Replicating setup configuration across multiple companies | Ongoing scheduled data synchronization | API v2.0 webhooks + scheduled jobs |
| Automated tenant provisioning via Automation API | Real-time record-level integration | API v2.0 OData endpoints |
| Legacy ERP migration where no direct migration tool exists | Migrating from supported products (NAV, GP, SL, QuickBooks) | Built-in cloud migration tools |
| Data volume under ~50,000 records per table | Data volume over 50,000 records per table | Custom XMLport (designed for high volume) |

## Important Caveats

- RapidStart Services blocks ALL other users from the company during package import and apply operations. Plan migration windows carefully and communicate downtime to users. [src2]
- Configuration packages must match the target database schema exactly — different BC versions, different extensions, or different field IDs will cause silent failures or data corruption. Always test in a sandbox environment with the same extension set as production. [src1]
- The Automation API import and apply operations are asynchronous. Some operations trigger background tasks via the task scheduler — calling the next step too early returns HTTP 400 Bad Request. Always poll status before proceeding. [src3]
- Blank cells in imported Excel files overwrite existing field values with blanks/zeros. This is especially dangerous when updating existing records — always deselect fields you don't intend to update. [src7]
- RapidStart does NOT validate business logic during import if "Skip Table Triggers" is enabled. Data that violates business rules (e.g., negative inventory, invalid posting groups) will be imported without error but cause failures during normal business operations. [src5]
- Opening balances imported via journal lines are NOT automatically posted. You must manually navigate to each journal type and post after the package is applied. [src2]

## Related Units

- [Business Central API v2.0 Capabilities and Limits](/business/erp-integration/business-central-api-v2/2026) — runtime OData API for production integrations
- [Business Central Cloud Migration Tools](/business/erp-integration/business-central-cloud-migration/2026) — for migrating from NAV, GP, SL, QuickBooks
- [Business Central XMLport](/business/erp-integration/business-central-xmlport/2026) — production-grade bulk import/export alternative