Extension Setup Manifest
Overview of the Extension Setup Manifest
Extensions in Adaptive Catalog are defined via a setup manifest in JSON format. The following is a truncated example for the ConnectWise Manage Product Export extension.
{
"id" : "export-cwmanage-catalog",
"category" : "export",
"maintainer": "Adaptive Catalog",
"name" : "ConnectWise Manage Catalog Export",
"description" : "Send an Adaptive Catalog product to your ConnectWise Manage system.",
"documentation": "URL",
"ready" : true,
"image" : "URL",
"url" : "URL",
"encryption" : "URL",
"validateUrl" : "URL",
"link": "product",
"linkType": "ConnectWiseManageProduct",
"additionalData" : [
{
"field" : "url",
"fieldType" : "static",
"description" : "URL",
"protected" : false
},
{
"field" : "companyId",
"fieldType" : "static",
"description" : "Company ID",
"protected" : false
},
{
"field" : "privateKey",
"fieldType" : "static",
"description" : "Private Key",
"protected" : true
},
{
"field" : "publicKey",
"fieldType" : "static",
"description" : "Public Key",
"protected" : true
},
{
"field" : "category",
"fieldType" : "item",
"description" : "Product Category",
"protected" : false,
"adHocOnlyField": true,
"optionsUrl" : "URL"
},
{
"field" : "subcategory",
"fieldType" : "item",
"description" : "Product Sub-Category",
"protected" : false,
"optionsUrl" : "URL",
"adHocOnlyField": true,
"optionsFields" : [
{
"type" : "extension",
"field" : "category"
}
]
}
]
}
An overview of the allowed fields are as follows:
Field | Required | Description |
---|---|---|
id | true | A unique identifier for your extension. The recommended format is {extensionType}-{targetProduct}-{targetResource} |
category | true | The extension type. Valid options are export , webhook , recommendation , realtime , and embed |
maintainer | true | Your company name |
name | true | A friendly name for your extension |
description | true | A brief description of what your extension does |
documentation | true | A URL to public facing documentation for setup & usage of your extension |
ready | true | A boolean indicating if the extension is ready to be published |
image | true | A URL to a public facing image for your extension. The image should be 512x512 pixels and either PNG or JPG |
url | true | The URL that will be called when your extension is run |
encryption | true | The URL to get your public PGP encryption key |
validateUrl | false | A URL to validate credentials & settings. Used when installing the extension. |
installCallUrl | false | A URL that will be called with all set static fields when the user installs an extension. Can be used for setting up anything on your extension, such as embedded iframes. |
uninstallCallUrl | false | A URL that will be called with all set static fields when the user uninstalls an extension. Should be used for cleaning up one time setup data. Is only called when the extension is uninstalled, not when it is disabled. |
additionalData | true | Any additional fields set during setup or when running the extension. Can be an empty array |
linkedItemType | false | The linkType that will be looked up for existing links. If found, the items will be passed as a reference. For more information see Untitled |
link | false | Should be set to product or workspace if provided. Establishes a link from products or workspaces to your external reference IDs. For more information, see Untitled |
linkType | false | Required if link is provided. A unique value for the reference between an Adaptive Catalog product and your extension. For more information see Untitled. |
allowAdHocItems | false | If set to true, all items in the workspace will be passed to an export extension. If set to false, only items that have a previously established link will be passed. |
allowPrice | false | A boolean that determines if the user is shown a price field which is passed to your extension. |
The Additional Data fields are as follows
Field | Required | Description |
---|---|---|
field | true | A unique field name that will be passed in the dictionary of additional data when running the extension |
fieldType | true | The field type. See the field type table for a list of field types. |
description | true | The friendly name for the field |
protected | true | Determines if the field should be presented as a password field and encrypted using your PGP encryption key. Generally only set to true on static fields. |
adHocOnlyField | false | Determines if a item level field should be presented only for items that do not have established links. |
searchable | false | If set to true, then the dropdown will allow users to text search on the options which are then passed to the optionsUrl . |
optionsUrl | false | If provided, then the field will be shown as a dropdown to the user and will query this endpoint for options |
optionsField | false | For fields with dropdowns, the options field can specify any field dependencies (such as subcategory depending on category). The type can be extension, product, or workspace and the field should be the field name. These will be passed when calling the optionsUrl |
Field Types
Field Type | Description |
---|---|
static | Static fields are set during extension installation and can be used for credentials or setup only fields |
user | User fields are data fields set when running the extension |
item | Item fields are data fields set per item on a workspace when running the extension |
file | File fields allow users to upload files that are then sent as a URL to your extension. Please note: files uploaded to Adaptive Catalog extensions are meant to be temporary and are only stored for up to 1 hour. Best practice is to only store the files as long as you need them to run the extension and then delete them to ensure the security and privacy of your users. |