Edit

Cloud Migration APIs Overview (v1.0)

  • Article

APPLIES TO: Business Central 2022 release wave 1 and later

Cloud Migration APIs provide capability for automating the cloud migration process end-to-end by using APIs. You will be able to complete the setup, move the data, and track the progress, trigger upgrade if needed and switch off the cloud migration.

The main endpoint for the API is: https://api.businesscentral.dynamics.com/v2.0/79dbd222-0f30-42a6-9f25-3164d21b269a/Production/api/microsoft/cloudMigration/v1.0/companies

Set up cloud migration

To create the set up you can issue a POST request, if it is a first setup, otherwise use a PATCH request. Issue the request against the following endpoint:

POST https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration
Authorization: Bearer {token}
Content-type: application/json

Body:
{ 
   "productId":"{ProductID}",
   "sqlServerType":"{SqlServerType}",
   "sqlConnectionString":"{SqlConnectionString}"
}

In the JSON example above, productId can be one of following values:

  • DynamicsBCLast – use for cloud migration with upgrade
  • DynamicsBC – use for cloud migration from the same version of Business Central
  • DynamicsGP – use if you are setting up a Dynamics GP cloud migration

In the JSON example above, sqlServerType can be one of the following values:

  • SQLServer – Use if you are migrating from the database that is hosted on the On-Prem SQL server
  • AzureSQL – If you have uploaded the database to migrate to Azure SQL server

And the SqlConnectionString must be the SQL connection string to the database you want to migrate

The above request will return a payload like:

{ 
    "id":"{SetupRecordId}",
   "productId":"{ProductID}",
   "sqlServerType":"{SqlServerType}",
   "sqlConnectionString":"{SqlConnectionString}"
   "runtimeName":"{RuntimeName}",
   "runtimeKey":"{RuntimeKey}"
}

If you are migrating from Azure SQL you can skip next step:

If you are migrating from SQLServer, you should take the runtimeKey value and install and connect Microsoft Integration Runtime by using this key. Then you need to issue a PATCH request such as the following:

PATCH  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration({SetupRecordId})
Authorization: Bearer {token}
Content-type: application/json
If-Match: etag
Body:
{ 
   "productId":"{ProductID}",
   "sqlServerType":"{SqlServerType}",
   "sqlConnectionString":"{SqlConnectionString}",
    "runtimeName":"{RuntimeName}"
}

To complete the setup for both SQL and Azure SQL hosted databases invoke:

POST https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration({SetupRecordId})/ Microsoft.NAV.completeSetup

Cloud migration - create companies

To create on-prem companies you can get the list first by issuing a request like this:

GET https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies 
Authorization: Bearer {token}

The response will be like this for each of the companies:
  {
      "id": "{CompanyId}",
      "name": "{CompanyName}",
      "replicate": false,
      "displayName": "{DislpayName}",
      "estimatedSize":{SizeOfComapny},
      "status": "",
      "created": false
    }

To include the company into the cloud migration you should issue following request:

PATCH  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies ({CompanyId})
Authorization: Bearer {token}
Content-type: application/json
If-Match: etag
 {
      "replicate": true
}

To exclude the company, issue the same request with a false value.

Once the companies are marked for replication you can create them by running the following request:

POST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies({AnyCompanyId}) /Microsoft.NAV.createCompaniesMarkedForReplication

Authorization: Bearer {token}

DELETE and POST are not allowed against this API; it is not possible to create or delete entities on this API.

Cloud migration status

To manage cloud migration or to track the status this API should be used:

GET https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus
Authorization: Bearer {token}

It will return the following payload:

{  
      "id": "679c8aa5-16a9-ec11-80f1-002248334988",
      "runId": "79090ce4-404d-4274-829a-a3b18e99006c",
      "startTime": "2022-03-21T12:57:17Z",
      "endTime": "2022-03-21T12:58:48.35Z",
      "replicationType": "Normal",
      "status": "Completed",
      "source": "Dynamics 365 Business Central earlier versions",
      "details": "Cloud migration setup completed.",
      "tablesSuccessful": 0,
      "tablesFailed": 0,
      "tablesRemaining": 0
}

To start the replication find the cloudMigrationStatus with last endTime and invoke the following command:

POST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.runReplication
Authorization: Bearer {token}

To refresh the status do the following request:

POST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.refreshStatus
Authorization: Bearer {token}

To trigger the data upgrade do the following request:

POST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.runDataUpgrade
Authorization: Bearer {token}

To disable the replication as the last step do the following request:

POST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.disableReplication
Authorization: Bearer {token}

See also

Endpoints for the APIs.