Integrating Kaseya BMS with Atria

Integrating Kaseya BMS with Atria

Introduction

The Atria Kaseya BMS integration takes billing data from Atria and updates the corresponding Recurring Services contract in Kaseya.  Once the contracts are updated, Kaseya can generate accurate invoices for customers.

This document will help you understand how the integration works and what you need to do to get it up and running.

Throughout this document, the term Kaseya means Kaseya BMS (as opposed to other Kaseya products)

Process Overview

1. Service Changes Tracked.

      Changes to provisioning occur in Atria, these are collated and stored in the database, tracking the change made and who made the change.

      For example:

  1. A customer is created
  2. A customer is assigned a service
  3. A user is created
  4. A user is assigned a service
  5. A service is removed from a user
  6. A service plan is changed for a user
  7. An application or resource is assigned to a user

2. Atria Billing Process generates billing views

On a daily basis, Service changes are used to generate billing data for the current Billing Period.  Non-billable data is filtered out based on pre-configured billing rules

3. Update Kaseya Contracts

Depending on the configured schedule, billing data is used to update Kaseya. The Contract quantities in Kaseya are updated to reflect the quantities returned from the Atria API.

Important Notes:

  1. The integration at present, uses a 1:1 mapping between an Atria customer and a Kaseya Account. This means that there is no direct support for reseller billing, however Kaseya is able to handle this natively through configuration.
  2. Atria does not create Accounts or Contracts within Kaseya, these must be configured in Kaseya for the integration to work.
  3. The integration looks for a  Recurring Services Contract   against the Kaseya Account - if you have multiple contracts of the same type within a customer, results may be inconsistent.  

Configuration Process – Guidelines

Import the Kaseya BMS Extension

To enable Kaseya BMS within the Atria Jobs function, please run the below PowerShell on the Provisioning Server

Import-AtriaExtension -Extension KaseyaBMS
Once this has completed, you should see KaseyaBMS in the dropdown within the Jobs Function.

Integration Setup Process

Atria uses the Kaseya BMS Rest API 
An API User needs to be configured in Kaseya, to do this 
  1. Log on to Kaseya BMS using an administrator account
  2. Select the "Admin" tab from the top navigation menu
  3. On the left hand menu, select the HR > Employees menu option
  4. Select the "New" button to display the form to create a new user
    1. Enter the details for the API User
    2. For "User Type" ensure your choose "API Employee"
    3. Select a security role which has permissions to update contracts and read account and contract data.
  5. Create the new user.
Please note - The Email Address provided must be valid, as the Password is emailed to this address.
Once you have the username and password for the API user, you can configure the Kaseya job within Atria.

Create a Job in Atria

A Job in Atria is a recurring task, this will perform the Kaseya update on a scheduled basis.

Access the Jobs Feature:

1. Navigate to Configuration > Jobs

2. Select Add a new Job to show the Job form:

Label:

Give a meaningful name – this will be used to identify the job.  e.g "Transfer Billing Data to kaseya BMS on 27th of each month"

Task:

Select “Kaseya BMS Billing” from the drop down list of available Tasks.

Log Level:

To start with, Select Verbose, this will give increased logging – you can adjust this later.

CRON expression

This determines the frequency of execution. The expression “0 22 26 * *” means that the process will run automatically at 10pm on the 26  th  of the month. More information on CRON expressions is available here  https://support.automate101.com/portal/en/kb/articles/cron-expressions-in-atria

Configuration:

This contains the parameters for your scheduled task, each parameter can have a default value. Parameters are stored in JSON format  https://en.wikipedia.org/wiki/JSON


Name

Purpose

Default Value

ApiUrl

this is the URL for connecting to Kaseya BMS.  this will typically be the same as the URL you use to access the Kaseya BMS User interface.

""

ContractType

Specify the contract type you want Atria to update.  e.g. "Recurring Services"

""

BillingPeriod

Determines which billing period to use for the transfer from Atria.

“Previous” – the previous closed billing period.

“Current” – the current billing period

“YYYY-MM-DD” – specify a date, the billing period will be selected based on the date.

“Current”

CustomersFilter

Will only process records for the specified customers – based on Atria customer code, if blank or unspecified – all customers will be processed. 

“”


SKUFieldMatch
Determines the field used for mapping the Atria SKU with a Kaseya product/contract line.  This can be set to:
"ServiceName" - the Service name field in Kaseya is used to identify the correct service.
"Description" - The description field is used to identify the correct service.
"SKUDescription" - this expects the SKU field to be supplied as the parameter at the start of the product description.  e.g. if the SKU in Atria was MB100, then the description field would be "MB100: this is the description of the MB100 product"

"ServiceName"

Example Parameters

  1. {
  2. "ApiUrl":"https://na1bmspreview.kaseya.com",
  3. "CustomersFilter":["ASP", "FR1", "UJA", "CustomerShortCodeName"],
  4. "BillingPeriod": "Current",
  5. }

The Customer ShortCodeName is identified on the Customers page under the shown properties, or by the Customer Name.

 


Secrets (Configuration)
Secrets are encrypted and stored, once stored, they are unable to be retrieved and displayed in the UI. If you need to update them, re-enter the secrets on the Secrets page and resave the job.  

Value

Description

Username

The API User configured in Kaseya

Password

The corresponding password for the API User
Tenant
A key to identify the Kaseya tenant.

To create the Secrets parameter set – copy below, then replace the XXXX below with your values.

Tenant is also the same as the Customer Name used to sign into Kaseya BMS

  1. {
  2. "UserName":"XXXX ",
  3. "Password":"XXXX ",
  4. "Tenant":"XXXX "
  5. }

Press Save to create the Job



Once the Job has been saved, you can see the Job in the list of jobs

  1. The Label of the new Job is shown in the list of Jobs.
  2. The next Run date is shown – this is calculated based on the CRON expression
  3. To test the execution, Click on the ellipsis and select “Run Now”
  4. You can disable the job and stop it from running indefinitely by selecting disable.
  5. Select delete to permanently remove the job, you will be asked to confirm before deletion.

Testing the Process

Manually run the job – the job may take a few moments to start, when the job has completed a link to the Log will be shown in the “Last Run Result” column. Click on this to view the runs of the job. From here you can select the run to see the detailed log entries.

Log Entries

Each line item in the log has a code, and a logging level.

Errors are likely to be technical issues – for example, if an API is unavailable this will result in an error and the process will end without completion.

Warnings are likely to need some intervention in order to resolve and are likely to be data related – e.g. Could not find something, a reference field is missing etc.  

Verbose  and  Info  provide information, but should not require any action.

Prepare Service Catalog and Contracts

In order to make sure the integration is successful, some work may need to be done to configure the two systems to link records correctly. Depending on how you operate today, this could be simple, or it may require more work to define products.

1. Setup Customer Mapping

Ensure all Atria Customers are correctly mapped to the Kaseya Account Code.

Copy the value from Kaseya, Map the Account Code in Kaseya to the  Customer >  Billing Identifier  (on the edit customer page)

 

2. Setup Product Mapping

The product mapping between Atria and Kaseya is configurable.  When the integration runs, Atria will use the product mapping to locate and update the correct item in the contract for the customer.

By default (and if not specified) Atria will attempt to use the Kaseya Service Name which is the unique name from the Service entity within Kaseya.  The SKU property for all items in Atria needs to be configured to match the Service Name for the associated service in Kaseya.

Review all of the products managed in Atria and ensure everything that needs to be billed has an associated  SKU  which maps directly to the Service Name in the Kaseya Service Catalog.

For information on where to configure SKUs in Atria – read the  Configuring Product SKUs  in this guide  https://support.automate101.com/portal/en/kb/articles/billing-setup-user-guide


In the requirements of Kaseya, this requires a Contract to be created for the customer. This is located under Finance > Contracts.
If this is already created, the Kaseya integration will select the contract and update it accordingly. This will automatically select the Recurring Services contract if multiple are applicable. 

Review and Configure Billing Rules

Setup Billing Rules to mark all non-important items as non-billable – this will stop them from being transitioned to invoices and potentially creating “Noise” in the log files.

If you have completed the Setup Product Mapping in Atria, it may be adequate for you to just exclude all items which do not have a SKU assigned.

For information on billing rules, there is more information in this KB  https://support.automate101.com/portal/en/kb/articles/billing-rule-engine-user-guide

Example Monthly Billing Process

  1. Billing period configured in Atria to start on 26th of the month
  2. BillingPeriod in Kaseya job set to “Previous”

On 25  th  of month

  1. Daily Atria billing job runs and generates complete billing data for month
  2. Billing period closes

On 26  th  of month

Kaseya Billing process executes and updates contracts in Kaseya, processing the Billing Period that has just completed.

Review and Resolve Results:

ID

Task/Action

1

Export Log Entries

  1. Locate Job run, export log and open in Excel

2

Review Errors

  1. Any errors returned will need technical diagnosis and may require the job to be re-executed.

3

Review Warn level entries and action problems as below

  1. Filter to show warnings and resolve issues line by line – see Data Resolution Guide Below

4

Review Informational Changes

  1. Review any informational changes, these will show the changes to contracts that have been made as a result of running the process.
5
  1. Re-execute Processes
  1. Manually Run the Bill Processing
  2. Manually Run the Kaseya Billing Job.
  3. Check logs to ensure issues have been resolved.

Data Integrity - Resolution Guide

Guidance for Resolving Data relationship issues between Kaseya and Atria. All possible codes are listed at the bottom of this article.

IDOccurs WhenLog LevelResolution
KS05A customer does not have a Billing IdentifierWarningLocate the Account in Kaseya, copy the Account Code. Locate Customer in Atria, paste the Account Code into the Billing Identifier field and Save.
KS06Customer Does not have a Recurring Service Contract in Kaseya that contains the service in Atria.WarningCheck that the Account in Kaseya has a "Recurring Services" Contract configured and that a service line exists for the service specified.
KS23SKU Missing in AtriaWarningIf you do not want this data in Kaseya, you can ignore or filter using an Atria billing rule. If this needs to be invoiced, ensure a service exists in Kaseya and that the SKU code is stored against the Service in Atria.
KS14Service Does not exist in KaseyaWarningThis means that the Service referenced din the SKU does not match anything in the Kaseya Service catalog.  Check the Service Identifier stored in Atria or add the service to Kaseya if missing.
KS15No record found in a billing period WarningThis is a warning - it could mean that the billing process has not executed.  Check the billing report in Atria for the specified period.

NOTE that changes made in Atria – e.g. Changing Billing Identifier or SKU values, will not be reflected until the Atria Billing Process is re-executed for the correct billing period. Once the billing process has completed you can re-run the Kaseya Billing Job to update Kaseya.
To quickly re-run the Atria Billing Process and reprocess the current billing records, Navigate to Reports > Service Billing Configuration
Then, select "Reprocess Billing Records"



Please note, this may take a while to run depending on the amount of Customers/Users/Services.

Using UI Features to make the review process easier

Use the following features to ease the process.  


1. The arrow buttons will order the results by error code, this will mean you can go through and fix all similar issues in one go – e.g. for customer identifier issues, order by Code, then go through and fix all missing Billing Identifier problems.

2. Similarly, you can order by Log Type, then scroll down to the warning level logs and review.

3. The search can be used to filter, the Code and Message fields are indexed, for example, typing in CW04 will show all CW04 lines. Or typing a product code may find a log entry.

4. Use the download button to download the data into spreadsheet format – then use Excel or similar to filter/review the data.

Kaseya Log Codes and Messages

The Following table lists the possible codes returned from the Kaseya integration process. 

CodeWhenLog LevelMessage
KS01Process of updating billing items startsInfoBilling Process Started: For Billing Period {date}
KS02When a request from Atria to communicate with Kaseya failsErrorCannot connect to Kaseya. The error occurred is: {errorMessage}
KS03Atria fails to retrieve billing information or an incorrect billing end period date is detectedErrorFailed to connect to Atria: Error reported was : {ErrorMessage}
KS04No changes between Atria and Kaseya contract line quantity was foundVerboseNo changes made in quantity for Product {Product Name} - no update to contract required for Customer {Customer Name}
KS05When Account Exists in Kaseya but no Contract for Account is foundWarningCustomer Contract for {Customer Name - Customer Billing ID} ({Contract Type}) does not exist in Kaseya portal.
KS06When no service line is found for a contractWarningProduct [0] not linked to a contract in Kaseya database for Customer Customer {11}
KS07When contract line is found and updated successfullyInfoProduct {Product Name} quantity updated from {Previous Quantity} to {Latest Quantity} for Customer {Customer Name}
KS08When the request from Atria to update contract line quantity failsErrorFailed to update service line quantity for Customer {Customer Name}. The error is: {Error Message}
KS09There is a customer in Atria but it doesn't have any billing ID defined in Atria.Warning{CustomerCode} CompanyID Missing Unable to process records for Atria Customer {CustomerName} – Please add CompanyID from Kaseya into Billing Identifer field on Customer within Atria.
KS10Validating billing period failsErrorIncorrect billing period date or format recognized.
KS11A removed line item in Atria is detected and process updates its quantity to zero in Kaseya portalWarning{CustomerName} Line located for {LineDescription} with Product ID {Sku} is been removed in the selected billing period. The Quantity is updated from {Quantity} to 0.00")
KS12Task Parameter ValidationErrorInvalid contract type. Please check contract type in task parameters.
KS13Process fails to desterilize a Json object retrieved from KaseyaErrorFailed to Deserialize Job Task Parameters: Error reported was: {e.Message}
KS14There is a billing item with SKU defined in Atria but no such a service is defined in Kaseya portal using SKUMatchField in Job ParametersErrorService Missing in Kaseya. Please check Kaseya portal to see if a Service with '{jobParameters.SkuFieldMatch}': '{item.Sku}' exists and is active.
KS15A period is selected that doesn't have any billing item record. (Needs code update to reflect the following msg: No records found in Atria for billing period)WarningNo invoice is received for the billing period: {invoiceDate}
KS16When at least one of the secret values is nullErrorFailed to retrieve Kaseya secrets. Error occurred is: {e.Message}
KS17Process of generating token to access Kaseya API failsErrorToken could not be found
KS18Process of Reducing deprovisioned items to zero startsVerboseStart Processing Deprovisioned Customers
KS19Process of Reducing deprovisioned items to zero finishesVerboseProcessing Deprovisioned Customers Completed
KS20When API Url is emptyInfoFailed to Retrieve Job Task Parameters: Error reported was: api url is not available
KS21When at least one of the Kaseya secrets has null valueErrorFailed to validate Kaseya secrets.
KS22No Account is found in Kaseya that matches with the Billing ID of the customer in AtriaErrorAtria Customer for Account Code '{Billing ID}' is not defined as a valid Kaseya Account
KS23SKU Missing in Atria : {CustomerName} : Skipped Line {LineDescription} for Customer {CustomerName} as no SKU was providedWarning{line.CustomerName}
KS24The whole process of updating contract lines endsInfoBilling Process Completed with status {Result}

    • Related Articles

    • Integrating ConnectWise with Atria

      Introduction The Atria ConnectWise integration takes billing data from Atria and updates the corresponding service quantities in the ConnectWise company agreement. This document will help you understand how the integration works and what you need to ...

    • Atria Billing Setup User Guide

      Objective This article describes how to configure Atria to utilize the latest billing features. This document outlines the billing setup attributes that should be configured.    Applies to Introduced in Atria version 12.0.0 Billing Setup Overview To ...

    • Integrating Datto Autotask with Atria

      Introduction The Atria Autotask integration takes billing data from Atria and updates the corresponding Recurring Services contract line quantity in Autotask . This document will help you understand how the integration works and what you need to do ...

    • Atria API Policy

      Purpose To provide direction and guidance to Atria customers and third parties integrating with Atria API’s. Atria API's API Name Type Purpose Cortex API XML based over HTTPS https://{hostname}/cortexapi Used by AD Sync, Customer, User, Service ...

    • Display Patterns for Billing Line Descriptions

      Purpose: When generating billing data, two descriptions are generated for each billable item - Line description (detailed) and summary descriptions.   The Summary Description serves two purpose: Used as a template for your invoice lines and reporting ...