Skip to main content

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 Catalog 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:

FieldRequiredDescription
idtrueA unique identifier for your extension. The recommended format is {extensionType}-{targetProduct}-{targetResource}
categorytrueThe extension type. Valid options are export, webhook, recommendation, realtime, and embed
maintainertrueYour company name
nametrueA friendly name for your extension
descriptiontrueA brief description of what your extension does
documentationtrueA URL to public facing documentation for setup & usage of your extension
readytrueA boolean indicating if the extension is ready to be published
imagetrueA URL to a public facing image for your extension. The image should be 512x512 pixels and either PNG or JPG
urltrueThe URL that will be called when your extension is run
encryptiontrueThe URL to get your public PGP encryption key
validateUrlfalseA URL to validate credentials & settings. Used when installing the extension.
installCallUrlfalseA 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.
uninstallCallUrlfalseA 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.
additionalDatatrueAny additional fields set during setup or when running the extension. Can be an empty array
linkedItemTypefalseThe linkType that will be looked up for existing links. If found, the items will be passed as a reference. For more information see Untitled
linkfalseShould 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
linkTypefalseRequired if link is provided. A unique value for the reference between an Adaptive Catalog product and your extension. For more information see Untitled.
allowAdHocItemsfalseIf 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.
allowPricefalseA boolean that determines if the user is shown a price field which is passed to your extension.

The Additional Data fields are as follows

FieldRequiredDescription
fieldtrueA unique field name that will be passed in the dictionary of additional data when running the extension
fieldTypetrueThe field type. See the field type table for a list of field types.
descriptiontrueThe friendly name for the field
protectedtrueDetermines 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.
adHocOnlyFieldfalseDetermines if a item level field should be presented only for items that do not have established links.
searchablefalseIf set to true, then the dropdown will allow users to text search on the options which are then passed to the optionsUrl.
optionsUrlfalseIf provided, then the field will be shown as a dropdown to the user and will query this endpoint for options
optionsFieldfalseFor 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 TypeDescription
staticStatic fields are set during extension installation and can be used for credentials or setup only fields
userUser fields are data fields set when running the extension
itemItem fields are data fields set per item on a workspace when running the extension
fileFile 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.