Synchronizing Subscriptions with ConnectWise

Subscriptions can be synchronized to ConnectWise as agreement additions. For this synchronization to work, the following steps must be followed:

  • Have an agreement per billing cycle and customer in your ConnectWise. If you are selling both monthly and annual subscriptions, you will need to create two agreements in ConnectWise for each new customer.

  • Link your BSS account with the ConnectWise agreements using the custom fields you need to create for this purpose.

  • Extend the ConnecWise additions by introducing new custom fields for keeping subscription details.

This preparation is necessary for our connector to be able automatically to create and update additions in ConneWise agreements for the subscriptions managed by our system.

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:

  1. In ConnectWise, go to SystemSetup TablesCustom FieldsAdditions

     

  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://staging.connectwisedev.com/v4_6_release/apis/3.0/finance/agreements/1/additions?pageSize=1000
  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:

"customFields": [ { "id": 2, "caption": "Subscription ID", "type": "Text", "entryMethod": "EntryField", "numberOfDecimals": 0 }, { "id": 3, "caption": "Subscription Name", "type": "Text", "entryMethod": "EntryField", "numberOfDecimals": 0 } ]

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.

     

Creating Custom Fields in BSS

The custom fields created in this section will contain the account agreement ID. Since each ConnectWise agreement is for recurring services with the same renewal terms (e.g. monthly or annual services), you will need to create a custom field for each billing cycle (i.e. unit) your services support.

  1. Then, in your BSS: Go to SetupOfficeAccountsCustom Fields

     

  2. Create the custom field(s) with the name of the unit. The Field Type must be Simple Value for both.

Please ensure that the name of the custom fields match the name of the subscription units exactly. The name of the unit can be found in the Pricing section of the product view, as in the figure below:

Linking Agreements to Accounts

For each new account you need to:

  • Create a ConnectWise agreement per billing cycle

  • Link the BSS Account with the agreements you created in ConnectiWise by settings the agreement Ids in the corresponding custom fields.

The steps below must then be repeated for every account:

  1. Create an agreement for the account you want to synchronize. Create one Agreement per billing cycle for every account. For instance, for an account which has a monthly and an annual subscription, 2 agreements must be created.

     

  2. Make the following GET request with your ConnectWise Client ID and authentication credentials. Please note that the pageSize parameter at the end of the request is for pagination purposes and helps avoid bulky responses which may crash the application:

    https://staging.connectwisedev.com/v4_6_release/apis/3.0/finance/agreements?pageSize=1000
  3. The response contains the id of the agreement(s). Use the search function to find agreements by name.

  4. Go to each account for which you have created agreements, and enter the ID of the agreement into the custom field created before. This step links your account with the agreement you created in Connectwise. From now on, all annual subscriptions for example will be created as additions to the ConnectWise agreement.

     

     

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/4664380