Linking Subscriptions with ConnectWise Agreement Additions

Owned by Oleg Melnykov
Last updated: Feb 26, 2024
4 min read

Subscriptions can be synchronized with ConnectWise as agreement additions. The following is required to achieve this synchronization:

  • An agreement type per billing cycle

  • ConnectWise additions must be extended by introducing new custom fields for keeping subscription details

This preparation is required so that the interworks.cloud Platform connector can automatically create and update additions in ConnectWise agreements for any corresponding BSS subscriptions.

Creating an Agreement Type for Each Billing Cycle in ConnectWise

Creating Agreement Types

  1. In ConnectWise, go to System → Agreement Type

  2. Create an Agreement Type for each unit (e.g. Subscriptions Monthly)

Finding the Agreement Type IDs

The Agreement Type IDs from ConnectWise must be specified in the BSS Synchronization Lookups.

  1. Using an API application such as Postman, create a GET request and enter the following address:

    https://{connectwiseSite}/v4_6_release/apis/3.0/finance/agreements/types/?conditions=name="Subscriptions Monthly"

  2. Go to Authorization, set the Type to Basic Auth and enter your ConnectWise credentials:

  3. Go to Headers, and add the header clientId, entering your Client ID for the value. If you do not have a Client ID, please see https://interworkscloud.atlassian.net/wiki/spaces/ICPD/pages/4663388 for instructions on how to obtain one.

  4. The response contains the IDs of the Agreement Type :

Updating the Synchronization Lookups

Now you can update the Synchronization Lookups → Subscription Units:

  1. In Setup mode, go to Administration → System Options → Systems Setup and select Settings under ConnectWise.

     

  2. In the Synchronization Lookups → Subscription Units section, enter the corresponding IDs of the Agreement Type previously copied from the API response from ConnectWise.

For example, the monthly billing cycle should be matched with the ID of the monthly agreements, the annual billing cycle with the ID of the annual agreements, and so on.

Creating Custom Fields for Agreement Additions in ConnectWise

Every ConnectWise agreement contains multiple additions. Whenever a subscription is pushed to ConnectWise as an addition, the custom fields created in this section will be updated with the name and ID of the BSS subscription:

Creating Custom Fields

  1. In ConnectWise, go to System → Setup Tables → Custom Fields → (Agreement Addition) Additions

     

  2. Create two custom fields: Subscription Name and Subscription ID. The Field Type must be Text for both. This is needed so that this information can be sent from the BSS to ConnectWise.

     

Finding the Custom Field IDs

The custom field IDs from ConnectWise must be specified in the BSS, to link the fields to each other.

  1. Using an API app such as Postman, create a GET request and enter the following address:

    https://{connectwiseSite}/v4_6_release/apis/3.0/system/userDefinedFields/?conditions=caption="Subscription ID" or caption="Subscription Name"

  2. Go to Authorization, set the Type to Basic Auth and enter your ConnectWise credentials:

  3. Go to Headers, and add the header clientId, entering your Client ID for the value. If you do not have a Client ID, please see https://interworkscloud.atlassian.net/wiki/spaces/ICPD/pages/4663388 for instructions on how to obtain one.

  4. The response contains the IDs of the Custom Fields:

Updating the Server Variables

Now you can update the server variables with the custom field IDs:

  1. In Setup mode, go to Administration → System Options → Systems Setup and select Settings under ConnectWise.

     

  2. In the Server Variables section, enter the corresponding IDs of the custom fields previously copied from the API response from ConnectWise.

      

Synchronization Process

When a subscription is created in the BSS, the synchronization mechanism checks whether the account custom field contains an agreement ID. If it does, an addition is created under the agreement in ConnectWise, with the name and ID of the BSS subscription.

For the list of the fields which are updated during this process, please see the Subscription Entity on the page https://interworkscloud.atlassian.net/wiki/spaces/ICPD/pages/562888914