Table of contents

Konnectors doctype

The io.cozy.konnectors doctype is used to store installed konnectors.

Konnectors are autonomous applications ran on the stack to connect to external services or API.

When installing a konnector, the Cozy stack creates a new io.cozy.konnector document from the fields in the manifest.konnector.

io.cozy.konnectors are used by Cozy-Store to install and uninstall konnectors, and by Cozy-Home to manage accounts for konnectors

Attributes

Retrieved from manifest.konnector

The available attributes in a io.cozy.konnectors document are :

Field Description
aggregator Object containing aggregator data. Typically { accountId: 'aggregator-service' }.
categories array of categories for your apps (see authorized categories), it will be ['others'] by default if empty
clientSide Boolean to specify if the konnector should be run on the client or not
data_types (konnector specific) Array of the data type the konnector will manage
developer name and url for the developer
editor the editor’s name to display on the cozy-bar (REQUIRED)
features (konnector specific) Array of features added in the konnector from the list below.
fields (konnector specific) JSON object describing the fields need by the konnector (except folder path). Used to generate a form. See below
folders (konnector specific) A list of folders required by the konnector to store files according to datatype (see the specific documentation below)
frequency (konnector specific) A human readable value between monthly, weekly, daily, indicating the interval of time between two runs of the konnector. Default: weekly.
icon path to the icon for the home (path in the build)
intents (application specific) a list of intents provided by this app (see cozy-stack intents doc for more details)
langs Languages available in your app (can be different from locales)
language (konnector specific) the konnector development language used (ex: node)
license the SPDX license identifier
locales an object with language slug as property, each name property is an object of localized informations (see the second part below)
manifest_version The current manifest version used. This is a versioning for the manifest and allow better retrocompatiblity when processing app manifest
messages (konnector specific) Array of message identifiers, which can be used by application to display information at known areas. See example below.
mobile (application specific) JSON object containing information about app’s mobile version (see cozy-stack routes doc for more details)
name the name to display on the home (REQUIRED)
name_prefix the prefix to display with the name
oauth (konnector specific) JSON object containing oAuth information, like scope. If a manifest provides an oauth property, it is considered as an OAuth konnector. Note: scope can be a string or an array. If it is an array, its values will be joined with a space. A false or null value in scope will remove any scope parameter in the request sent to the oauth provider.
parameters (konnector specific) Additional parameters which should be passed to the konnector. Used for example for bank konnectors to pass a bankId parameter.
partnership an object to provide informations (to display in the Store for example) about a partnership related to the application (icon description, name and domain). It can also be used to trigger alternative konnector connection policies for some vendors (see the budget-insight konnector policy in cozy-harvest).
permissions a map of permissions needed by the app (see see cozy-stack permissions doc for more details)
platforms (application specific) List of objects for platform native applications. For now there are only two properties: type (i.e. 'ios' or 'linux') and the optional url to reach this application page.
qualification_labels (konnector specific) Array of one or more labels from the Cozy Client’s qualifications list to associate with the files the konnector will receive from the website.
routes (application specific) a map of routes for the app (see cozy-stack routes doc for more details) (REQUIRED)
screenshots an array of paths to the screenshots of the application (paths in the build)
services (application specific) a map of the services associated with the app (see cozy-stack services doc for more details)
slug the default slug that should never change (alpha-numeric lowercase) (REQUIRED)
source where the files of the app can be downloaded (by default it will look for the branch build)
terms an object defining properties for terms that need to be displayed/accepted by the user when installing the application (more-info-below)
time_interval (konnector specific) By defaults, konnector triggers are scheduled randomly between 00:00 AM and 05:00 AM. Those two values can be overwritten thanks to this property, by passing an array containing two values: first is the interval start hour, second is the interval end hour. Example: [15, 21] will randomly schedule the konnector trigger between 15:00 (03:00 PM) and 21:00 (09:00 PM). The time zone used is GMT.
type type of application (konnector or webapp) (REQUIRED)
version the current version number (REQUIRED)
vendor_link (konnector specific) URL to editor or service website

Translated manifest fields

Here are the properties that you can override using locales (we recommand to automatically build these properties according to your locales files if you’re using a translating tool like transifex):

{
  "fields": {
    "email": {
      "type": "email"
    }
  },
  "locales": {
    "en": {
      "short_description": "Collect your Orange's bills",
      "fields": {
        "email": {
          "label": "Identifier (your email)"
        }
      }
    },
    "fr": {
      "short_description": "Récupère vos factures Orange",
      "fields": {
        "email": {
          "label": "Identifiant (votre adresse mail)"
        }
      }
    }
  }
}

Available manifest’s features list :

Other Attributes

Attribute Role
state Store the installation state of the konnector. Value can be AVAILABLE, INSTALLING, UPGRADING, UNINSTALLING, INSTALLED, READY

Example

{
  "version": "1.0.0",
  "name": "debug",
  "type": "konnector",
  "language": "node",
  "icon": "icon.svg",
  "slug": "debug",
  "source": "git@github.com:konnectors/debug.git",
  "editor": "Cozy",
  "vendor_link": "",
  "categories": [""],
  "fields": {
    "login": {
      "type": "text"
    },
    "password": {
      "type": "password"
    }
  },
  "folders": [{"defaultDir": "$administrative/$konnector/$account"}],
  "data_types": [
    "bill"
  ],
  "screenshots": [],
  "permissions": {
    "carbon_copy": {
      "type": "io.cozy.certified.carbon_copy"
    },
    "bank operations": {
      "type": "io.cozy.bank.operations"
    },
    "bills": {
      "type": "io.cozy.bills"
    },
    "files": {
      "type": "io.cozy.files"
    },
    "accounts": {
      "type": "io.cozy.accounts"
    }
  },
  "developer": {
    "name": "Cozy Cloud",
    "url": "https://cozy.io"
  },
  "langs": ["fr", "en"],
  "locales": {
    "fr": {
      "short_description": "",
      "long_description": "",
      "permissions": {
        "carboncopy": {
          "description": "Utilisé pour certifier que vos fichiers sont copie conforme avec les documents d'origine"
        },
        "bank operations": {
          "description": "Utilisé pour relier les factures à des operations bancaires"
        },
        "bills": {
          "description": "Utilisé pour sauver les données des factures"
        },
        "files": {
          "description": "Utilisé pour sauvegarder les factures"
        },
        "accounts": {
          "description": "Utilisé pour obtenir les données du compte"
        }
      }
    },
    "en": {
      "short_description": "Fetch your personnal documents.",
      "long_description": "Fetch the list of bills and personnal documents from your Luko account.",
      "permissions": {
        "carboncopy": {
          "description": "Use to certify your files are the exact copy of the originals"
        },
        "bank operations": {
          "description": "Required to link bank operations to bills"
        },
        "bills": {
          "description": "Required to save the bills data"
        },
        "files": {
          "description": "Required to save the bills"
        },
        "accounts": {
          "description": "Required to get the account's data"
        }
      }
    }
  },
  "qualification_labels": [
    ""
  ],
  "features": [
    "LOGIN_OK",
    "METADATA_DEDUP",
    "CARBON_COPY",
    "DOC_QUALIFICATION_V2",
    "SENTRY_V2"
  ],
  "banksTransactionRegExp": "\\bdebug\\b",
  "manifest_version": "2"
}