The ConnectWise Vendor Hosted API is a JavaScript script that allows hosting of ConnectWise in your own Web Applications via an IFrame. Your application can then make requests of the Client API such as opening a specific service ticket or refreshing the embedded instance.
In many cases the ConnectWise Vendor Hosted API will be used in conjunction with the ConnectWise API.
An example workflow would be:
The Client API consists of the ConnectWiseVendorHostedAPI_X.x.js JavaScript script file and a sample project .
The version of the ConnectWise Vendor Hosted API being used is appended to the JavaScript file name in the format of X.x. The ConnectWise Vendor Hosted API will maintain backwards capability within the same minor versions but might break compatibility with major version updates.
If the version of the ConnectWise Vendor Hosted API is incompatible with the embedded instance of ConnectWise an error will be returned when an api call is made.
Place an IFrame element in your web application with the src attribute set to the url of your ConnectWise instance. If wanted the url query parameter FullScreen can be set to true to have ConnectWise open with the left and top navigation hidden.
<iframe id='frameConnectWise' src='my.connectwise.com?fullscreen=true'></iframe>
Place a script element in your web application with the src attribute pointing to where you are hosting the ConnectWiseVendorHostedAPI.js file.
<script src='ConnectWiseVendorHostedAPI.js'></script>
In your JavaScript instantiate an instance of the ConnectWiseVendorHostedAPI. See the API specification below for further information on the constructor arguments for the ConnectWiseVendorHostedAPI module.
// instantiate connectWiseVendorHostedAPI
var connectWiseVendorHostedAPI = new ConnectWiseVendorHostedAPI(frameConnectWise,
'my.connectwise.com',
function(data) { // callback });
Now the ConnectWiseVendorHostedAPI module is ready to be sent requests.
connectWiseVendorHostedAPI.sendRequest({"action" : "open", "args" : { "screen" : "ticket", "id" : 1345}, function(data){ // callback });
Please note your web application must be hosted by a web server such as IIS or Apache. The ConnectWise Vendor Hosted API will not work directly off the hard drive.
Before requests can be made of the ConnectWiseVendorHostedAPI it must be instantiated.
You must set the hosting application’s Origin domain setting in the ConnectWise Vendor Hosted API set up table. You will need security access to access this table. Please contact your ConnectWise Administrator if you do not have access.
ConnectWiseVendorHostedAPI(IFrame ConnectWiseFrame,
String origin,
Function callback,
boolean debug)
ConnectWiseFrame - A reference to the IFrame hosting ConnectWise.
Origin - The domain of the ConnectWise instance. This is needed for security reasons when passing messages between domains. See (http://www.w3.org/TR/webmessaging/#web-messaging) for more information.
WARNING. If you do not set the Origin in your ConnectWise Client API Setup to your hosting application domain then the Client API will not work properly. See the ConnectWiseClientAPI Instantiation section above.
Callback - A function that will be invoked when ConnectWise has loaded. Once this callback has been called the embedded instance is ready for requests.
Debug - [Optional] if set to true, verbose information will be logged to the console to aid in debugging issues.
new ConnectWiseVendorHostedAPI(frameConnectWise, 'my.connectwise.com', function(data) { // callback body });
Most interactions with the ConnectWiseVendorHostedAPI will be by calling sendRequest. The sendRequest method has the following signature:
sendRequest(JSON object, Function callback)
JSON object - A JSON Object with at least an action and args parameter. The action parameter specifies which request is being made. The args parameter is a collection of any arguments needed for the request.
Function callback - A function that will be invoked when the request completes. The function is passed a JSON Object SendResponse. See the SendResponse section for further information on this object. The response might contain other data depending on the specific request.
sendRequest({"action" : "open", "args" :{ "screen" : "ticket", "id": 444} },
function(data) { console.debug(data.error); });
The Response JSON Data object passed to the callback consists of at least an error number. If the error number indicates that an error has happened, the Response will also contain an errors collection. Many Responses will also contain a ScreenObject.
The format of the response.error is as follows:
{"error":0, "screenObject":{"screen":"ticket", "id":1}}
{"error":1, "errors":[{"error":"Invalid message format"}]}
The ScreenObject will be returned in the callback response of certain requests. The ScreenObject consists of two properties, the screen and the id.
The Screen is a text enumeration of the below possible values:
The ID is a number representing the record id of the specific screen.
{ "screen" : "ticket", "id" : 123445}
The Refresh Request will refresh the current screen if the screen and ID match. The user might have navigated to a different screen in which case refresh will be ignored.
JSON Object
screenObject.refresh(callback(data));
The Open Request will navigate the embedded ConnectWise instance to the indicated screen with the indicated ID.
JSON Request
sendRequest('{"action" : "open", "args" : { "screen" : "ticket", "id": 444} }, function(data) { ...})
The setEventListener is used to register a callback for when a specific screen event occurs. It takes in the ScreenObject to set up the event listener for and a callback that is triggered when the event occurs for that *screen8 and id. There can only be one event listener active at a time.
sendRequest({"action","setEventListener", "args" : {"screenObject", screenObject}, function(data) {
data.screenEvent
}
);