First steps with the ConnectWise integration

Introduction

This article explains how to access, authenticate, and configure the ConnectWise integration in the Platform. These are one-time setup steps that must be completed before mapping or syncing any data.

In this article:

• Accessing the ConnectWise integration
• Settings page
  • Authentication sub-section
  • Configuration sub-section
  • Dictionary sub-section
• Dashboard page

Accessing the ConnectWise integration

The ConnectWise integration is configured from the Settings > Integrations area of the Platform.

To access the ConnectWise integration:

1. Navigate to Settings → Integrations in the Platform.
    

   

   

2. Locate the PSA Tools section in the top tab bar.

   

    

3. Click the ConnectWise tile.

   

    

4. You are taken to the ConnectWise integration area. The left navigation contains four items in this order: Dashboard, Mapping, System Logs, and Settings.

   

Settings page

The Settings page is the configuration hub for the ConnectWise integration. It contains three sub-sections, accessed via the tabs at the top: Authentication, Configuration, and Dictionary.

The page header reads: "Settings — Configure your ConnectWise integration credentials and preferences."

Authentication sub-section

The Authentication tab is where you provide the API credentials that let the Platform communicate with your ConnectWise instance. Until these credentials are saved, the rest of the integration remains disabled.

How to obtain API credentials info box

At the top of the Authentication page, a collapsible info box titled How to obtain API credentials provides a brief explanation:

Connection Credentials form — first connection

On first access, the Connection Credentials section is empty. The description reads: "Configure your ConnectWise Integration to manage and bill your customers."

Required fields:

• API URL — the URL of your ConnectWise site. Example format: https://staging.connectwisedev.com.
• ConnectWise Company ID — your ConnectWise company identifier.
• API Public Key — generated under System > Members in your ConnectWise instance, on the member account's API Keys tab.
• API Private Key — generated alongside the public key. Stored securely on the Platform side. After saving, the field is displayed as masked (asterisks) and the value cannot be retrieved back in plain text.

Testing the connection

After entering credentials, verify them before saving. This catches typos and missing permissions before they propagate to other tabs.

1. Click Test Connection.
2. Wait for the test to complete.
3. If successful, a green message displays: "Test is successful."
4. If the test fails, a red message displays: "Test is not successful." Verify each credential and try again.

Saving the connection

1. Click Save to store the credentials.
2. If you click Save without testing first and the values are incorrect, the Platform shows the error: "Connection was not established. Please validate settings information."
3. On successful save, you are automatically redirected to the Mapping page > Organizations tab so you can begin mapping immediately.

Authentication page after saving

Once the credentials are saved and verified, the Authentication page displays the populated fields (with API Private Key masked) and an Administrative Actions section appears at the bottom.

Administrative Actions — Disconnect Integration

The Administrative Actions section, located at the bottom of the Authentication page, contains high-impact actions and is visually highlighted with a red-tinted border and background.

To disconnect the integration:

1. Click the red Disconnect button.
2. A confirmation modal appears with a red warning icon.
   
3. Click Confirm to proceed, or Cancel to abort.

On successful disconnection:

• A success toast appears: "Integration disconnected successfully."
• The API credential fields are cleared.
• The connection status indicator on the Dashboard updates to Not Connected.
• Any active or scheduled sync jobs are immediately cancelled or paused.
• The API Private Key is securely removed from the Platform.
• The disconnection event is recorded together with the user name and timestamp for audit purposes.

Configuration sub-section

The Configuration tab controls how the Platform transforms Subscription and Invoice data before sending it to ConnectWise. Settings here apply to all future syncs only and do not retroactively update records already in ConnectWise.

This setting applies to all future invoice syncs. Already-synced records in ConnectWise will not be retroactively updated.

Agreement Type (required)

Select the default Agreement Type that ConnectWise should use when a Customer has no existing matched Agreement for the line being posted. This setting is mandatory — the integration cannot post invoice lines until it is selected.

The dropdown is populated from the list of Agreement Types configured in your ConnectWise instance. If you do not see the expected types in the list, ensure they exist in ConnectWise and re-test the connection.

Charge End Date Configuration

Configure how the Charge End Date on each Invoice line is calculated, per Charge Type. Rules are evaluated at sync time. If no rule matches the line's Charge Type and no manual override has been applied, the default behaviour is used (see the NOTE at the end of this sub-section).

To add a Charge End Date rule:

1. Click Add Rule below the section header.
2. In the new row, pick a Charge Type from the dropdown. Available types: Cycle Fee, Correction, Usage Fee, Item Fee, Purchase Fee, One Time Fee. Already-used types are not selectable in subsequent rules (a charge type can have only one rule at a time).
   
3. Pick a Rule from the dropdown. The two available rules are:
   • Last day of invoice month
   • First day of following month
     
4. To remove a rule, click the delete (trash) icon at the right end of the row.
5. Click Save Configuration at the bottom of the page to persist the rules.

When a rule is applied to a line during sync, the Charge End Date column on the Invoices tab displays a System Updated badge next to the value. If a user later overrides the value manually, the badge changes to User Updated.

Charge Start Date Configuration

Configure how the Charge Start Date is adjusted, per Billing Cycle. The configuration is structured the same way as the Charge End Date rules: an Add Rule button, a row per rule, and a delete icon to remove a rule.

To add a Charge Start Date rule:

1. Click Add Rule.
2. Pick a Billing Cycle from the dropdown.
   
3. Pick the rule First day of next month — "Charge start dates are adjusted forward to the first day of the next month. Example: if charge starts on Jan 15, it will be set to Feb 1."
   
4. Click Save Configuration.

As with Charge End Date, applied rules display a System Updated badge on the Invoices tab, and manual overrides display a User Updated badge.

Custom Charge Type Names

Customize the display names sent to ConnectWise for the six Platform charge types. The left column shows the Platform charge type (read-only); the right column contains an editable field for the value that will be sent to ConnectWise. The original Platform values are not changed; only the values transmitted to ConnectWise are renamed.

Platform charge types:

• Cycle Fee
• Correction
• Usage Fee
• Item Fee
• Purchase Fee
• One Time Fee

When a custom name is in effect, any Invoice line synced to ConnectWise with that Charge Type displays a System Updated badge in the Charge Type column on the Invoices tab.

Automated Daily Invoice Line Sync

Toggle Automated Daily Invoice Line Sync on or off. When enabled, fully mapped invoice lines are posted to ConnectWise automatically every day at midnight UTC. Invoice lines that are not fully mapped are skipped and remain on the Invoices tab for manual review.

Disable this toggle during periods of active remapping or configuration changes so that incomplete data is not posted while you are still reviewing.

Agreement configuration in ConnectWise

The selected configuration settings are reflected directly in the related ConnectWise Agreement.

Depending on the selected configuration:

• Agreement details can contain different billing and synchronization settings.
• Synchronized invoice lines are later attached to the configured agreement as Additions.
• Related invoice synchronization behavior follows the mapped Agreement configuration.

Agreement selected from the dropdown in the Platform:

Corresponding Agreement in the ConnectWise:

\

Agreement details are being configured in the Configuration Settings.

And will be reflected also in the ConnectWise in Agreement's details.

Saving the Configuration

After making any changes on the Configuration tab, click Save Configuration at the bottom of the page. Changes apply to all future syncs only.

Dictionary sub-section

The Dictionary tab is a read-only reference that explains how field names map between the Platform and ConnectWise, as the terminology between those two systems differs in several places. 

This reference is displayed on the Settings > Dictionary sub-tab. It is provided to reduce confusion when users work in both systems and encounter different terminology for the same concepts.

Dashboard page

The Dashboard page provides an overview of the integration status and recent sync activity. It is the first tab in the left navigation and is the default landing page after authentication has been saved and an Agreement Type has been selected.

Sync tiles

Two sync tiles are displayed at the top of the page. Each tile shows the relative time of the most recent sync, with your local timezone.

• Last Sync to Platform — the relative time since Organizations were last synced from ConnectWise to the Platform, with your local timezone (for example, 7h ago (UTC+02:00 Europe/Warsaw)). If the last sync was more than one day ago, the value is displayed as "X days ago". A refresh icon on the tile lets you re-fetch the timestamp without reloading the page.
• Last Sync to PSA — the relative time since Subscription and Invoice data was last synced from the Platform to ConnectWise. An external link icon on the tile lets you open the corresponding view in ConnectWise in a new browser tab.

When no sync has yet been performed, the tile displays "No sync yet" instead of a timestamp.

System Information panel

The System Information panel below the tiles shows the current connection state and integration version.

• Environment — the ConnectWise site URL is displayed (e.g., https://staging.connectwisedev.com), accompanied by a status badge:
  • Connected (green badge) — the integration is currently authenticated and operational.
  • Not Connected (red badge) — credentials are missing, invalid, or the integration has been disconnected.
• Integration Version — the ConnectWise API version currently in use by the integration (for example, v4.0 release). Used by support when troubleshooting.

Summary

This article covered the one-time setup steps for the ConnectWise integration: accessing the integration, entering and testing API credentials, configuring Agreement Type and charge-date rules, and understanding the Dashboard. Once these steps are complete, the integration is ready for day-to-day mapping and syncing.

Related content

• How to obtain ConnectWise credentials
• ConnectWise integration overview
• Mapping organizations and products
• Loading and syncing invoice lines
• How configuration settings are reflected in ConnectWise
• System Logs and troubleshooting