Installing the Atlar app in Business Central

Prerequisites

This guide will help you with the installation and the integration between Atlar and Business Central. For a smooth setup, you'll need one or more team members with the right access levels to get involved, as you will generate API secrets in both Atlar and Business Central.

First, you'll need access to the Atlar Dashboard. Make sure you are either the Owner of an Atlar organization or have permissions to manage roles, users and third-party connections.

Secondly, you'll need access Business Central. Usually, a Business Central administrator is the go-to person for this kind of access.

Configuration

To connect Atlar and Business Central, you’ll need to configure both systems.
In the Atlar Dashboard, create a role and a programmatic user. In Business Central, set up the Microsoft Entra application.

Create role

1. Navigate to Role Creation
   1. Go to User Management > Roles in your Atlar Dashboard.
   2. Click on Create new.
2. Define Role Permissions
   1. Expand "ERP Access" and select the following permissions:
      1. Account balances: READ
      2. Accounts: READ
      3. Transactions: READ
   2. To enable payments the following permissions are also needed
      1. Counterparties: READ
      2. Credit transfers: CREATE
      3. External accounts: READ
      4. Entities: READ
3. Select Accounts
   1. Click on Select accounts and choose which accounts to include. For comprehensive integrations, it is typical to include all available accounts.
4. Complete the Role Setup
   1. Click on See role summary to review the settings.
   2. Give the role a descriptive name, such as "Business Central". Use this role only for the BC integration.
   3. Click Create.

This ensures your programmatic user has the right permissions to interact with the Atlar API.

Create programmatic user

1. Initiate User Creation
   1. Go to User Management -> Users in Atlar.
   2. Click Actions > New Programmatic User.
2. Configure User Details
   1. Name the user Business Central.
   2. Assign the role you previously created.
3. Access Key and Secret
   1. After setup, click Generate to obtain an Access Key and Secret.
   2. It is important to store these credentials in a secure location as they are only shown once, and necessary for integrating and authenticating the user with Business Central. Ensure these details are accessible as you will need them shortly for setup in Business Central.

You now have a programmatic user ready to interact securely with the Atlar API.

Set up Business Central integration

The Atlar system must be able to talk to Business Central and vice versa. Within Atlar, you can set up a new connection towards Business Central, specifying the necessary API secrets. Some of them already exist in your Business Central environment, and some of the secrets require a Microsoft Entra application to be set up. Microsoft has documentation on how this type of Service-to-Service authentication works.

1. Go to https://entra.microsoft.com and click on App Registrations > New registration
   1. Give the application a name, such as "Atlar BC Integration".
   2. For Supported Account Types, choose the preselected Single Tenant.
   3. Skip the optional fields and click Register
2. Navigate to Certificates and Secrets > New client secret in your newly created app.
   1. Set the expiry to two years. Atlar's system will notify us before it expires.
   2. Under Description, just set "Atlar Integration".
3. Copy the Value of the secret and store it in a safe, temporary location, since you won't be able to see it again later.
4. Navigate to API permissions for your app.
   1. Click on Add a permission > Dynamics 365 Business Central > Application permissions > Add, then tick API.ReadWrite.All.

Once you have created the Microsoft Entra app, head back to Atlar to set up the connection.

1. In Atlar, go to Settings > Third-party connections and click on the Business Central connection. If you don't have one, ask your Atlar contact to help you create it.
2. Click on the Secrets tab and then Actions > Create secret.
3. A dialog will show with a dropdown that holds all required secret types. Created one at a time. When selecting a secret, a descriptive text will explain what it is and how it can be obtained. Some of the secrets will be related to your Entra application, and some will be related to Business Central.
   1. ENVIRONMENT – your Business Central environment name.
   2. TENANT_ID – your Microsoft tenant id in Business Central. To find it, click the ? and navigate to Help & Support. The Tenant ID is found at the bottom of the page. Ensure to not get any extra blank spaces when copying the ID.
   3. CLIENT_ID – your Microsoft Entra Application ID, found in the Overview tab of the Entra Application.
   4. CLIENT_SECRET – the secret value saved in step three of the Microsoft Entra application creation process.

Business Central configuration

To finalize the setup, some configurations are needed in Business Central.

• Install the Atlar extension: Add the Atlar extension to your Business Central setup.
• Business Central service-to-service configuration: Add a Microsoft Entra Application in Business Central to enable access to BC.
• Configure API secrets: Set up the essential credentials for API interaction with Atlar.
• Pair accounts: Link your Business Central accounts with Atlar accounts for seamless data exchange.

Install the Atlar extension

Ask your contact at Atlar to provide you the link and details for how to install the extension.

Business Central service-to-service configuration

Once the Atlar extension has been installed, create a Microsoft Entra application in Business Central. This way, Atlar will be able to authenticate towards Business Central.

1. Inside Business Central, go to the Microsoft Entra Applications page (easily found by using the global search function).
2. Click on New to create a new Microsoft Entra Application Card.
3. Copy the Application (client) ID from the list of applications under App registrations on Microsoft Entra.
4. Give the application a suitable name in the Description, such as "Atlar integration".
5. Set the State field to Enabled
6. Under User Permission Sets you grant the app the required permissions.
   1. By pressing the three dots in the first cell, search for and add the following permissions
      1. ATB SYSTEM (Atlar system access),
      2. D365 BANKING,
      3. D365 BASIC
7. Check in the top right that the configuration has been saved.
8. Grant consent for the Microsoft Entra Application.
9. Ask your Atlar contact to validate that the Atlar platform can access your Business Central environment.

Configure API secrets

After generating the Access Key and Secret from the Atlar dashboard, these need to be entered into Business Central.

1. In Business Central, search for "Atlar Configuration" in the search box and go to the configuration page.
2. Paste the Atlar credentials from the programmatic user setup into the Access Key and Secret fields.

By setting these configurations, you ensure that both the Atlar Access Key and Secret are securely integrated into Business Central, allowing for controlled and safe interaction with the Atlar platform.

Pair entities and accounts

1. Log into the Atlar Dashboard and go to Settings > Third-party connections and click on your Business Central connection.
2. Navigate to the tab called GL Entities. Here you can see your Business Central companies listed, they have to be matched with your respective Atlar entity.
3. Click Edit and match the desired entites. Then, make sure to click Save.
4. Go to Cash Management > Accounts and click on of the accounts you want to pair with a Business Central bank account.
   1. Copy the ID that is the top most field in the view.
5. Now open Business Central and go to Cash Management > Bank Accounts.
   1. Open the account you want to pair with the Atlar account and paste ID in the field called Atlar Account ID.

The Atlar <> Business Central connection is now set up. To be able to make payments or load transactions into Business Central, run the configurations below.

Getting started

To learn more about how to use Business Central, continue reading, or find the respective guides for Using Bank Account Reconciliation and Using the Payment Journal.

Bank Account Reconciliation

The accounts you have paired in the previous steps are now synced with Business Central. You can now enable fetch of transactions and balances either automatically, or manually.

1. To start fetching transactions and balances automatically search and go to Job Queue Entries
   1. Locate ATB Reconciliation, click the three dots in the Status column, and click Edit, then click Set Status to Ready. This will make Business Central start to fetch transactions and balances for all configured accounts.
   2. By default, the first fetch will backfill 7 days. This can be changed by navigating to Atlar Configuration and change the default Transaction History Days before the ATB Reconciliation status is set to ready. Atlar recommends not setting the default transaction histroy days above 30.
2. To fetch transactions manually from Atlar, navigate to Cash Management > Bank Account Reconciliation
   1. Click Actions > Atlar > Fetch Transactions. Actions may be hidden under More options.
   2. By default, the manual fetch will fetch 7 days back. This can be changed by navigating to Atlar Configuration and change the default Transaction History Days before the manual fetch is triggered. Atlar recommends not setting the default transaction histroy days above 30.
3. To verify that the transactions were successfully fetched, go to (or stay on the page) Cash Management > Bank Account Reconciliation and select a statement for a bank account that has been paired. You should see the transactions listed on the left-hand side under Bank Statement Lines.

Payments

To be able to submit payments, you'll need to configure each account and recipient. This will change how payments from each bank account can be made. Thus, run this configuration when you are ready to start running payments through Atlar.

1. Configure bank accounts
   1. Inside Business Central, go to Cash Management > Bank Accounts and select a bank account you would want to execute payments with Atlar.
   2. Verify that it has been matched with an Atlar account, by checking that Atlar Account ID has been populated underneath the section Atlar.
   3. Scroll down to the section Transfer. Click on Payment Export Format, then select ATLAR-CSV.
2. Configure the recipients
   1. Prepare an entity you want to transfer money to, for example a vendor. This part can be done in bulk by following Importing Bank Details.
      1. Navigate to your vendors and select the vendor to configure
      2. Under Payments, set the Payment Method Code to be ATLAR.
      3. Then navigate to Vendor > Bank Accounts on the Vendor card and open, or create, a bank account for the entity.
         1. Under General, set the Country/Region Code
         2. Under Atlar, populate all the bank details, including the payment scheme to be used when paying the vendor.
   2. Naviagte to Cash Management > Payment Journals.
      1. Click New to create a new Payment Journal, using one of your configured bank accounts.
         1. Example name: "ATL Bank Code" --> "ATL B020"
         2. For Bal. Account Type, choose Bank Account
         3. For Bal. Account No., choose the account you want to pay out of
      2. Next, select the Payment Journal created, and add a line with your configured vendor. For more information, follow the guide: Using the Payment Journal.