title | description | author | ms.date | ms.topic | ms.author | ms.reviewer |
---|---|---|---|---|---|---|
Introduction to automation APIs |
APIs used to hydrate a Dynamics 365 Business Central tenant. Using the automation APIs, companies can be created, extensions installed, permissions assigned, and RapidStart packages applied. |
henrikwh |
12/03/2023 |
conceptual |
solsen |
solsen |
Automation APIs provide capability for automating company setup through APIs. Once the tenants are created, the automation APIs can be used, in order to hydrate the tenant - to bring the tenant up to a desired state. Usually this involves creating a new company on the tenant, running RapidStart packages, installing extensions, assigning permission sets to users and managing security groups.
Delegated admin credentials and [!INCLUDEd365fin_long_md] users with permissions, can call the APIs.
[!INCLUDE admin-azure-ad-preconsent]
Automation APIs are placed in the microsoft/automation
API namespace. In all the examples below, parameters are marked in parenthesis {}
. Make sure that only valid parameters are passed.
To create a company, an automationCompany endpoint is available. To create a Company issue a POST request as shown in the following example.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/automationCompanies
Authorization: Bearer {token}
Content-type: application/json
{
"name": "CRONUS",
"displayName": "CRONUS",
"businessProfileId": ""
}
The {companyId} must be the ID of a valid company on the tenant. Issue a GET automationCompany request to fetch existing companies.
Note
The company, which is created won't be initialized.
To rename a company, issue a PATCH automationCompanies.
RapidStart is uploaded, installed, and applied using the APIs described below. RapidStart operations can be time consuming. To get the current status of the RapidStart packages and running operations issue a GET configurationPackages as shown in the following example.
GET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages
Authorization: Bearer {token}
In the response, status for the import and apply status is shown, and information about the RapidStart package.
First step is to create the configuration package, by issuing a POST configurationPackages in the [!INCLUDEd365fin_long_md] tenant. Once the configuration package is created, the RapidStart package can be uploaded. See the example below.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages
Authorization: Bearer {token}
Content-type: application/json
{
"code":"{SAMPLE}",
"packageName": "{SAMPLE}"
}
Once the configuration package is created, a RapidStart package can be uploaded with a PATCH configurationPackages. See the example below.
PATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/file('{SAMPLE}')/content
Authorization: Bearer {token}
Content-type: application/octet-stream
If-Match: *
Body: RapidStart file.
Once uploaded, the RapidStart package needs to be imported by issuing a POST on the bound action Microsoft.NAV.import.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/Microsoft.NAV.import
Authorization: Bearer {token}
When the RapidStart package is imported, it can be applied with a POST on bound action Microsoft.NAV.apply.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/configurationPackages({packageId})/Microsoft.NAV.apply
Authorization: Bearer {token}
The automation APIs enable users to be set up in [!INCLUDEd365fin_long_md].
Get the current user properties by issuing a GET users. This gets the UserSecurityId needed on subsequent requests.
To modify the user, create a PATCH user request as shown in the example below.
PATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})
Content-type: application/json
If-Match:*
{
"state": "Enabled",
"expiryDate": "2035-01-01T21:03:53.444Z"
}
Note
User groups are replaced with Security groups and will be deprecated in version 25. For more information, see security group APIs.
To assign users to a user group, issue a POST request against the userGroupMembers entity. See the example below.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})/userGroupMembers
Authorization: Bearer {token}
{
"code": "D365 EXT. ACCOUNTANT",
"companyName" :"CRONUS USA, Inc."
}
To retrieve the list of user groups issue a GET userGroups. This returns the information that you need for the payload above.
Assigning permission sets is identical to adding users to user groups. GET permissionSet returns information about the available permission sets. To assign a permissionSet issue a POST userPermission as shown in the following example.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/users({userSecurityId})/userPermissions
Authorization: Bearer {token}
{
"roleId": "SECURITY"
}
Removing the permissionSet from the user is done by issuing a DELETE userPermissions on the users entity.
To get new users from Office 365, two bound actions on the users endpoint can be used: Microsoft.NAV.getNewUsersFromOffice365
and Microsoft.NAV.getNewUsersFromOffice365Async
. Both actions retrieve new users or new user information from the Office 365 portal but former one is designed for delegated admins and it runs synchronous and latter one schedules a background job, which makes it asynchronous. Microsoft.NAV.getNewUsersFromOffice365Async
returns a link to the scheduled job where you can track the progress. You can also track the progress by issuing a GET scheduledJobs on the users entity. Existing, unchanged users won't be updated with these actions.
Add-on extensions, which are already published to the tenant can be installed and uninstalled. Per-tenant extensions can be uploaded and installed. To get the list of all extensions on the tenant, issue a GET extensions. This returns the packageId needed for installing and uninstalling extensions.
There are three bound actions available on the extensions endpoint: Microsoft.NAV.install
, Microsoft.NAV.uninstall
and Microsoft.NAV.uninstallAndDeleteExtensionData
.
Issue a POST extension using the bound actions. See the example below.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensions({packageId})/Microsoft.NAV.install
Authorization: Bearer {token}
Use extensionUpload endpoint to upload and install the extension.
Note
Installing per-tenant extensions using Automation APIs is only possible in SaaS.
First step is to create the configuration package, by issuing a POST extensionUpload in the [!INCLUDEd365fin_long_md] tenant. Once the extension upload record is created, the extension can be uploaded. See the example below.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload
Authorization: Bearer {token}
Content-type: application/json
{
"schedule":"Current version",
"schemaSyncMode": "Add"
}
Note
Schedule in the body can be "Current version", "Next minor version" or "Next major version".
Note
Schema Sync Mode in the body can be "Add" or "Force Sync".
Once the extension upload record is created, an extension file can be uploaded with a PATCH extensionUpload. See the example below.
PATCH https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload({extensionUploadId})/extensionContent
Authorization: Bearer {token}
Content-type: application/octet-stream
If-Match: *
Body: extension file.
Once extension file is uploaded, the extension needs to be installed by issuing a POST on the bound action Microsoft.NAV.upload.
POST https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionUpload({extensionUploadId})/Microsoft.NAV.upload
Authorization: Bearer {token}
Uninstalling the extension can be done through the bound action Microsoft.NAV.uninstall, as with the add-on extensions. The bound action Microsoft.NAV.uninstallAndDeleteExtensionData can be used to delete the tables that contain data owned by the extension on uninstall. This action can't be undone.
To view ongoing extension installation status, issue GET extensionDeploymentStatus as shown in the following example.
GET https://api.businesscentral.dynamics.com/v2.0/{environment name}/api/microsoft/automation/v2.0/companies({companyId})/extensionDeploymentStatus
Automation company
Company
Configuration package
Extension
Extension deployment status
Extension upload
Permission set
Profile
Scheduled job
User
User group
User group member
User group permission
User permission
Control Access to Business Central Using Security Groups