kotive.github.io

Kotive Services (integrations)

Thanks for your interest in adding your application to Kotive.

Your application will become available displayed within the Kotive Designer. Your customers will get more value from your application by having it integrated with their daily taskflows/workflows/business processes.

Applications in the Kotive Designer

How to add your application/tool/service to Kotive

Fork this repository.

Create a new folder in the root folder. Give it the name of your service, e.g. /awesomeapp/

Choose an applicable config sample (see below) and save it in /awesomeapp/config.json. Configs are based on the type of authentication your service uses. Samples:

Update /awesomeapp/config.json with your service’s authentication details.

Save your logo as /awesomeapp/icon.png (Max 200px x 200px. Min 128 px x 128 px). The name of the PNG has to be icon.png otherwise it will be ignored.

Add your service to services.json in the root folder. E.g.

    {
      "name": "My Awesome App",
      "service": "awesomeapp"
    }

How to add your application/tool/service as a task in taskflows

Copy the task configuration of any active integration to your /awesomeapp/ and rename to the name of your first task. (lowercase, words separated by _)

Working examples you can copy:

"fields": [] contain the user interface elements that are displayed in Kotive and that a Designer will see and use when adding your service to a taskflow.

Be nice and helpful. Use the helptext to provide clear, concise instructions (and <a href='#' target='_blank'>external links</a> to supporting documentation) to make it as easy as possible for your (and our) customers to use the integration.

The "method": "", "headers": {}, "endpoint": "", "request": {} and "response": {} contain the technical properties of your integration. You also need to provide a success and an error sample in the response.

Tags for pulling in dynamic data (fields) when executing your task (using Mandrill as example):

{field.fromEmail} pulls in the value of one of the fields in your task’s config where the parameter is set to fromEmail.
{auth.field.apikey} pulls in the value of one of the fields in the config.json where the parameter is set to apikey.

Helper tags for when you need to transform data or prep auth details:

{auth.oauth2Token} (example)
{base64_encode_username_password(auth.field.username:auth.field.password)} (example)
{encode_uri(field.webhook_url)} (example)
{string_to_boolean(field.javascript)} (example)
{string_to_number(field.number)}
{string_to_number_or_null(field.number)}
{string_to_hash(field.mergeFields)} (example)
{string_to_hash_or_null(field.payload)} (example)
{string_to_md5(field.emailAddress)} (example)
{comma_to_array(field.to)} (example)
{comma_to_array_or_null(field.to)} (example)
{comma_to_hash_array(field.to, email)} (example)
{json_to_xml(field.xmlpayload)} (example)
{generate_uuid_v4} (example)
{find_and_replace(field.to|find|replacewith)} (example)

You can add many tasks in your /awesomeapp/ folder by creating a copy of this task config, renaming it and updating its properties.

Submit for testing

You’ll need to install npm and install grunt.

Set up the required dependencies using npm.

npm install .

Then run the JSON lint validator & thumbnail generator. More thorough tests to be added in future.

grunt build

Submit a pull request to the staging branch if the grunt tasks passed successfully. The JSON should be ‘syntax error-free’ and the thumbnails should have been generated.

Another collaborator will review your json configs, language used, helptext, etc. When happy they will accept your pull request and it will be deployment to our staging environment. You’ll test it in there. When testing has been completed, issue a pull request to master - for review and deployment to our production environment.

Thanks for contributing!

This site is open source. Improve this page.