feat: switch from Admin Center database export to BC API v2.0 data extraction
The Admin Center export API requires an Azure Storage SAS URI which requires an Azure Subscription - defeating the purpose of an independent backup. Instead, use BC API v2.0 to extract critical business data (customers, vendors, items, GL entries, invoices, etc.) as JSON files. - bc-export.ps1: rewritten to use BC API v2.0 endpoints, extracts 23 entity types per company with OData pagination support - bc-backup.sh: handles JSON export directory, creates tar.gz archive before encrypting and uploading to S3 - bc-backup.conf.template: removed Azure Storage SAS config, added optional BC_COMPANY_NAME filter - decrypt-backup.sh: updated for tar.gz.gpg format, shows extracted entity files and metadata after decryption Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
399
bc-export.ps1
399
bc-export.ps1
@@ -1,7 +1,7 @@
|
||||
#!/usr/bin/env pwsh
|
||||
#
|
||||
# Business Central Database Export via Admin Center API
|
||||
# Authenticates to Azure AD and exports BC database as BACPAC
|
||||
# Business Central Data Export via BC API v2.0
|
||||
# Authenticates to Azure AD and extracts critical business data as JSON
|
||||
#
|
||||
|
||||
param(
|
||||
@@ -14,19 +14,37 @@ $tenantId = $env:AZURE_TENANT_ID
|
||||
$clientId = $env:AZURE_CLIENT_ID
|
||||
$clientSecret = $env:AZURE_CLIENT_SECRET
|
||||
$environmentName = $env:BC_ENVIRONMENT_NAME
|
||||
$apiVersion = $env:BC_API_VERSION
|
||||
$storageAccountSasUri = $env:AZURE_STORAGE_SAS_URI
|
||||
$storageContainer = $env:AZURE_STORAGE_CONTAINER
|
||||
$bcCompanyName = $env:BC_COMPANY_NAME # optional: filter to specific company
|
||||
|
||||
if (-not $apiVersion) {
|
||||
$apiVersion = "v2.21"
|
||||
}
|
||||
$baseUrl = "https://api.businesscentral.dynamics.com/v2.0/$tenantId/$environmentName/api/v2.0"
|
||||
|
||||
if (-not $storageContainer) {
|
||||
$storageContainer = "bc-exports"
|
||||
}
|
||||
|
||||
$baseUrl = "https://api.businesscentral.dynamics.com/admin/$apiVersion"
|
||||
# Entities to extract - critical business data
|
||||
$entities = @(
|
||||
"accounts",
|
||||
"customers",
|
||||
"vendors",
|
||||
"items",
|
||||
"salesInvoices",
|
||||
"salesInvoiceLines",
|
||||
"salesOrders",
|
||||
"salesOrderLines",
|
||||
"salesCreditMemos",
|
||||
"salesCreditMemoLines",
|
||||
"purchaseInvoices",
|
||||
"purchaseInvoiceLines",
|
||||
"purchaseOrders",
|
||||
"purchaseOrderLines",
|
||||
"generalLedgerEntries",
|
||||
"bankAccounts",
|
||||
"employees",
|
||||
"dimensions",
|
||||
"dimensionValues",
|
||||
"currencies",
|
||||
"paymentTerms",
|
||||
"paymentMethods",
|
||||
"journals",
|
||||
"countriesRegions"
|
||||
)
|
||||
|
||||
function Write-Log {
|
||||
param([string]$Message, [string]$Level = "INFO")
|
||||
@@ -63,283 +81,178 @@ function Get-AzureADToken {
|
||||
}
|
||||
}
|
||||
|
||||
function Get-ExportMetrics {
|
||||
function Get-BCData {
|
||||
param(
|
||||
[string]$Token,
|
||||
[string]$EnvironmentName
|
||||
[string]$Url
|
||||
)
|
||||
|
||||
$headers = @{
|
||||
"Authorization" = "Bearer $Token"
|
||||
"Accept" = "application/json"
|
||||
}
|
||||
|
||||
$metricsUrl = "$baseUrl/exports/applications/BusinessCentral/environments/$EnvironmentName/metrics"
|
||||
$allRecords = @()
|
||||
|
||||
try {
|
||||
$response = Invoke-RestMethod -Uri $metricsUrl -Method Get -Headers $headers
|
||||
Write-Log "Export metrics - Used this month: $($response.exportsPerMonth), Remaining: $($response.exportsRemainingThisMonth)"
|
||||
return $response
|
||||
}
|
||||
catch {
|
||||
Write-Log "Failed to get export metrics: $_" "WARN"
|
||||
return $null
|
||||
$currentUrl = $Url
|
||||
while ($currentUrl) {
|
||||
try {
|
||||
$response = Invoke-RestMethod -Uri $currentUrl -Method Get -Headers $headers
|
||||
}
|
||||
catch {
|
||||
Write-Log "API request failed for $currentUrl : $_" "ERROR"
|
||||
throw
|
||||
}
|
||||
|
||||
if ($response.value) {
|
||||
$allRecords += $response.value
|
||||
}
|
||||
|
||||
# Handle OData pagination
|
||||
$currentUrl = $response.'@odata.nextLink'
|
||||
}
|
||||
|
||||
return $allRecords
|
||||
}
|
||||
|
||||
function Start-DatabaseExport {
|
||||
function Get-Companies {
|
||||
param([string]$Token)
|
||||
|
||||
Write-Log "Fetching companies..."
|
||||
$companiesUrl = "$baseUrl/companies"
|
||||
$companies = Get-BCData -Token $Token -Url $companiesUrl
|
||||
Write-Log "Found $($companies.Count) company/companies"
|
||||
return $companies
|
||||
}
|
||||
|
||||
function Export-EntityData {
|
||||
param(
|
||||
[string]$Token,
|
||||
[string]$EnvironmentName,
|
||||
[string]$StorageSasUri,
|
||||
[string]$Container,
|
||||
[string]$BlobName
|
||||
[string]$CompanyId,
|
||||
[string]$CompanyName,
|
||||
[string]$EntityName,
|
||||
[string]$OutputDir
|
||||
)
|
||||
|
||||
Write-Log "Initiating database export for environment: $EnvironmentName"
|
||||
$entityUrl = "$baseUrl/companies($CompanyId)/$EntityName"
|
||||
|
||||
$headers = @{
|
||||
"Authorization" = "Bearer $Token"
|
||||
"Content-Type" = "application/json"
|
||||
}
|
||||
|
||||
$exportUrl = "$baseUrl/exports/applications/BusinessCentral/environments/$EnvironmentName"
|
||||
|
||||
$body = @{
|
||||
storageAccountSasUri = $StorageSasUri
|
||||
container = $Container
|
||||
blob = $BlobName
|
||||
} | ConvertTo-Json
|
||||
Write-Log " Exporting $EntityName..."
|
||||
|
||||
try {
|
||||
$response = Invoke-RestMethod -Uri $exportUrl -Method Post -Headers $headers -Body $body
|
||||
Write-Log "Database export initiated successfully"
|
||||
return $response
|
||||
$data = Get-BCData -Token $Token -Url $entityUrl
|
||||
$count = 0
|
||||
if ($data) { $count = $data.Count }
|
||||
|
||||
$outputFile = Join-Path $OutputDir "$EntityName.json"
|
||||
$data | ConvertTo-Json -Depth 10 | Out-File -FilePath $outputFile -Encoding utf8
|
||||
|
||||
Write-Log " $EntityName : $count records"
|
||||
return $count
|
||||
}
|
||||
catch {
|
||||
Write-Log "Failed to initiate export: $_" "ERROR"
|
||||
Write-Log "Response: $($_.ErrorDetails.Message)" "ERROR"
|
||||
throw
|
||||
}
|
||||
}
|
||||
|
||||
function Get-ExportHistory {
|
||||
param(
|
||||
[string]$Token,
|
||||
[datetime]$StartTime,
|
||||
[datetime]$EndTime
|
||||
)
|
||||
|
||||
$headers = @{
|
||||
"Authorization" = "Bearer $Token"
|
||||
"Content-Type" = "application/json"
|
||||
}
|
||||
|
||||
$startStr = $StartTime.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
|
||||
$endStr = $EndTime.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
|
||||
|
||||
$historyUrl = "$baseUrl/exports/history?start=$startStr&end=$endStr"
|
||||
|
||||
try {
|
||||
$response = Invoke-RestMethod -Uri $historyUrl -Method Post -Headers $headers
|
||||
return $response
|
||||
}
|
||||
catch {
|
||||
Write-Log "Failed to get export history: $_" "ERROR"
|
||||
return $null
|
||||
}
|
||||
}
|
||||
|
||||
function Wait-ForExport {
|
||||
param(
|
||||
[string]$Token,
|
||||
[string]$EnvironmentName,
|
||||
[string]$BlobName,
|
||||
[datetime]$ExportStartTime,
|
||||
[int]$MaxWaitMinutes = 120
|
||||
)
|
||||
|
||||
Write-Log "Waiting for export to complete (max $MaxWaitMinutes minutes)..."
|
||||
|
||||
$startTime = Get-Date
|
||||
$pollInterval = 30 # seconds
|
||||
|
||||
while ($true) {
|
||||
$elapsed = ((Get-Date) - $startTime).TotalMinutes
|
||||
|
||||
if ($elapsed -gt $MaxWaitMinutes) {
|
||||
Write-Log "Export timeout exceeded ($MaxWaitMinutes minutes)" "ERROR"
|
||||
return $null
|
||||
}
|
||||
|
||||
$history = Get-ExportHistory -Token $Token -StartTime $ExportStartTime -EndTime (Get-Date)
|
||||
|
||||
if ($null -eq $history -or $null -eq $history.value -or $history.value.Count -eq 0) {
|
||||
Write-Log "No export history found yet, waiting... (Elapsed: $([math]::Round($elapsed, 1)) min)"
|
||||
Start-Sleep -Seconds $pollInterval
|
||||
continue
|
||||
}
|
||||
|
||||
# Find our export by environment name and blob name
|
||||
$ourExport = $history.value | Where-Object {
|
||||
$_.environmentName -eq $EnvironmentName -and $_.blob -eq $BlobName
|
||||
} | Sort-Object -Property startedOn -Descending | Select-Object -First 1
|
||||
|
||||
if (-not $ourExport) {
|
||||
# Fallback: just find the most recent export for this environment
|
||||
$ourExport = $history.value | Where-Object {
|
||||
$_.environmentName -eq $EnvironmentName
|
||||
} | Sort-Object -Property startedOn -Descending | Select-Object -First 1
|
||||
}
|
||||
|
||||
if (-not $ourExport) {
|
||||
Write-Log "Export not found in history yet, waiting... (Elapsed: $([math]::Round($elapsed, 1)) min)"
|
||||
Start-Sleep -Seconds $pollInterval
|
||||
continue
|
||||
}
|
||||
|
||||
$exportStatus = $ourExport.status
|
||||
Write-Log "Export status: $exportStatus (Elapsed: $([math]::Round($elapsed, 1)) min)"
|
||||
|
||||
switch ($exportStatus.ToLower()) {
|
||||
"completed" {
|
||||
Write-Log "Export completed successfully"
|
||||
return $ourExport
|
||||
}
|
||||
"complete" {
|
||||
Write-Log "Export completed successfully"
|
||||
return $ourExport
|
||||
}
|
||||
"failed" {
|
||||
Write-Log "Export failed" "ERROR"
|
||||
if ($ourExport.failureReason) {
|
||||
Write-Log "Failure reason: $($ourExport.failureReason)" "ERROR"
|
||||
}
|
||||
return $null
|
||||
}
|
||||
"inprogress" {
|
||||
Write-Log "Export in progress..."
|
||||
}
|
||||
"queued" {
|
||||
Write-Log "Export queued..."
|
||||
}
|
||||
default {
|
||||
Write-Log "Unknown status: $exportStatus" "WARN"
|
||||
}
|
||||
}
|
||||
|
||||
Start-Sleep -Seconds $pollInterval
|
||||
}
|
||||
}
|
||||
|
||||
function Download-FromAzureStorage {
|
||||
param(
|
||||
[string]$StorageSasUri,
|
||||
[string]$Container,
|
||||
[string]$BlobName,
|
||||
[string]$OutputPath
|
||||
)
|
||||
|
||||
# Parse the SAS URI to construct the blob download URL
|
||||
# SAS URI format: https://account.blob.core.windows.net?sv=...&sig=...
|
||||
$uri = [System.Uri]$StorageSasUri
|
||||
$baseStorageUrl = "$($uri.Scheme)://$($uri.Host)"
|
||||
$sasToken = $uri.Query
|
||||
|
||||
$downloadUrl = "$baseStorageUrl/$Container/$BlobName$sasToken"
|
||||
|
||||
Write-Log "Downloading BACPAC from Azure Storage..."
|
||||
Write-Log "Container: $Container"
|
||||
Write-Log "Blob: $BlobName"
|
||||
Write-Log "Saving to: $OutputPath"
|
||||
|
||||
try {
|
||||
$ProgressPreference = 'SilentlyContinue'
|
||||
Invoke-WebRequest -Uri $downloadUrl -OutFile $OutputPath -UseBasicParsing
|
||||
|
||||
if (Test-Path $OutputPath) {
|
||||
$fileSize = (Get-Item $OutputPath).Length
|
||||
$fileSizeMB = [math]::Round($fileSize / 1MB, 2)
|
||||
Write-Log "Download completed successfully ($fileSizeMB MB)"
|
||||
return $true
|
||||
}
|
||||
else {
|
||||
Write-Log "Download failed - file not found" "ERROR"
|
||||
return $false
|
||||
}
|
||||
}
|
||||
catch {
|
||||
Write-Log "Download failed: $_" "ERROR"
|
||||
return $false
|
||||
Write-Log " Failed to export ${EntityName}: $_" "WARN"
|
||||
# Write empty array so downstream knows it was attempted
|
||||
$outputFile = Join-Path $OutputDir "$EntityName.json"
|
||||
"[]" | Out-File -FilePath $outputFile -Encoding utf8
|
||||
return 0
|
||||
}
|
||||
}
|
||||
|
||||
# Main execution
|
||||
try {
|
||||
Write-Log "========================================="
|
||||
Write-Log "BC Database Export Script"
|
||||
Write-Log "BC Data Export Script (API v2.0)"
|
||||
Write-Log "========================================="
|
||||
Write-Log "Environment: $environmentName"
|
||||
Write-Log "API Version: $apiVersion"
|
||||
Write-Log "Output Path: $OutputPath"
|
||||
Write-Log "Entities to extract: $($entities.Count)"
|
||||
|
||||
# Validate required parameters
|
||||
if (-not $storageAccountSasUri) {
|
||||
Write-Log "AZURE_STORAGE_SAS_URI is required for database export" "ERROR"
|
||||
exit 1
|
||||
# Create output directory
|
||||
$exportDir = $OutputPath
|
||||
if (-not (Test-Path $exportDir)) {
|
||||
New-Item -ItemType Directory -Path $exportDir -Force | Out-Null
|
||||
}
|
||||
|
||||
# Step 1: Get Azure AD token
|
||||
$token = Get-AzureADToken -TenantId $tenantId -ClientId $clientId -ClientSecret $clientSecret
|
||||
|
||||
# Step 2: Check export metrics
|
||||
Write-Log "Checking export metrics..."
|
||||
$metrics = Get-ExportMetrics -Token $token -EnvironmentName $environmentName
|
||||
# Step 2: Get companies
|
||||
$companies = Get-Companies -Token $token
|
||||
|
||||
if ($metrics -and $metrics.exportsRemainingThisMonth -le 0) {
|
||||
Write-Log "No exports remaining this month! (Limit reached)" "ERROR"
|
||||
if ($companies.Count -eq 0) {
|
||||
Write-Log "No companies found in environment $environmentName" "ERROR"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Step 3: Start the export
|
||||
$blobName = "bc_export_${environmentName}_$(Get-Date -Format 'yyyyMMdd_HHmmss').bacpac"
|
||||
$exportStartTime = (Get-Date).AddMinutes(-1) # slight buffer for clock differences
|
||||
# Save companies list
|
||||
$companies | ConvertTo-Json -Depth 10 | Out-File -FilePath (Join-Path $exportDir "companies.json") -Encoding utf8
|
||||
|
||||
Write-Log "Starting export to Azure Storage (container: $storageContainer, blob: $blobName)..."
|
||||
|
||||
$exportResult = Start-DatabaseExport `
|
||||
-Token $token `
|
||||
-EnvironmentName $environmentName `
|
||||
-StorageSasUri $storageAccountSasUri `
|
||||
-Container $storageContainer `
|
||||
-BlobName $blobName
|
||||
|
||||
# Step 4: Wait for export to complete
|
||||
$completedExport = Wait-ForExport `
|
||||
-Token $token `
|
||||
-EnvironmentName $environmentName `
|
||||
-BlobName $blobName `
|
||||
-ExportStartTime $exportStartTime `
|
||||
-MaxWaitMinutes 120
|
||||
|
||||
if (-not $completedExport) {
|
||||
Write-Log "Export did not complete successfully" "ERROR"
|
||||
exit 1
|
||||
# Filter to specific company if configured
|
||||
$targetCompanies = $companies
|
||||
if ($bcCompanyName) {
|
||||
$targetCompanies = $companies | Where-Object { $_.name -eq $bcCompanyName -or $_.displayName -eq $bcCompanyName }
|
||||
if ($targetCompanies.Count -eq 0) {
|
||||
Write-Log "Company '$bcCompanyName' not found. Available: $($companies.name -join ', ')" "ERROR"
|
||||
exit 1
|
||||
}
|
||||
Write-Log "Filtering to company: $bcCompanyName"
|
||||
}
|
||||
|
||||
# Step 5: Download the BACPAC from Azure Storage
|
||||
$downloadSuccess = Download-FromAzureStorage `
|
||||
-StorageSasUri $storageAccountSasUri `
|
||||
-Container $storageContainer `
|
||||
-BlobName $blobName `
|
||||
-OutputPath $OutputPath
|
||||
$totalRecords = 0
|
||||
$totalEntities = 0
|
||||
$failedEntities = @()
|
||||
|
||||
if (-not $downloadSuccess) {
|
||||
Write-Log "Failed to download export" "ERROR"
|
||||
exit 1
|
||||
# Step 3: Export data for each company
|
||||
foreach ($company in $targetCompanies) {
|
||||
$companyName = $company.name
|
||||
$companyId = $company.id
|
||||
|
||||
Write-Log "-----------------------------------------"
|
||||
Write-Log "Exporting company: $companyName ($companyId)"
|
||||
|
||||
# Create company directory (sanitize name for filesystem)
|
||||
$safeName = $companyName -replace '[\\/:*?"<>|]', '_'
|
||||
$companyDir = Join-Path $exportDir $safeName
|
||||
if (-not (Test-Path $companyDir)) {
|
||||
New-Item -ItemType Directory -Path $companyDir -Force | Out-Null
|
||||
}
|
||||
|
||||
foreach ($entity in $entities) {
|
||||
$count = Export-EntityData `
|
||||
-Token $token `
|
||||
-CompanyId $companyId `
|
||||
-CompanyName $companyName `
|
||||
-EntityName $entity `
|
||||
-OutputDir $companyDir
|
||||
|
||||
$totalRecords += $count
|
||||
$totalEntities++
|
||||
|
||||
if ($count -eq 0) {
|
||||
$failedEntities += "$companyName/$entity"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Save export metadata
|
||||
$metadata = @{
|
||||
exportDate = (Get-Date -Format "yyyy-MM-dd HH:mm:ss UTC" -AsUTC)
|
||||
environment = $environmentName
|
||||
companies = @($targetCompanies | ForEach-Object { $_.name })
|
||||
entitiesExported = $totalEntities
|
||||
totalRecords = $totalRecords
|
||||
failedEntities = $failedEntities
|
||||
}
|
||||
$metadata | ConvertTo-Json -Depth 5 | Out-File -FilePath (Join-Path $exportDir "export-metadata.json") -Encoding utf8
|
||||
|
||||
Write-Log "========================================="
|
||||
Write-Log "Export completed successfully"
|
||||
Write-Log "Export completed"
|
||||
Write-Log "Companies: $($targetCompanies.Count)"
|
||||
Write-Log "Entities: $totalEntities"
|
||||
Write-Log "Total records: $totalRecords"
|
||||
if ($failedEntities.Count -gt 0) {
|
||||
Write-Log "Failed/empty: $($failedEntities.Count) entities" "WARN"
|
||||
}
|
||||
Write-Log "========================================="
|
||||
exit 0
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user