Skip to main content
Developer Network

Vendor Defined Data Fields

Vendor Defined Data Fields

These API endpoints allow integration vendors to create and share data for their products into the ConnectWise Command Platform. The data can either be shown in the Devices section of the ITSupport Portal or it can be used to store technical/temporary data/information which can later be used for automation purposes.

Use Case

For partners to manage and monitor any third-party product, it is important to keep an eye on the health status of devices with respect to the specific third-party product. This health status can be shown to the MSPs by providing certain key data points about the third-party product. Vendor Defined data fields are the mechanism via which third-party products can inject such key data points of their product into the ITSupport portal for MSPs monitoring needs.

Some common examples for this are:

  • From an Endpoint Protection/AV product perspective, it is important for products to provide data points like:
    • What is the endpoint protection status of devices?
    • When was the device last scanned?
    • Are there any threats to the device?
    • Is the endpoint protection software up to date?
  • From a Backup and Disaster recovery product perspective, it is important for products to provide data points like:
    • What is the backup status?
    • What is the protection plan applied to the machine?
    • When was the last successful backup?

Answers to such questions can be provided by adding one or more data points for each of the above. These data points can be added in the ITSupport portal using the concept of Vendor defined data fields. Vendor-defined data fields are nothing but a set of additional data fields for devices that can be introduced and updated from an external source (i.e a third-party product).

Vendors can add any number of data fields for each device. When fields are added by Vendors they are automatically visible in the ITSupport portal UI if they are defined as UI visible. The following screenshots show where these fields are shown in the ITSupport portal.

  • This is the main device summary page in the ITSupport portal, giving MSPs a summary of all the devices they manage. Data for Integrations (Vendor Defined Fields for a specific third-party product can be accessed by clicking on the Integrations selection option (Highlighted with RED in the above screenshot)
    devSummary.png
  • Clicking on the selection option will show MSPs list of all the third-party product integrations they have enabled and vendor-defined data fields for that product. In this screenshot, Easy Automation (an example third-party product) is the only Integration product that MSP has enabled. Hence, only Easy Automation appears in the selection list. If there are more products, all would appear as a list here
    MSPList.png
  • Clicking on Easy Automation will open up the summary page which contains a list of all the devices along with data of that specific product. Companyfield11 and Companyfield are the example Vendor Defined Fields for this integration. Fields and values for these fields can be created and updated using the APIs. This screenshot shows the summarized view which should ideally be utilized by Vendors to show the most important data for their product
    devList.png
  • In addition, there is a detailed view which Vendors can use to show other additional data outside of the summary view. This additional data is also visible in the UI in the device detail view which is accessible by clicking on an individual device. The screenshot below shows the device detail view of a specific device. Click the Integrations option in the menu (highlighted RED) to access the additional Vendor defined data fields for a specific device
    sumView.png
  • Similar to the summary view, here too partners would be provided with a selection box to view the data for a specific integration. Since Easy Automation is the only third-party product in our example, only that product is seen in the UI, and for that product, Companyfield is the vendor-defined data field that is defined such that it is visible in the device details view. 
    intView.png

NOTE: It is the vendor's choice to define which fields should be visible on summary view or detail view.

How To Use Vendor Defined Data Fields

We have introduced APIs via which vendors can create and manage Vendor defined fields. These APIs allow product vendors to push monitoring data of their products into the ConnectWise Command Platform. The data can either be shown in the ITSupport Portal UI or can be used to store technical/temporary data/information which can later be used for automation purposes.

The following steps must be performed to push data:

  1. The vendor should first define a schema for the fields, this is done via a POST API.
    • Currently, we support 5 types of data fields
      • String
      • Boolean
      • Integer
      • Datetime
      • Enum
  2. Once the schema is defined, a PUT can be used to push data for each endpoint at the Client, Site, or Endpoint level.
  3. Once data is pushed for each endpoint, vendors will have to define whether the field should be UI visible and where it should be displayed in the UI, if so. This needs to be specified while creating a schema for the fields.
    • NOTE: It is recommended to create up to 6 data fields for the Devices Summary page. Other fields can be created and added to the Device Details section. The maximum number of fields that can be created is 200 (which can be extended on request).
  4. Once field definitions are created, a GET can be performed to retrieve a definitions schema with all entity types or by a specific type. To delete definitions, create a schema with an empty list in the request body.
Example

POST to Create Data Fields Schema

{
"entityType": "endpoint",
"name": "backup_plan",
"description": "some description",
"attributeType": "enum",
"validationOptions": {
"enum": [
"not_specified",
"premium",
"elite"
] 
}, 
"defaultValue": "not_specified",
"localizations": [
"description": "dropdown of the attribute",
"language": "en_US",
"name": "AD"
]
"uiOptions": {
"display_type": "storage",
"views": [
{
"columnCropFactor": 1,
"order": 1,
"view": "portal.device_details_view"
}
 ]
 },
}
Configuration
id
  • A unique identifier of the field can be used in the future as a reference to it.
  • Represented in form of UUID and can be environment agnostic.
  • In cases where it is not specified during schema creation, it will be automatically generated.
entityType controls field mapping to specific entity type (partner/client/site/endpoint)
attributeType defines type of the field (string/boolean/integer/datetime/enum)
name defines the name of the fields
description defines the description of the fields
defaultValue optionally defines the default value for the fields
validationOptions
  • Controls type-specific validations
  • For string type, it's possible to specify a regular expression pattern, which will be used to check if the value is inserted for such field conforms to the defined pattern. Specified using the syntax mentioned here: https://github.com/google/re2/wiki/Syntax
  • For enum fields, validation options should contain all possible values for that enum
"validationOptions": { "regex": ".*" }
uiOptions

controls UI-specific behavior. If this configuration is not specified, the field will not be displayed in the UI. If specified location and behavior must be mentioned

  • “View” argument specifies the location. There are two options portal.device_details_view and portal.device_summary_view. More UI options will be added later
  • The column order can be controlled using the “order” parameter. Use numbers to specify an order, 1 means first, 2 means second. If two fields have the same order, they would be sorted by field name
  • Column size can be controlled using the “columnCropFactor” parameter. Use numeric multiplier to align the size of the column, where 1 defines to use default calculated size, 1.5 is to have default size to be extended on 50%, and so on
  • The field can be configured to be displayed in a specific manner to provide a better UX experience to partners. For example, if the field contains a URL, you can specify the “display_type” parameter as a link to show this as a URL in the portal. If the field contains the size of storage, specify “display_type” as storage, this will automatically convert the number to KB, MB, or GB