Integrating ConnectWise with Atria

Overview

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.

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

info

• The integration at present, uses a 1:1 mapping between an Atria customer and a ConnectWise account. This means that there is no direct support for reseller billing, however it is likely that ConnectWise can handle this natively through configuration.
• 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.
• 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 integrate ConnectWise with Atria, you need to import the extension on your Provisioning Server. This process downloads and installs the latest version of the ConnectWise integration code.

To begin this process, run the below powershell command:

Import-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/Retrieve a ConnectWise API Key and connection details.

In order to communicate with ConnectWise, you need API Keys (public and private) and 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, so store them securely as you’ll need them for the next step.

2. Setup Job to process data

Configure a ConnectWise Batch 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:

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 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 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	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 for selection.	"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:

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

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
CompanyName	Company name is the name allocated to your ConnectWise partner account, used for login.
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:

{
"CompanyName":"XXXXXXXXX",
"PublicKey":"XXXXXXXXX",
"PrivateKey":"XXXXXXXXXX",
"ClientId":"XXXXXXXX"
}

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.

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.

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

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

ConnectWise transfer process executes and updates contracts in ConnectWise, 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 ConnectWise Billing Job.
   • 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.

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

ConnectWise Log Codes and Messages

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

ConnectWise Codes

ID	Occurs When	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).
CW07	Contract quantity Change	Info	(CustomerShortCode) Quantity Update: Line located for (Line Description) with Product ID (SKU) 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.Sku), 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 exists with appropriate parameters.
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) has been removed in the selected billing period.
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).
CW23	End of Process	Info	Billing Process Completed with status (result.Result).