NAV
cURL Node

Introduction

Welcome to the Kotive API, and thank you for using Kotive!

Our API is build around REST, so all calls can be made using simple and predictable URLs!

All of our URLs start with https://webapp.kotive.com/api, and can be accessed with SSL only.

Authentication

Login

var Kotive = require('kotive');

To authorise:

curl -u username:password https://webapp.kotive.com/api/login
var client = Kotive.Client('username', 'password');

Or alternatively

curl https://webapp.kotive.com/api/login       \
    -H 'Authorization: Basic <login details>'
var client = Kotive.Client('username', 'authToken');

The Kotive API uses BASIC Auth to authenticate, and when you log in initially, it will provide you with an authToken that must be used with other requests. This authToken is sent instead of your password, and will expire when your session ends.

To get an authToken, you can sent a GET request to /login with your username and password specified in the -u tag, e.g.,

-u username:password

Or you could send a GET request to /login with the following header:

-H 'Authorization: Basic <login details>'

Example Response:

{
  "authToken": "3e2dfoxa58c243arabbitc17b9bb1bf7",
  "systemRoles": [{
    "id": 1,
    "label": "Account Owner"
  }, {
    "id": 2,
    "label": "User Administrator"
  }, {
    "id": 3,
    "label": "Maker"
  }],
  "userRoles": [{
    "userId": 14,
    "role": {
      "id": 1,
      "label": "Account Owner"
    },
    "groupId": 25
  }, {
    "userId": 14,
    "role": {
      "id": 2,
      "label": "User Administrator"
    },
    "groupId": 25
  }, {
    "userId": 14,
    "role": {
      "id": 3,
      "label": "Maker"
    },
    "groupId": 25
  }],
  "groupsIndex": [{
    "id": 24,
    "parentId": 1
  }, {
    "id": 24,
    "parentId": 245
  }],
  "user": {
    "email": "example@example.com",
    "username": "example@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "id": 14,
    "mobile": "",
    "password": "****"
  }
}

Great! You’ve successfully logged in! You’ll see that with the above login request, you get a JSON response that should look similar to that on the right.

We know it’s a little daunting at first, but here’s a breakdown of what’s included in the response:

Attribute Description
authToken This is the authToken that you may use instead of your password for making requests.
systemRoles This is a list of all of the default roles associated with your account. Each entry consists of the ID of that group, and a human-friendly label. Custom roles will not be displayed here.
userRoles This is a list of every role that has been assigned to you. Each entry contains your Person ID, a role object with the role ID and a description, and the ID of the group that you have that role in.
groupsIndex This is a list of every group that you belong to. It shows you the group’s ID, as well as the ID of the parent group to which this group belongs.
user Finally, this section provides you with information on your user account. It shows you your email address and username, your first and last names, your Person ID, your mobile phone number, and a hidden version of your password. Note that this will always show four stars, regardless of password length.

This information will come in handy later, but for now, we’re mostly just interested in the authToken attribute.

The authToken attribute can be used to replace the password in all further requests, and in both types of authentication. This is more secure than using your password, as if something ever goes wrong, we can easily revoke your authToken and issue you a new one.

To use it you would have:

-u username:authToken

Or

Authorization: Basic <login details>

Where <login details> is made up of Base64 encoded username:authToken

Password reset

Example Request

curl https://webapp.kotive.com/api/user/resetpassword  \
    -X POST                                            \
    -H "Content-Type: application/json"                \
    -d '{"email": "example@example.com"}' 
client.auth.passwordReset({email: "example@example.com"}, function (d) {
  // d is the response from the server
});

Example Response

OK

You forgot your password? And you’ve already tried ‘1234’? Don’t worry, it happens to the best of us! Here’s how to recover it using the API:

Send a POST request to /user/resetpassword with "email": "<your email address>" as the payload.

That’s it! Now the user just has to follow the email prompts in their inbox to change their password.

People

Get a list of people

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/people  \
    -H 'Authorization: Basic <login details>'
client.people.list(<group_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "people": [{
    "email": "example@example.com",
    "username": "example@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "id": 130,
    "mobile": "",
    "password": "****"
  }]
}

Ever feel like you need a list of everybody that’s associated with your account? No? Well here’s how to do it anyway:

First of all you’ll need the group_id of the group, so that you can find out who is in that group. Getting this value should be pretty easy, as it will be nested inside of the groupsIndex part of the login response you got earlier!

Once you’ve got that value, all you have to do it submit a GET request to /group/<group_id>/people, and the reponse will contain the list of people you’re looking for.

Create a new person

Example Request

curl https://webapp.kotive.com/api/people      \
    -X POST                                    \
    -H "Content-Type: application/json"        \
    -H 'Authorization: Basic <login details>'  \
    -d '{"person": {"email": "<email>", "username": "<username>", "firstname": "<firstname>", "lastname": "<lastname>", "mobile": "<mobile>", "password": "<password>", "groupId": <groupId>}}'
client.people.create({email: '<email>', username: '<username>', firstname: '<firstname>', lastname: '<lastname>', mobile: '<mobile>', password: '<password>', groupId: <groupId>}}, function (d) {
  // d is the response from the server
});

Example Response

{
  "person": {
    "email": "johanna@example.com",
    "username": "johanna@example.com",
    "firstname": "Johanna",
    "lastname": "Doe",
    "id": 133,
    "mobile": "",
    "password": "****"
  }
}

Has a new special someone come into your life? ;) Or is it just that time of year when your company has hired a whole load of newbies and wants you to add them to the system? Either way, here’s how to do it quickly and still get time to procrastinate!

To create a new person (not really), you must make a POST request to /people with all of the information about the new person:

Attribute Description Required
email The email address of the person to add Yes
username The username is the same as the email address Yes
firstname The person’s first name Yes
lastname The person’s last name Yes
mobile The person’s mobile number No
password The person’s password No
groupId The ID of the group to add the new person to Yes

If you wish to send an invitation email to the person after you have added them, simply follow the instructions on Password reset, as resetting the password of a user that doesn’t yet exist will sent them an invitation email.

Update a person

Currently, the only change you can make to somebody’s details is changing which roles have been assigned to them. Details on how to do this can be found in the ‘Assign a role to a person’ and 'Revoke a role from a person’ sections.

Roles

Get a person’s roles

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/personRoles?personId=<person_id>  \
    -H 'Authorization: Basic <login details>'
client.roles.get(<group_id>, <person_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "personRoles": [{
    "id": 319,
    "userId": 130,
    "roleId": 22,
    "groupId": 26
  }]
}

Not sure what your boss actually does all day? Here’s a quick and easy way to find out using our API:

Again, you’ll first need the group_id of the group, otherwise we won’t know where to look. This is easy to get, as it is in the groupsIndex part of the login response from earlier!

In order to know who to query (apparently it is unethical to know everything about everybody and use it against them), we also need the Person ID of the person we want to query. This is obtained from the id attribute of the Get a list of people response. You simply look through that for the person that you’re curious about (a.k.a. your boss), and BAM, their Person ID is in the id attribute.

Now that you have these values, you simply insert them in the URL of a GET request to /group/<group_id>/personRoles?personID=<person_id>, and we’ll return a JSON string with a list of all of the roles that that person has!

Assign a role to a person

Example Request

curl https://webapp.kotive.com/api/personRoles  \
    -X POST                                     \
    -H 'Authorization: Basic <login details>'   \
    -H "Content-Type: application/json"         \
    -d '{"personRole":{"userId": <user_id>, "roleId": <role_id>, "groupId": <group_id>}}'
client.roles.assign({personRole: {userId: <user_id>, roleId: <role_id>, groupId: <group_id>}}, function (d) {
  // d is the response from the server
});

Example Response

{
  "personRole": {
    "id": 34,
    "userId": 10,
    "roleId": 2,
    "groupId": 24
  }
}

Did you leave somebody off the system again in your last minute panic? Well, before you have a complete emotional breakdown (it’s almost Friday!), here’s how to remedy the situation:

As per usual, you’ll need the group_id of the group to edit the person’s roles in, as well as the actual id of the person to update. The Group ID is fetched from the groupsIndex section of the response from your initial login request, and the Person ID can be found in the Get a list of people response - just choose the one that you need.

Once you have these values, simply submit a POST request to /personRoles with the information of the role you want to add in the following format as the payload:

{"personRole":{"userId": <user_id>,"roleId": <role_id>, "groupId": <group_id>}}

Replace the <user_id> attribute with the Person ID of the person to update, and do the same for <group_id>, but for groups. The <role_id> attribute is the role ID you want to give to the person, and must correlate to the ID of an existing role

Revoke a role from a person

Example Request

curl https://webapp.kotive.com/api/personRoles/<id>  \
    -X DELETE                                        \
    -H 'Authorization: Basic <login details>'

client.roles.revoke(<id>, function (d) {
  // d is the response from the server
});

Example Response

{

}

Did someone (gasp) complain about their work load? We know you don’t want to, but if HR is forcing you to relieve their stress by giving them less roles, here’s how to do it:

For this API call, all you’ll need is the unique role link ID of the role.

To get the unique role link ID, you will need to look at the response from Get a person’s roles. Find the roleId value that corresponds to the role that you want to revoke, and use the id attribute to send a DELETE request to /personRoles/<id>.

Taskflows

In Kotive, the terms process and taskflow, and activity and task are used interchangably.

Get a list of live taskflows

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/taskflowReports  \
    -H 'Authorization: Basic <login details>'
client.taskflow.list(<group_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "taskflowReports": [{
    "id": 79,
    "label": "My Average Taskflow"
  }, {
    "id": 76,
    "label": "My Awesome Taskflow"
  }]
}

Who knows what your group is up to? Probably doing something fun, like taking over the world or eating ice cream. Without you. If you’re really that desperate, here’s how to get a list of live taskflows for your group:

First of all you’ll need the group_id of the group, so that you can find out what taskflows are in your group. Getting this value should be pretty easy, as it will be nested inside of the groupsIndex part of the login response you got earlier!

Once you have your group_id, simply submit a GET request to /group/<group_id>/taskflowReports to get a list of live taskflows!

Start a new taskflow

Step 1: Get the taskflow template

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<taskflow_id>/blank  \
    -H 'Authorization: Basic <login details>'
client.taskflow.getTemplate(<group_id>, <taskflow_id>, function (d) {
  // d is the response from the server
});

Example Response

{
  "activity": {
    "phase": "new",
    "label": "A Taskflow",
    "id_process": 0,
    "publish": false,
    "id_t": 79,
    "order": 0,
    "status": "blank",
    "fields": [],
    "id_owning_process": -1,
    "kind": "form"
  },
  "childActivities": [{
    "phase": "new",
    "label": "Taskero numero twoero",
    "id_process": 0,
    "publish": false,
    "id_t": 862,
    "order": 0,
    "status": "blank",
    "fields": [{
      "pattern": "str[][]",
      "visible": true,
      "style": "{\"kind\":\"email\"}",
      "label": "Le Random Field",
      "readonly": false,
      "id": "-1_862_1015",
      "order": 0,
      "required": true,
      "value": ""
    }],
    "id_owning_process": -1,
    "kind": "form"
  }, {
    "phase": "new",
    "label": "Taskero numero uno",
    "id_process": 0,
    "publish": false,
    "id_t": 749,
    "order": 0,
    "status": "blank",
    "fields": [{
      "pattern": "str[][]",
      "visible": true,
      "style": "{\"kind\":\"text\"}",
      "label": "Nuclear Missile Launch Codes",
      "readonly": false,
      "id": "-1_749_1020",
      "order": 0,
      "required": true,
      "value": ""
    }],
    "id_owning_process": -1,
    "kind": "form"
  }]
}

When you want to start a new taskflow, you will want to know which tasks are available as part of the first step of the taskflow.

When you request a specific taskflow in Kotive, it will return information about the taskflow. This will include the first task(s) that can be completed, as well as the fields pertaining to them.

Before you can view information on a specific taskflow, you will need to obtain the <group_id> of the group to which the taskflow belongs, as well as the <taskflow_id> of the taskflow.

Send a GET request to /group/<group_id>/process/<taskflow_id>/blank. The response will contain the following attributes:

Attribute Description
activity This attribute provides information on the current taskflow. A breakdown of this attribute is available here.
childActivities This attribute contains a list of all of the tasks that are available to be executed. A breakdown of this attribute is available here.

Activity model

Attribute Description
id The ID of the instance of the task (only available for existing task instances)
label The task’s human-friendly label
kind The type of task that this is (e.g. form, email, sms, github, slack, …)
order The order that this activity is in, starting at 0
status The status of the task. This will default to ‘blank’
phase The current phase that this task is in. This will default to 'new’
publish Whether or not the task has been published
id_process The ID of instance of the taskflow which is currently associated with this task
id_t The ID of the task template (from the Designer)
id_owning_process This attribute allows you to attach processes to processes. For now this will always default to -1
fields A list of the fields contained within this task.

Field model

Attribute Description
id The unique ID that we use to identify your task. This is a compound ID, combined using underscores:
  • <id_field_instance>
  • <activity.id_t>
  • <id_field_template>
label The human-friendly label of the field
order The position of the field in the task, starting at 0
pattern The way the type of data is stored by Kotive. Examples of this are: str[][] (for dates, dividers, email, headings, numbers, paragraphs, passwords, telephone numbers, text, text areas, times, and web addresses), mse[Option1^Option2][] (multiple selection, for checkboxes), and sse[Option1^Option2][] (single selection, for radiobuttons and dropdown lists)
style The HTML style that our webapp uses to display the field
required Whether or not the field is required
visible Whether or not the field is visible
readonly Whether or not the field is readonly
value The current value of the field

Step 2: Start a taskflow instance

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process  \
    -X POST                                                  \
    -H 'Authorization: Basic <login details>'                \ 
    -H 'Content-Type: application/json'                      \
    -d '{"id_process":<id_process>,"id_t":<id_t>,"id_owning_process":<id_owning_process>,"fields":[]}'
client.taskflow.startInstance(<group_id>, {id_process: <id_process>, id_t: <id_t>, id_owning_process: <id_owning_process>, fields: []}, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "Taskero numero twoero",
  "id_process": 375,
  "publish": false,
  "id_t": 809,
  "order": 0,
  "status": "blank",
  "fields": [{
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"email\"}",
    "label": "Le Random Field",
    "readonly": false,
    "id": "-1_809_1135",
    "order": 0,
    "required": true,
    "value": ""
  }],
  "id_owning_process": -1,
  "kind": "form"
}, {
  "phase": "new",
  "label": "Taskero numero uno",
  "id_process": 375,
  "publish": false,
  "id_t": 889,
  "order": 0,
  "status": "blank",
  "fields": [{
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"number\"}",
    "label": "Nuclear Missile Launch Codes",
    "readonly": false,
    "id": "-1_889_1230",
    "order": 0,
    "required": true,
    "value": ""
  }, {
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"divider\"}",
    "label": "",
    "readonly": false,
    "id": "-1_889_1231",
    "order": 1,
    "required": false,
    "value": ""
  }, {
    "pattern": "str[][]",
    "visible": true,
    "style": "{\"kind\":\"textarea\"}",
    "label": "Presidential Banking Details",
    "readonly": false,
    "id": "-1_889_1232",
    "order": 2,
    "required": false,
    "value": ""
  }],
  "id_owning_process": -1,
  "kind": "form"
}]

Great! Now that you’ve got the taskflow template, you need to start a taskflow instance in order to get the id_process. You will then use the id_process to link all of your task instances. Getting this is pretty simple!

First of all, you build a JSON payload with the following attributes:

Attribute Description
id_process The ID of instance of the taskflow which is currently associated with this task. Leave this 0 for now.
id_t The ID of the task template (from the Designer).
id_owning_process This attribute allows you to attach processes to processes. For now this will always default to -1.
fields A list of fields to send along with this request. Leave this blank when starting a new taskflow.

Now that you’ve build your JSON string, use it to submit a POST request to /group/<group_id>/process. This will return the tasks which are available in the first step of the taskflow, and includes the id_process.

Submit a task

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<process_id>/activity  \
    -X POST                                                                        \
    -H 'Authorization: Basic <login details>'                                      \
    -H 'Content-Type: application/json'                                            \
    -d'{"id_process":<id_process>,"id_t":<id_t>,"id_owning_process":<id_owning_process>,"fields":[{"id":<id>,"value":<value>},{"id":<id>,"value":<value>}]}'
client.taskflow.submit(<group_id>, <process_id>, {id_process: <id_process>, id_t: <id_t>, id_owning_process: <id_owning_process>, fields: [{id:<id>, value: <value>}, {id: <id>, value: <value>}]}, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "A Form",
  "id_process": 386,
  "publish": false,
  "id_t": 798,
  "order": 2,
  "status": "blank",
  "fields": [{
    "pattern": "str[value][]",
    "visible": true,
    "style": "{\"kind\":\"text\"}",
    "label": "Field",
    "readonly": false,
    "id": "-1_798_8701",
    "order": 0,
    "required": false,
    "value": "value"
  }],
  "id_owning_process": -1,
  "kind": "form"
}]

Have your deadlines gotten to the point where you’re giving up on that intern and just doing everything yourself? That’s probably for the best, I’ve heard he uses Internet Explorer. If you really want to replace him entirely with one simple command, here’s how to do it! Disclaimer: this command will not bring you coffee.

In order to submit a task, you will yet again need the <group_id> and the <process_id>. Once you have these values, all you have to do is submit a POST request to /group/<group_id>/process/<process_id>/activity.

The payload of the POST request must contain certain information, outlined below:

Attribute Description
id The ID of the instance of the task (only available for existing task instances)
id_process The ID of the instance of the taskflow which is currently associated with this task
id_t The ID of the task template (from the Designer)
id_owning_process This attribute allows you to attach processes to processes. For now this will always default to -1
fields This is a list of the fields you want to update. For each entry in the list, you provide the id of the field you want to update, and the new value to put into that field.

The response obtained from this request may be:

Get the next task in a taskflow

Example Request

curl https://webapp.kotive.com/api/group/<group_id>/process/<process_id>/next  \
    -H 'Authorization: Basic <login details>'
client.taskflow.next(<group_id>, <process_id>, function (d) {
  // d is the response from the server
});

Example Response

[{
  "phase": "new",
  "label": "A Form",
  "id_process": 386,
  "publish": false,
  "id_t": 798,
  "order": 2,
  "status": "blank",
  "fields": [{
    "pattern": "str[value][]",
    "visible": true,
    "style": "{\"kind\":\"text\"}",
    "label": "Field",
    "readonly": false,
    "id": "-1_798_8701",
    "order": 0,
    "required": false,
    "value": "value"
  }],
  "id_owning_process": -1,
  "kind": "form"
}]
CONTINUE WITH TASKFLOW

As in the previous request, you’ll need to obtain the <group_id> of the group to which the taskflow belongs, as well as the <process_id> of the taskflow instance.

Once you have those values, simply point a GET request to /group/<group_id>/process/<process_id>/next to get the next task(s) in the taskflow. Pretty straightforward, huh?

The attributes contained in the response are in the activity model.