Description
This document outlines the procedure for how Converge can synchronise invoices from Converge to HaloPSA
The Process
Purpose: This document describes how the system synchronizes billing between Converge and HaloPSA. The process ensures that product licenses in HaloPSA always match the current records in system.
Process Overview: The synchronisation runs in four main steps:
○ Connect the Halo with Converge: The reseller can link their HaloPSA account to Converge through the Authorise Code feature. (see the guideline below this docs).
Note: with Admin account, you can also use this function similar to reseller.
But first, you have to select a specific reseller from the partner list.
○ Data Collection: Gather all relevant invoice and product data for the current month.
○ Data Comparison and Preparation: Match this data against existing records in HaloPSA to determine what needs to be created, updated, or deleted.
○ Synchronisation: Apply the changes to Halo PSA through secure API calls.
Main Flow:
○ 1. Connect HaloPSA with Converge: refer 1. Establish a connection between HaloPSA and Converge
○ 2. Data Collection:
■ Collect Invoice Data:
● Retrieve all invoices and product records from our system that fall within the current month.
● For each product, extract details such as: Customer name, Product code, Quantity, Price and Billing cycle.
■ Retrieve HaloPSA Credentials:
● Load the stored authentication credentials for the partner organisation.
● If credentials are expired, the system refreshes them automatically before continuing.
○ 3. Data Comparison and Preparation
■ Step 1 – Confirm Customers Exist in Halo:
● Fetch the complete list of customers (clients) from Halo PSA for the partner.
● Try to match each customer in our system to a customer in Halo by customer name.
● If a customer cannot be found in Halo, all their products are skipped and not synchronised.
■ Step 2 – Determine Product Actions
● Fetch the complete list of software licenses from Halo PSA for the partner.
● For each product in our records:
○ Check if it already exists in Halo:
■ Look for a software license record in Halo where: The license belongs to the matched customer and the license name matches the product code.
○ Determine what to do based on quantity:
■ If no matching license exists:
● If the product quantity is greater than zero → Create a new license in Halo.
● If the product quantity is zero → Skip (no action).
● If a matching license does exist:
● If the quantity is greater than zero → Update the existing license to reflect the current data.
● If the quantity is zero → Delete the license in Halo.
○ Data to synchronise for each license: Product code, Quantity, Price, Billing cycle.
■ Step 3 – Clean Up Old Records
● Any software license in Halo that belongs to the current customer, and does not have a corresponding product in our system will be deleted to keep the data consistent.
○ 4. Synchronisation:
● The system securely connects to the Halo PSA API using the partner’s credentials.
● Each create, update, or delete action is sent to Halo.
● If Halo responds with a temporary error (such as too many requests), the system waits and retries automatically.
● If credentials are invalid, the system refreshes them before retrying.
Error Handling and Logging:
● Critical Failures:
■ If the system cannot fetch customers or licenses from Halo, the entire process stops and is marked as failed.
■ An error message is logged for review.
■ Due to the limitation of the HaloPSA, which allows a maximum of 500 requests every 5 minutes, there are occasions when Converge is unable to transmit data to them, resulting in a synchronization failure. Once the processing is complete, you may initiate the process again by clicking the "Sync" button.
1. Establish a connection between HaloPSA and Converge
1.1 Authorisation
In order to allow Converge to access the Halo API, you must first allow the application access to it. This is done by registering the application in the Halo API settings in the Halo Web Application.
In the web application, whilst logged in as a Halo administrator, go to Configuration > Integrations > Halo API.
The following page allow you can settings up all information regular the Halo API.
Here you will be able to choose “Application” button to redirect the all applications page.
The following page will show all applications that you have allowed to access the Halo API. Select the "+ New" button to add to this list.
Here, you will have the opportunity to select the Authentication method that you wish to utilize for your application. These methods align with the flows provided in OAuth.
Additional settings will become accessible depending on your selection. All methods require a Client ID, which will be provided to you. When using Converge, please select 'Authorisation Code', and ensure that you complete all required
information:
· Application Name: converge
· Login Redirects URLs:
o Testing environment: https://dev.sensely.ai/accounts
Please remember to copy the Client ID to your clipboard for the subsequent step.
Finally, click on the 'Save' button to preserve all your initial settings in HaloPSA.
1.2 Connect with Converge
Access Converge in dev environment at https://dev.sensely.ai/dashboard/.
After configuring the Converge application on Halo, you may now return to the Converge portal and connect it with Halo using the login form. Please follow the setup instructions below:
In Converge, while logged in as an Admin or Reseller account, navigate to the Accounts tab > Halo PSA.
The following page enables you to verify whether your Converge account is connected to Halo. If it is not connected, please complete all necessary information to initiate the connection from Converge to Halo.
· Tenant: this refers to the name of your tenant that you select when establishing your account on Halo. You can observe it in the browser URLs when accessing your Halo account.
· Client ID: This is the client ID that you were included on in the previous step when you set up an application on Halo.
Subsequently, click on the "Connect" button. If your application is valid, you will be shown a Halo logon screen.
Please log in using your Halo account (if you have logged in previously, the application will automatically connect without displaying the login form).
If successful, you will observe that the HaloPSA page on Converge is reloaded, and a new tab labeled "Report" will become visible.
2. Loading the data
Upon establishing the connection as described in step 1 above, Converge will automatically retrieve invoice data from the server corresponding to the current month. This data collection occurs after the successful completion of the 'Invoice Run' process—usually around the 5th of each month, or on the following business day if the 5th coincides with a weekend or holiday.
Additionally, you can view both the total number of successful synchronisations and the total number of failures; this reflects the count of data that has been successfully synced to Halo or not.
Please be advised that you will have the ability to view the data, but you will not be permitted to make any modifications.
When you are prepared, you may click the "Sync" button to transmit the data to Halo PSA.
3. Push invoice to HaloPSA
The sync progress will be shown on the screen. The “Sync” button will remain disabled until the process is complete (or fail).
Once the processing is finished, you will observe that the status of the data has changed and the counter has been updated.
4. Mapping Customer/License
4.1. Setup Customers
Click the Customers tab in the options above the customer details.
Here you can select which Converge customers are to be linked to the relevant HaloPSA customer.
Each Converge customer can only be connected to one HaloPSA customer.
4.2. Setup Product/License
Click the License tab in the options above the customer details.
Here you can select which Converge products are to be linked to the relevant HaloPSA license.
