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.
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)
- 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
- 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
- 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
- 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.
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.
Step 1: Create Field from the Vendor Development Portal
Step 2: Save and deploy the package to Sandbox
Step 3: Push data via the Extended Attributes APIs. Documented here: https://developer.connectwise.com/Products/Command/REST/V1
Step 4: Once tested on Sandbox, the package can be deployed to Production for partners.
Following steps must be performed to create the data fields:
- The vendor should first create the fields in the Vendor development portal. Log in to the Sandbox and switch to the Vendor Development portal, navigate to the "Data Fields" from the left menu. You will see the following screens:
- Once on the Data Fields page, click on the + icon on the top right side to add a new field definition. A new modal window will open up for field creation. You will see the following screen:
- Following parameters are needed to create a new field (same is also applicable for editing a field)
- Name - Mandatory Field, specify the name that you like to give to a data field.
- Hidden - You can make a field hidden on UI via this "Hidden" toggle. If toggle is On, field will not be displayed in the UI
- Entity type - Mandatory Field. You can create a field at the Partner, Client, Site, or Endpoint level. Select the required option from the dropdown.
- Attribute type - Mandatory Field. This is for selecting the type of field. Select the required option from the dropdown. We support 5 types of fields:
- Select (Multiple selection box/dropdown)
- Default value - To specify default values for the field. These values are applied when explicit value is not assigned to any entity. Default value selection depends on attribute type and will be specific for each item:
- For "String' it will be single input. Also, there will be an additional field to specify a regular expression for validation.
- For "Boolean" you can specify toggle on or off
- For "Integer" you can specify a number
- For "Date" you can select a default date via a date-picker.
- For "Select" it will be a dropdown. Also, there will be one more additional field to specify dropdown items.
- Description - Mandatory field. Free text to describe the field
- UI options - section for specifying how a field should look in the UI for partners
- Display type - dropdown for defining the specific structure of value on UI.
- Default - no changes on UI, the field will be displayed as is
- Storage - applicable only for "Integer" type. Display value as storage (1 - 1b, 1024 - 1kb and etc).
- Link - applicable only for "String" type. Display value as a hyperlink on UI (value must be URL), Also there will be one more additional field for specifying the label for the hyperlink.
- Views - You can also specify where in the UI the data fields should be shown to the MSPs. To do this, you need to create a new View record by clicking on the + icon on the right-hand side within the View section:
- View - To select the location in the UI where the field should be displayed. We have two options Device Summary and Device Details (as shown above in the screenshots). Select the required location from the dropdown
- Order - To specify the order of the field in the table. It specifies the index of the column in the table. Accepted values between 0 and 99. Order of 1 indicates the first column for the field
- Crop factor - This is for the Device summary view, which can be used to specify the width of the column in the table (Number between [0.1, 5]).
- Display type - dropdown for defining the specific structure of value on UI.
- Once all the parameters are filled, click on "Create/Update"
- Create as many fields as you want
- Once all the fields are created, PUT API from the Extended Attributes APIs can be used to push data for each field at each endpoint at the Client/Site/Endpoint level