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 Examples
  • As an AV product vendor, you want to share the status of the AV for each machine, whether the machine is infected or not, when was the last scan performed on a machine, etc.
  • Similarly, as a Backup product vendor, I want to share the status of backups for each machine, the number of backups, size of backup, etc.
How to Push Data

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, which 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