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