Developing a konnector

Without an accessible cozy-stack

If you just want to test this connector without any cozy available.

You first need an installed [nodejs] (LTS version is fine).

And the last version of yarn :

npm install --global yarn

Then just run :

yarn
yarn standalone

The requests to the cozy-stack will be stubbed using the [./fixture.json] file as source of data and when cozy-client is asked to create or update data, the data will be output to the console. The bills (or any file) will be saved in the . directory.

With the cozy-stack

If you do not want to have to install the konnector on a cozy v3 to test it, you can register the konnector as an OAuth application with the following commands :

yarn
yarn dev

This command will register your konnector as an OAuth application to the cozy-stack. By default, the cozy-stack is supposed to be located in http://cozy.tools:8080. If this is not your case, just update the COZY_URL field in [./konnector-dev-config.json].

After that, your konnector is running but should not work since you did not specify any credentials to the target service. You can do this also in [./konnector-dev-config.json] in the “fields” attribute.

Now run yarn dev one more time, it should be ok.

The files are saved in the root directory of your cozy by default.

How does the cozy-stack run the connector ?

The cozy-stack runs the connector in a nsjail container to be sure it does not affect the environment.

The connector is run by calling yarn start with the following envrionment variables :

{
  "data":{
    "attributes":{
      "arguments":{
        "account":"cf31eaef5d899404a7e8c3737c1c2d1f",
        "folder_to_save":"folderPathId",
        "slug":"mykonnector"
      }
    }
  }
}

The “account” field is the id of the record with doctype “io.cozy.accounts” which will be used as parameters for your konnector.

Build (without Travis)

To be able to run the connector, the cozy stack needs a connector which is built into only one file, without needing to install its dependencies, this will be a lot faster to install.

There is a command in package.json to help you to do that : yarn build

This command uses [webpack] to bundle all the code needed by your connector into one file.

This will generate an index.js file in the build directory and add all files the connector will need.

You can deploy this build by using the specific script : yarn deploy

This command will commit and push your build in the branch build fo your project.

And your konnector can now be installed using the following url :

git://github.com/konnectors/cozy-konnector-.git#build

Build using Travis CI

This project contains a .travis.yml config file which allows you to build your connector automatically using [Travis-CI][travis].

You can follow these steps to enable building using Travis:

Now Travis is ready to build your project, it should build it each time your push a commit in your repository or create a pull request.

Note: Travis will push your build to your build branch ONLY for commits made on your master branch (included PR merge commits). You can see the related Travis statement here.

Add your new connector to Cozy Collect

The Cozy Collect application will soon use an application store as source of connectors. But for now, if you want to add your new connector to Cozy Collect, you can submit a message in the forum in the collect section, and we will handle this for you.