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 do to get it up and running.

Process Overview

1. Service Changes Tracked.

      Changes to provisioning occur in Atria, these are collated and stored in the database, tracking the change that was 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. This contains the source for billing records. Non-billable data is filtered out based on pre-configured billing rules

3. Update ConnectWise Agreements

      Depending on the configured schedule, billing data is used to update ConnectWise . The Agreement Additions in ConnectWise 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 ConnectWise. This means that there is no direct support for reseller billing, however it is likely that ConnectWise can handle this natively through configuration.
2. Atria does not create Companies or Agreements in ConnectWise, Companies and Agreements must be Created or Pre-Configured in ConnectWise for the integration to work.
   
3. The integration looks for the first agreement of the specified type for the Customer  (by default this is set to "Hosting and Cloud Services") - If you have multiple agreements of the same type within a customer, the results may be inconsistent.  Change the configuration setting "AgreementType" to match your ConnectWise instance.

Configuration Process – Guidelines

Integration Installation Process

Install-AtriaExtension -Extension ConnectWiseManage -RestartServices

Integration Setup Process

This involves getting connectivity details between the two systems and setting up the batch process which performs the data transfer between Atria and ConnectWise

1. ConnectWise API Setup

Create/Get a ConnectWise API Key and Connection details

2. Setup Job to process data

Configure a ConnectWise Batch Job in Atria

ConnectWise API Setup

In order to communicate with ConnectWise, you need API Keys (public and private) + a ClientID

A ClientID is needed for all requests made to ConnectWise via the API. This will be created by ConnectWise or you may already have one. The ClientID is unique to your Connectwise Account. There is more information available at https://developer.connectwise.com

You can request a new ConnectWise ClientID by contacting ConnectWise developer support.

API Access is handled via Tokens which are generated against a “Member”

1. Login to your ConnectWise Portal

2. Go to System > Members

3. Select the “API Members” tab

4. Add a new API member called “Atria API User”

5. Go to “API Keys”

6. Add a new Key

Once keys have been created, you cannot access them again from the ConnectWise UI, store them securely - you’ll need them at the next step!

Create a Job in Atria

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

1. Navigate to Configuration > Jobs

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

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

Select “ConnectWise Manage Billing” from the drop down.

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

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

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

Example Parameters

1. {
2. "apiUrl":" https://api-staging.connectwisedev.com/v4_6_release/apis/3.0/",
3. "CustomersFilter":["ASP", "SampleCustomerShortCodeName"],
4. "BillingPeriod": "Current",
5. "AgreementType": "Hosting and Cloud Services",
6. }

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.

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

1. {
2. "CompanyName":"XXXXXXXXX",
3. "PublicKey":"XXXXXXXXX",
4. "PrivateKey":"XXXXXXXXXX",
5. "ClientId":"XXXXXXXX"
6. }

Press Save to create the Job

The job is now displayed in the Jobs screen:

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, in this case – the next run will be on 26 ^th December at 10pm.
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 an 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 is u

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.

Check Product Catalog and Agreements

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.

The high level process:

Setup Customer Mapping

Ensure all Atria Customers are correctly mapped to the ConnectWise Company identifier. Copy the value from ConnectWise, and ensure it is set in Atria.

ConnectWise : Company > CompanyID (on the edit company page in ConnectWise)

Atria : Customer > Billing Identifier (on the edit customer page) under Additional Options as shown below

Setup Product Mapping

Review all of the products managed in Atria and ensure everything that needs to be transferred to the agreement has an associated SKU which maps directly to a ProductID in the ConnectWise Product Catalog.

If you do not use SKU’s then you will need to create a SKU for each product offering and ensure these are updated in Atria.

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

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, 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 ConnectWise 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

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

Review and Resolve Results:

Data Integrity - Resolution Guide

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

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 this has been completed you can re-run the ConnectWise Billing Job to update ConnectWise.

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 awhile 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.

ConnectWise Log Codes and Messages

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