Integrating Datto Autotask with Atria

Overview

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 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 Autotask Contracts

Depending on the configured schedule, billing data is used to update Autotask. The Contract quantities in Autotask 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 an Autotask account. This means that there is no direct support for reseller billing, however it is likely that Autotask can handle this natively through configuration.
• Atria does not create Accounts or Contracts within Autotask. These must be configured in Autotask for the integration to work.
• The integration looks for a Recurring Services Contract for the Customer - 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 Autotask with Atria, you need to import the extension on your Provisioning Server. This process downloads and installs the latest version of the Autotask integration code.

To begin this process, run the below powershell command:

Import-AtriaExtension -Extension AutotaskPSA -RestartServices

Integration Setup Process

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

1. Create an Autotask API User for Atria

Autotask API User Setup

1. Set up a Security Level for the API User

In Autotask, navigate to Admin > Account Settings & Users > Security Levels:

• Create a copy of the Default API User (API-Only) security level. Once created you can revoke permissions that are not required.
• Rename the Security Level to "Atria Restricted API Access"
• CONTRACTS - Grant Full Permission
• CRM - set to "No Permission", then grant "ALL" Permission to Customer and Cancellation.
• ADMIN - remove all permission, then enable permissions for "Products, Services & Inventory".
• WEB SERVICES API - Under feature access, check "Can logon to web services API".

2. Create an API User

Enter the details for the user that Atria will use to connect to Autotask:

1. Select the Security Level created earlier.
2. Click on Generate Key to generate a unique and complex username key.
3. Click on Generate Secret to generate a unique and complex password.
4. Select "Integration Vendor".
5. In the drop down list, select "Automate101 - Service Automation".

For more information on Autotask API Users, visit here.

2. Setup Job to process data

Configure an Autotask Batch Job in Atria.

A Job in Atria is a recurring task, this will perform the update of Autotask 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 Autotask on 27th of the Month" which describes the what, where and how of what the job performs.

Task: Select Autotask PSA 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
BaseUrl	Autotask Base API – this is the URL for connecting to Autotask. Recommend to leave blank and use the ZoneUser setting to automatically determine the correct URL. If set, this is the URL that Atria will use to access the Autotask API.	""
ZoneUser	Email address of a valid user for your Autotask instance. Suggest you use the address for the API user.	""
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.	""
ProRatedTransactions	If set to True, Atria will set the EffectiveDate of each contract change to the current date/time. When set to False, Atria will use the start date of the current billing period as the effective date. If you do not do part month billing for services, set to false. If you have part month billing, this process will need to execute at least every day in order to capture changes.	"False"
AllowAtriaCreateItems	Determines if Atria can create contract lines. If set to "False" Atria will log that a contract line is missing, if it's set to true, it will create a contract line for the service.	"False"

Example Parameters:

{
"BaseUrl":"",
"ZoneUser":"fred@cspservices.com"
"CustomersFilter":["ASP", "SampleCustomerShortCodeName"],
"BillingPeriod": "Current",
"ProRatedTransactions": "False"
"AllowAtriaCreateItems": "True"
}

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 Autotask
Secret	The corresponding password for the API User

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

{
"UserName":"XXXXXXXXX",
"Secret":"XXXXXXXXX",
}

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 Autotask Account ID. Copy the value from Autotask, and ensure it is set in Atria.

The Account ID can be seen at the top of the Account form (see 1 and 3), Clicking on the clipboard icon copies the Account ID to the clipboard.

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

Setup Product Mapping

The product mapping between Atria and Autotask 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 Autotask Service Identifier (ServiceID) which is the unique integer identifier from the Service entity within Autotask. The SKU property for all items in Atria needs to be configured to match the ServiceID for the billable service in Autotask. We recommend using this field - it's always guaranteed to uniquely identify the Service within Autotask.

Autotask Field to use	Type	Setting to use in Atria Job Parameters
ServiceID	string	"SKUType":("name":"ServiceId", "type":"int")
Name	string	"SKUType":("name":"name", "type":"string")
InvoiceDescription	string	"SKUType":("name":"InvoiceDescription", "type":"string")
description	string	"SKUType":("name":"description", "type":"string")

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 ServiceID in the Autotask Service Catalog.

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

Autotask billing process executes and updates contracts in Autotask, 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 Autotask Billing Job.
   • Check logs to ensure issues have been resolved.

Data Integrity - Resolution Guide

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

ID	Occurs When	Log Level	Resolution
AT04	A customer does not have a Billing Identifier	Warning	Locate the Account in Autotask, copy the Account ID. Locate Customer in Atria, paste the AccountID into the Billing Identifier field and Save.
AT06	Customer Does not have a Recurring Service Contract	Warning	Check that the Account in Autotask has a "Recurring Services" Contract configured.
AT07	SKU Missing in Atria	Warning	If you do not want this data in Autotask, you can ignore or filter using an Atria billing rule. If this needs to be invoiced, ensure a product exists in Autotask and that the SKU code is stored against the Service in Atria.
AT08	Service Does not exist in Autotask	Warning	This means that the Service ID specified in the SKU does not match anything in the Autotask Service catalog. Check the Service Identifier stored in Atria or add the service to Autotask.
AT12	Contract Line Missing in Autotask	Warning	The Recurring Services contract for the customer does not contain this service. Either add the service manually or reconfigure the Atria with the AllowAtriaCreateAdditions set to True.
AT15	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 Autotask Billing Job to update Autotask.

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.

Autotask Log Codes and Messages

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

Autotask Codes

ID	Occurs When	Log Level	Message
AT01	Start of Process	Info	Billing Process Started: For Billing Period (BillPeriod End Date)
AT02	Cannot Connect to Autotask	Error	Failed to connect to Autotask: Error reported was: (Error Details)
AT03	Cannot Connect to Atria	Error	Failed to connect to Atria: Error reported was: (Error Details)
AT04	A customer does not have a Billing Identifier	Warning	(CustomerCode) CompanyID Missing Unable to process records for Atria Customer (CustomerName) – Please add CompanyNumber from Autotask into Billing Identifier field on Customer.
AT05	Company Cannot be located on Autotask	Error	No Company with Customer Number for (customerAccountCode) Found. Check Autotask to see if the customer: (customerName) with Company Number: (customerAccountCode) exists in Autotask.
AT06	Customer Does not have a Recurring Service Contract	Warning	No Contract exists for the Customer (customerName). Check Autotask to see if customer (customerName) and a Recurring Service Contract with Contract Number: (customerAccountCode) exists in Autotask.
AT07	SKU Missing in Atria	Warning	(CustomerName) SKU Missing in Atria: (CustomerName): Skipped Line (LineDescription) for Customer (CustomerName) as no SKU was provided.
AT08	Service Does not exist in Autotask	Warning	(CustomerName) Service Missing in Autotask: (CustomerName): Skipped Line (LineDescription) for Customer (CustomerName) as no SKU was provided.
AT09	Contract Quantity Updated	Info	(CustomerName) Quantity Update: Line located for (LineDescription) with Product ID (Sku) and updated from (Old Value) to (New Value).
AT10	Contract Line Unchanged	Verbose	(CustomerName) Contract Line for (Name) located – quantity is unchanged.
AT11	New Contract Line Created	Info	(CustomerName) Contract Line Added: New Line added for (Name) with Service ID (Id).
AT12	Contract Line Missing in Autotask	Warning	(CustomerName) Contract Line Missing in Autotask: Skipped Line (LineDescription) with Product ID (Sku) for Customer (CustomerName) as the Contract Service SKU could not be located in Autotask.
AT13	Contract Line Reduced to Zero	Info	(customerName) Line located for (serviceDto.Description) with Service Name (serviceDto.Name) is being removed in the selected billing period. The Quantity is updated from (contractServiceUnitDto.Units.ToString("F")) to 0.00.
AT14	Creating new Contract Service fails	Error	(CustomerName) ContractService (Sku), Error Details (Error Details).
AT15	No record found in a billing period	Warning	No records found in Atria for billing period: (Billing Date).
AT16	Secrets values are not valid	Error	Failed to retrieve autotask secrets. Error occurred is: (Message).
AT17	User Email is not available or is not valid	Error	Failed to Retrieve Job Task Parameters: Error reported was: user email is not valid.
AT18	One of the Autotask Secrets is not available	Error	Failed to validate Autotask secrets. (Autotask Secret) must have a valid value.
AT19	Billing Period entry is incorrect	Error	Incorrect billing period date or format recognized.
AT20	Start Processing Deprovisioned Customers	Verbose	Started Processing Deprovisioned Customers.
AT21	Finish Processing Deprovisioned Customers	Verbose	Finished Processing Deprovisioned Customers.
AT22	Start Autotask Worker Task Process	Verbose	Autotask Worker Task Service (JobWorkerTaskTypeId) started.
AT23	Failing to Deserialize Object	Error	Failed to Deserialize object: Error reported was: (Error Details).
AT24	Billing Process Completed	Info	Billing Process Completed with status (Jobstatus).