Cozy Connector Tutorial


Open Source Your Knowledge, Become a Contributor

Technology knowledge has to be shared and made accessible for free. Join the movement.

Create Content
Previous: Hello connector!

Save the cats!

Now lets do something better for the world, we will save the best kitten in the world... At least kitten pictures! This connector will fetch the 10 best kitten pictures directly in the current directory.

Save the cats!
'use strict'
// This is a default simple connector made to show you some common libs which can be used
// This connector fetches some cat images from the qwant api (which is more open than the google one)
const {BaseKonnector, saveFiles, request} = require('cozy-konnector-libs')
const rq = request()
module.exports = new BaseKonnector(fields => {
return rq({
uri: '',
qs: {
q: 'chatons', // change the search keyword if you want
count: 10
.then(body => {
let result = []
if (body && && && {
result =, index) => ({ fileurl: }))
return result
.then(entries => saveFiles(entries, fields.folderPath))
// saves the informations about resulting images to display it after
.then(result => {
require('fs').writeFileSync('result.js', `window.result = ${JSON.stringify(result)}`)
return result
// displays the list of results in the page
.then(result => console.log('TECHIO> open -s /project/target index.html'))

Try to change the code to save some other kind of pictures.

saveFiles ( files[], folderPath, options? )

The goal of this function is to save the given files in the given folder via the Cozy API.

  • files is an array of { fileurl, filename } :

    • fileurl: The url of the file. This attribute is mandatory or this item will be ignored
    • filename : The file name of the item written on disk. This attribute is optional and as default value, the file name will be "smartly" guessed by the function. Use this attribute if the guess is not smart enough for you.
  • folderPath (string) is relative to the main path given by the cozy-collect application to the connector. If the connector is run in standalone mode, the main path is the path of the connector.

  • options (object) is optional. Possible options :

    • timeout (timestamp) can be used if your connector needs to fetch a lot of files and if the the stack does not give enough time to your connector to fetch it all. It could happen that the connector is stopped right in the middle of the download of the file and the file will be broken. With the timeout option, the saveFiles function will check if the timeout has passed right after downloading each file and then will be sure to be stopped cleanly if the timeout is not too long. And since it is really fast to check that a file has already been downloaded, on the next run of the connector, it will be able to download some more files, and so on. If you want the timeout to be in 10s, do + 10*1000. You can try it in the previous code.

A final exercise

You can set the search keyword as a parameter to the connector. Just set it as "keyword" in the konnector-dev-config.json file, fetch it and use it in the connector. The connector will be ready to be added to the list of cozy connectors as "Qwant Images" for example!

Open Source Your Knowledge: become a Contributor and help others learn. Create New Content