Integrating Kaseya BMS with Atria

Overview

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.

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

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

Diagram

Process Overview

1. Service Changes Tracked

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

For example:

• A customer is created
• A customer is assigned a service
• A user is created
• A user is assigned a service
• A service is removed from a user
• A service plan is changed for a user
• 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. This contains the source for billing records. 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.

info

• 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 it is likely that Kaseya can handle this natively through configuration.
• Atria does not create Accounts or Contracts within Kaseya. These must be configured in Kaseya for the integration to work.
• The integration looks for a Recurring Services Contract against the Kaseya account. If you have multiple contracts of the same type within a customer, the results may be inconsistent.

Configuration Process - Guidelines

Integration Installation Process

To integrate Kaseya with Atria, you need to import the extension on your Provisioning Server. This process downloads and installs the latest version of the Kaseya integration code.

To begin this process, run the below powershell command:

Import-AtriaExtension -Extension KaseyaBMS -RestartServices

Integration Setup Process

To allow Atria to use the KaseyaBMS REST API, an API user and Atria Job need to be configured.

1. Create an Kaseya API User for Atria

Kaseya API User Setup

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.
   • Enter the details for the API User.
   • For "User Type" ensure your choose "API Employee".
   • Select a security role which has permissions to update contracts and read account and contract data.
5. Create the new user.

note

The Email Address provided must be valid, as the password is emailed to this address.

2. Setup Job to process data

Configure an Kaseya BMS Batch Job in Atria.

A Job in Atria is a recurring task, this will perform the update of Kaseya on a scheduled basis. psa Access the Jobs Feature:

1. Navigate to Configuration > Jobs.

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

Label: Give the job a meaningful name, this will be used to identify the job in future. An example of this is "Transfer Billing Data to Kaseya BMS on 27th of the Month" which describes the what, where and how of what the job performs.

Task: Select Kaseya BMS Billing from the drop down.

Log Level: To start with, select Verbose. This will give increased logging and you can adjust this later as required.

CRON expression: This determines the frequency of execution. The expression '0 22 26 * *' means that the process will run automatically at 10pm on the 26th of the month. More information on CRON expressions is available here: 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:

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

note

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 Atria Interface.

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 with your values:

{
"UserName":"XXXX ",
"Password":"XXXX ",
"Tenant":"XXXX "
}

Click Save to create the Job

The job is now displayed in the Jobs screen:

• The Label of the new Job is shown in the list of Jobs.
• The next Run date is shown. This is calculated based on the CRON expression, in this case, the next run will be on 26th December at 10pm.
• To test the execution, click on the ellipsis and select Run Now.
• You can disable the job and stop it from running indefinitely by selecting disable.
• 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.

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 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 be able to link records correctly. Depending on how you operate today, this could be very simple, or it may be more complex.

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:

Map the Account ID in Atria : Customer > Billing Identifier.

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, refer to this guide Configuring Product SKUs.

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 of 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, refer to Billing Rules.

Example Monthly Billing Process

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

On the 25th of the month:

• Daily Atria billing job runs and generates complete billing data for month.
• 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:

1. Export Log Entries

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

2. Review Errors

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

3. Review Warn Level Entries and Action Problems

   • Filter to show warnings and resolve issues line by line. Refer to the Data Resolution Guide below.

4. Review Informational Changes

   • Review any informational changes to identify updates to contracts resulting from the process.

5. Re-execute Processes

   • Manually run the Bill Processing.
   • Manually run the Kaseya Billing Job.
   • 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.

ID	Occurs When	Log Level	Resolution
KS05	A customer does not have a Billing Identifier	Warning	Locate the Account in Kaseya, copy the Account Code. Locate Customer in Atria, paste the Account Code into the Billing Identifier field and Save.
KS06	Customer Does not have a Recurring Service Contract in Kaseya that contains the service in Atria.	Warning	Check that the Account in Kaseya has a "Recurring Services" Contract configured and that a service line exists for the service specified.
KS23	SKU Missing in Atria	Warning	If 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.
KS14	Service Does not exist in Kaseya	Warning	This means that the Service referenced in 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.
KS15	No record found in a billing period	Warning	This is a warning - it could mean that the billing process has not executed. Check the billing report in Atria for the specified period.

info

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 this has been 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, meaning you can go through and fix all similar issues in one go. For example, 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 by the Code and Message fields. 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.

Kaseya Codes

Code	When	Log Level	Message
KS01	Process of updating billing items starts	Info	Billing Process Started: For Billing Period (date)
KS02	When a request from Atria to communicate with Kaseya fails	Error	Cannot connect to Kaseya. The error occurred is: (errorMessage)
KS03	Atria fails to retrieve billing information or an incorrect billing end period date is detected	Error	Failed to connect to Atria: Error reported was : (ErrorMessage)
KS04	No changes between Atria and Kaseya contract line quantity was found	Verbose	No changes made in quantity for Product (Product Name) - no update to contract required for Customer (Customer Name)
KS05	When Account Exists in Kaseya but no Contract for Account is found	Warning	Customer Contract for (Customer Name - Customer Billing ID) ((Contract Type)) does not exist in Kaseya portal.
KS06	When no service line is found for a contract	Warning	Product [0] not linked to a contract in Kaseya database for Customer Customer (11)
KS07	When contract line is found and updated successfully	Info	Product (Product Name) quantity updated from (Previous Quantity) to (Latest Quantity) for Customer (Customer Name)
KS08	When the request from Atria to update contract line quantity fails	Error	Failed to update service line quantity for Customer (Customer Name). The error is: (Error Message)
KS09	There 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.
KS10	Validating billing period fails	Error	Incorrect billing period date or format recognized.
KS11	A removed line item in Atria is detected and process updates its quantity to zero in Kaseya portal	Warning	(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
KS12	Task Parameter Validation	Error	Invalid contract type. Please check contract type in task parameters.
KS13	Process fails to deserialize a JSON object retrieved from Kaseya	Error	Failed to Deserialize Job Task Parameters: Error reported was: (e.Message)
KS14	There is a billing item with SKU defined in Atria but no such service is defined in Kaseya portal	Error	Service Missing in Kaseya. Please check Kaseya portal to see if a Service with '(jobParameters.SkuFieldMatch)': '(item.Sku)' exists and is active.
KS15	A period is selected that doesn't have any billing item record.	Warning	No invoice is received for the billing period: (invoiceDate)
KS16	When at least one of the secret values is null	Error	Failed to retrieve Kaseya secrets. Error occurred is: (e.Message)
KS17	Process of generating token to access Kaseya API fails	Error	Token could not be found
KS18	Process of Reducing deprovisioned items to zero starts	Verbose	Start Processing Deprovisioned Customers
KS19	Process of Reducing deprovisioned items to zero finishes	Verbose	Processing Deprovisioned Customers Completed
KS20	When API Url is empty	Info	Failed to Retrieve Job Task Parameters: Error reported was: api url is not available
KS21	When at least one of the Kaseya secrets has null value	Error	Failed to validate Kaseya secrets.
KS22	No Account is found in Kaseya that matches with the Billing ID of the customer in Atria	Error	Atria Customer for Account Code '(Billing ID)' is not defined as a valid Kaseya Account
KS23	SKU Missing in Atria	Warning	(line.CustomerName): Skipped Line (LineDescription) for Customer (CustomerName) as no SKU was provided
KS24	The whole process of updating contract lines ends	Info	Billing Process Completed with status (Result)