Skip to main content
Developer Network

Connection and Callbacks

Connection and Callback

This is the section in the vendor development portal that will be used by vendors to create the configuration and fields needed for accepting credentials or other parameters needed for establishing communication between the ConnectWise platform and vendor product platform and also specify callbacks needed for different functions for the Integration to work. To access and configure the "Connection and callbacks", log in to the sandbox and switch to the development portal, thereafter navigate to the "Connection and callbacks" section from the left menu navigation.

How to access the "Connection and Callback" section in the vendor development portal:

  1. Log in to the Sandbox:
    1.png
  2. Switch to the Development portal:
    2.png

  3. Navigate to the Connection and callbacks section:
    3.png

Connection

This section is used to establish a connection between the ConnectWise platform and the vendor's product platform. This connection mechanism will then be used by the Connectwise platform to communicate with different APIs and Services in the vendor's product platform that would be needed for the integration to work. The first configuration that would be needed from the Vendor would be to create a form for partners in the ITSupport Portal that accepts the partner's credentials that would be needed to communicate with the vendor's product platform (like username and password or some API credentials or secret key's etc.). Vendors do not have to create a dedicated UI for this, vendors have to just specify the fields needed for their product for accepting credentials from partners in the form of JSON schema in the vendor development portal (screenshot shown above). Based on this schema, UI will be automatically created in the ITSupport portal. The following screen shows the partners' view in the ITSupport portal. The highlighted section is where partners will specify the third-party product credentials, In this example, we have two fields - Username and Password, for your product you can create as many fields as you want. We currently support 4 different types of fields:

  • Text box
  • Password type text box
  • Check box
  • Dropdown/selection box
  • Additionally, you can add titles and labels if needed

connect.png

Callback

Every product integration would require the execution of specific actions that are defined and controlled by the vendor's product. Typical examples are actions where connection to Vendor Public APIs is required to obtain some specific data or make some configuration change by calling services hosted in the vendor's product platform/cloud. As part of the Integration workflow, we would need Integration vendors to have a special service that exposes secured REST API endpoints that accepts specific requests from the ConnectWise platform for different types of specific actions (these specific actions are described later in this document). Currently, we need 4 different types of actions:

  • Test Connection - this will be used to test the connection between the Connectwise platform and the vendor's product platform
  • Retrieve Topology - this will be used to retrieve topology (sites/companies/locations) as defined by partners in the vendor's product so that partners can then perform site to site mapping in the ITSupport portal
  • Retrieve Installation parameters/token - this will be used to retrieve license or token or any other parameter needed to successfully deploy and install vendor's product
  • Create New Site/Company/Location - this will be used to request new site/location/company creation in the vendor's product
API Contracts

Vendor Integration service which exposes HTTPS interface for the above callback actions should conform to the following rules:

  1. Should have a valid TLS v.1.2 or higher certificate. It can be signed with a trusted authority. If not, then this certificate should be defined on the "Connection&Callbacks" page on the Vendors Development Portal
  2. API endpoint should support two request methods:
    • HTTP GET: to be used as a health check. Should always respond with HTTP 200 code
    • HTTP POST: actual implementation method, which will accept "application/JSON" payload with information about action that should be executed
  3. Request Payload - Request payload sent to the POST method consists of the following mandatory fields
    • "action": "action-name", where action-name will be the name of action (test-connection, retrieve-topology, retrieve-installation-token, etc.

    • "apiCredentials": { ... }, will be a JSON object that contains credentials needed to establish connection with the Vendor solution. Content of the JSON will depend on the form definitions data defined in the "Connection & Callback" section on the Vendor Development Portal.

    • "parameters": { ... }  will be a JSON object that contains action specific configuration parameters, like target, openAPIClientID, etc. Depends on action type and will be omitted for those actions that don't require extra parameters, i.e. test-connection.

  4. Response - Response payload depends on the actual action type. Some actions don't need any response, while others need a specific contract response. We also need HTTP response codes with the response as follows:
    • HTTP 200 OK - If request processing is successful. The response body should include a specific payload required for that action type
    • HTTP 401 Unauthorised - to be returned in case if apiCredentials passed in the request payload are not valid
    • HTTP 400 Bad request - to be returned in case if request payload sent doesn't contain required data or the payload is invalid;
    • HTTP 500 Internal Server Error - to be returned in case of other error that doesn't fall into the above classifications. Response payload should include details of the error
Actions and Request-Response Contracts

As described in the section above, the integration currently requires 4 different types of action callbacks:

Callback Action Request Response
Test Connection - this will be used to test the connection between the Connectwise platform and the vendor's product platform
{
    "apiCredentials": {
        ...                 // variadic form data
    },
    "action": "test-connection"
}
Example:
{
    "apiCredentials": {
        "username": "admin",
        "password": "some_secret_password"
    },
    "action": "test-connection"
}

Example:
{
    "apiCredentials": {
        "username": "admin",
        "password": "some_secret_password"
    },
    "action": "test-connection"
}

HTTP 200 response code in case of success;

HTTP 401 response code in case if authentication fails.

Retrieve Topology - this will be used to retrieve topology (sites/companies/locations) as defined by partners in the vendor's product so that partners can then perform site to site mapping in the ITSupport portal
{
    "apiCredentials": {
        ...                 // variadic form data
    },
    "action": "retrieve-topology"
}

Example:
{
    "apiCredentials": {
        "username": "admin",
        "password": "some_secret_password"
    },
    "action": "retrieve-topology"
}

HTTP 200 response code in case of success and response json payload that contains list of vendor topology objects as follows

[ {"id": "topology item identifier", "name": "topology item name"}, {...}, ... ]

Example:
[
   {
      "id": "e883eb99-cbac-48b3-97c3-5158b81bc069",
      "name": "test-site-1"
   },
   {
      "id": "0890d427-fc5a-4c14-9344-0e6534f6ccc4",
      "name": "test-site-2"
   }
]

HTTP 401 response code in case if authentication fails

Retrieve Installation parameters/token - this will be used to retrieve license or token or any other parameter needed to successfully deploy and install vendor's product
{
    "apiCredentials": {
        ...
    },
    "action": "retrieve-installation-token",
    "parameters": {
        "openapiClientID": "openAPI Client Identifier",
        "target": {
            "clientId": "public client identifier",
            "siteId": "public site identifier",
            "endpointId": "public endpoint identifier"
        },
        "mappingDetails": {
            "targetId": "mapped resource identifier"
        }
    }
}

Example:
{
    "apiCredentials": {
        "username": "admin",
        "password": "some_secret_password"
    },
    "action": "retrieve-installation-token",
    "parameters": {
        "openapiClientID": "f9bf78b9a18ce6d46a0cd2b0b86df9da",
        "target": {
            "clientId": "Drmhze6EPcv0",
            "siteId": "Drmhze6EPcv0",
            "endpointId": "d94f51c2-9f10-4dd1-be33-71116a693a64"
        },
        "mappingDetails": {
            "targetId": "633d5c58-20df-4ca5-a6f3-3603bc7fe438"
        }
    }
}

HTTP 200 response code in case of success and response payload of "plain/text" type that contains installation token/license

HTTP 401 response code in case if authentication fails.

Create New Site/Company/Location - this will be used to request new site/location/company creation in the vendor's product
{
    "apiCredentials": {
        ...
    },
    "action": "create-new-site",
    "parameters": {
        "name": "site name",
        "description": "some site description"
    }
}

Example:
{
    "apiCredentials": {
        "username": "admin",
        "password": "some_secret_password"
    },
    "action": "create-new-site",
    "parameters": {
        "name": "Arizona Site",
        "description": "Site at Arizona"
    }
}

HTTP 200 response code in case of success and response JSON payload that contains the identifier of the newly created site:

{"id": "site ID"}

Example:
{
  "id": "e883eb99-cbac-48b3-97c3-5158b81bc069"
}

HTTP 401 response code in case if authentication fails.

HTTP 409 response code in case if a site already existed.