Introduction to automation APIs
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 Dynamics 365 Business Central users with permissions, can call the APIs.
Note
Azure Active Directory is now Microsoft Entra ID. Learn more
Important
For delegated admin access, you must add the Microsoft Entra application to the AdminAgents group. If the Microsoft Entra application is not added, the consent flow will show an error such as Need pre-consent. For more information, see Pre-consent your app for all your customers in the Graph documentation.
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.
Create a company
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.
Upload and apply a RapidStart package
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.
Insert RapidStart
First step is to create the configuration package, by issuing a POST configurationPackages in the Dynamics 365 Business Central 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}"
}
Upload RapidStart package
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.
Import and apply RapidStart package
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}
Managing users and permission sets
The automation APIs enable users to be set up in Dynamics 365 Business Central.
Modifying user properties
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"
}
Assign user permissions and user groups
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.
Get new users from Office 365
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.
Handling tenant extensions
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.
Installing and uninstalling published add-on 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}
Upload and install a per-tenant extension
Use extensionUpload endpoint to upload and install the extension.
Note
Installing per-tenant extensions using Automation APIs is only possible in SaaS.
Insert extension upload
First step is to create the configuration package, by issuing a POST extensionUpload in the Dynamics 365 Business Central 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".
Upload extension file
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.
Install extension
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.
Monitoring extension installation progress
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
See also
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for