Integrating Connectwise Manage with Atria for automated service billing

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

Atria and ConnectWise integration

Process Overview

Process of updating ConnectWise Agreements from Atria

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

To set up ConnectWise within Atria it requires importing the Extension. This is carried out on the provisioning server.
This downloads and installs the latest version of the ConnectWise integration code. 

You do this by running the below PowerShell command
Import-AtriaExtension -Extension ConnectWiseManage -RestartServices

After this has been ran, you are free to continue with the integration. 

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

1. Obtain 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.

2. Generate API Tokens

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.

Access the Jobs Feature:

1. Navigate to Configuration > Jobs

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

Screenshot of Edit Job page in Atria

Label:

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.

Task:

Select “ConnectWise Manage Billing” from the drop down.

Log Level:

To start with, Select Verbose, this will give increased logging – 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 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

Connectwise Base API – this is the URI for connecting to your ConnectWise system.

""

AgreementType

Contract Type for Atria Services – this is configurable within ConnectWise

"Cloud and Hosting Services"

AllowAtriaCreateAdditions

Allows process to create Additions to the agreement for missing services, to enable, set to “True”

“False”

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.

“”

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.

Value

Description

CompanyName

Company name is the name allocated your ConnectWise partner account, it is the same value you use when you login to ConnectWise.

PublicKey

API Tokens – see above

PrivateKey

API Tokens – see above

ClientID

Provided by ConnectWise – see above

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:

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 ConnectWise Billing Job.
  3. Check logs to ensure issues have been resolved.

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.

Error

Occurs When

How to Resolve

CW04

A customer does not have a Billing Identifier

Locate the Company in ConnectWise, copy the CompanyID. Locate the Customer in Atria, Paste the CompanyID into the Billing Identifier field. Save. 

CW05

A line item in Atria does not have a SKU code

If you do not want this data in ConnectWise, you can ignore or filter using an Atria billing rule. If this needs to be invoiced, ensure a product exists in ConnectWise and that the SKU code is stored against the Service in Atria.

CW06

The product in Atria cannot be located in ConnectWise

Check the Product SKU and make sure it is configured within ConnectWise.

CW14

Either the company cannot be located or an agreement of the required type does not exist.

Locate the company in ConnectWise and make sure an agreement of the correct type is configured. 

CW15

No data was returned from Atria for the specified billing period

This could mean that an incorrect date was used or the Bill Processing has not executed successfully. 

CW20

A service has been removed for this customer.

The quantity is set as 0 on the addition line. There is no specific action required.

CW22

An agreement has been found but the addition for the specified SKU is absent.

If AllowAtriaCreateAdditions is set to False, Atria will not automatically add Additions. To resolve, manually add an addition to the Agreement, or change this setting to True.

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. 

ID

Occurs

Log Level

Message

CW01

Start of Process

Info

Billing Process Started : For Billing Period {BillPeriod End Date}

CW02

Cannot connect to Connectwise

Error

Failed to connect to Connectwise: Error reported was : {Error details}

CW03

Cannot connect to Atria

Error

Failed to connect to Atria: Error reported was : {Error details}

CW04

Company ID missing in Atria

Warn

{CustomerShortCode} CompanyID Missing Unable to process records for Atria Customer {CustomerName} – Please add CompanyID from ConnectWise into Billing Identifier field on Customer

CW05

SKU Missing in Atria

Warn

{CustomerShortCode} SKU Missing in Atria : {CustomerShortCode} : Skipped Line {LineDescription} for Customer {CustomerName} as no SKU was provided

CW06

Product doesn’t exist in ConnectWise

Warn

{CustomerShortCode} Product Missing : Skipped Line {LineDescription} with Product ID {SKU} for Customer {CustomerName} as the SKU could not be located in ConnectWise. Please add this product in ConnectWise portal

CW07

Contract quantity Change

Info

{CustomerShortCode} Quantity Update : Line located for {Line Description} with Product ID {SKU} and updated from {beforequantity} to {afterquantity}

CW08

New Contract Line Added

Info

{CustomerShortCode} Contract Line Added : New Line added for {Line Description} with Product ID {SKU}

CW09

Contract Line has no changes

Verbose

{CustomerShortCode} Contract Line for {Line Description} located – quantity is unchanged

CW10

Error on retrieving agreement addition ConnectWise

Error

{CustomerShortCode} Contract Line {LineDescription}, SKU {SKU}, Error Details {Error}

CW11

Error on creating new product catalog item

Error

{billingInvoiceDataitem.CustomerName} Catalog Item {billingInvoiceDataitem.LineDescription}, SKU {billingInvoiceDataitem.LineDescription}, Error Details {response.ErrorMessage}

CW12

Error creating agreement addition

Error

{billingInvoiceDataitem.CustomerName} Addition {billingInvoiceDataitem.Sku}, Error Details {response.ErrorMessage}

CW13

Error Deserializing Json objects

Error

Failed to Deserialize object: Error reported was: {e.Message}

CW14

Error when customer or agreement doesn't exist in ConnectWise

Warn

No Agreement exists for the customer {customerName}. Check ConnectWise to see if the customer: {customerName} with Id: {customerAccountCode} and agreement type: {_taskParameters.AgreementType} exists.

CW15

Error when no data exists in the billing period specified.

Warn

No records found in Atria for billing period {invoiceDate}.

CW16

Error reading connectwise configuration secrets

Error

Failed to retrieve ConnectWise secrets. Error occurred is: {e.Message}

CW17

api url is null or empty

Error

Failed to Retrieve Job Task Parameters: Error reported was: api url is not available

CW18

invalid value for secrets

Error

Failed to validate ConnectWise secrets. {property.Name } must have a valid value

CW19

invalid Billing period date or format

Error

Incorrect billing period date or format

CW20

Product has been removed from customer in this period.

Warn

{CustomerName}| Line located for {addition.LineDescription} with Product ID {addition.Sku} is been removed in the selected billing period. The Quantity is updated from {addition.Quantity} to 0.00

CW21

Agreement type is invalid.

Error

Invalid agreement type. Please check agreement type in job parameters.

CW22

Contract Line doesn't exist in ConnectWise

Warn

Contract Line Missing in ConnectWise : Skipped Line {addition.LineDescription} with Product ID {addition.Sku} for Customer {addition.CustomerName} as the SKU could not be located in ConnectWise

CW23

End of Process

Info

Billing Process Completed with status {result.Result}


    • Related Articles

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