Step by Step Guide to Building a ConnectWise Manage API Integration in Ruby

Introduction

Hey there, fellow developer! Ready to dive into the world of ConnectWise Manage API integration? You're in for a treat. In this guide, we'll walk through building a robust integration using Ruby. The ConnectWise Manage API is a powerful tool that'll let you tap into a wealth of business management data. Let's get cracking!

Prerequisites

Before we jump in, make sure you've got:

• A Ruby environment set up (I'm assuming you're good to go here)
• ConnectWise Manage API credentials (if you don't have these, reach out to your ConnectWise admin)

Setting Up the Project

First things first, let's get our project off the ground:

mkdir connectwise_integration
cd connectwise_integration
bundle init

Now, open up your Gemfile and add these gems:

gem 'httparty'
gem 'dotenv'

Run bundle install, and we're ready to rock!

Authentication

ConnectWise uses API key authentication. Let's set that up:

require 'httparty'
require 'dotenv/load'

class ConnectWiseClient
  include HTTParty
  base_uri 'https://api-na.myconnectwise.net/v4_6_release/apis/3.0'

  def initialize
    @options = {
      headers: {
        'Authorization' => "Basic #{ENV['CW_AUTH_KEY']}",
        'clientId' => ENV['CW_CLIENT_ID'],
        'Content-Type' => 'application/json'
      }
    }
  end
end

Don't forget to create a .env file with your CW_AUTH_KEY and CW_CLIENT_ID!

Making API Requests

Now for the fun part - let's make some requests:

def get_companies
  self.class.get('/company/companies', @options)
end

def create_ticket(params)
  self.class.post('/service/tickets', @options.merge(body: params.to_json))
end

Working with ConnectWise Manage Resources

Here's a quick example of how to work with companies and tickets:

client = ConnectWiseClient.new

# Get all companies
companies = client.get_companies

# Create a ticket
new_ticket = client.create_ticket({
  summary: 'New integration ticket',
  board: { id: 1 },
  company: { id: companies.first['id'] }
})

Error Handling and Rate Limiting

Always be prepared for things to go wrong:

def make_request
  retries = 0
  begin
    yield
  rescue => e
    retries += 1
    if retries < 3
      sleep(2 ** retries)
      retry
    else
      raise e
    end
  end
end

Data Parsing and Manipulation

ConnectWise returns JSON. Let's parse it:

require 'json'

response = make_request { get_companies }
companies = JSON.parse(response.body)

Building a Simple CLI Tool

Let's wrap this up in a simple CLI:

#!/usr/bin/env ruby

require_relative 'connectwise_client'

client = ConnectWiseClient.new

case ARGV[0]
when 'companies'
  puts client.get_companies
when 'create_ticket'
  puts client.create_ticket(summary: ARGV[1])
else
  puts "Unknown command"
end

Testing the Integration

Don't forget to test! Here's a simple RSpec example:

RSpec.describe ConnectWiseClient do
  it 'fetches companies' do
    VCR.use_cassette('companies') do
      client = ConnectWiseClient.new
      response = client.get_companies
      expect(response.code).to eq(200)
    end
  end
end

Best Practices and Optimization

Remember to cache when you can and be mindful of API rate limits. Your future self (and ConnectWise) will thank you!

Conclusion

And there you have it! You've just built a ConnectWise Manage API integration in Ruby. From here, sky's the limit. You could expand this to cover more endpoints, build a full-fledged Rails app, or even create a gem for others to use.

Keep coding, keep learning, and most importantly, have fun with it!