summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/api-application-procedures.markdown60
-rw-r--r--doc/api-group-member-procedures.markdown152
-rw-r--r--doc/api-group-procedures.markdown174
-rw-r--r--doc/api-json-rpc.markdown29
-rw-r--r--doc/api-project-permission-procedures.markdown274
-rw-r--r--doc/api-project-procedures.markdown101
-rw-r--r--doc/tests.markdown128
7 files changed, 718 insertions, 200 deletions
diff --git a/doc/api-application-procedures.markdown b/doc/api-application-procedures.markdown
index ab1230cc..2897b526 100644
--- a/doc/api-application-procedures.markdown
+++ b/doc/api-application-procedures.markdown
@@ -229,3 +229,63 @@ Response example:
}
}
```
+
+### getApplicationRoles
+
+- Purpose: **Get the application roles**
+- Parameters: none
+- Result: **Dictionary of role => role_name**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getApplicationRoles",
+ "id": 317154243
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 317154243,
+ "result": {
+ "app-admin": "Administrator",
+ "app-manager": "Manager",
+ "app-user": "User"
+ }
+}
+```
+
+### getProjectRoles
+
+- Purpose: **Get the project roles**
+- Parameters: none
+- Result: **Dictionary of role => role_name**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getProjectRoles",
+ "id": 8981960
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 8981960,
+ "result": {
+ "project-manager": "Project Manager",
+ "project-member": "Project Member",
+ "project-viewer": "Project Viewer"
+ }
+}
+``` \ No newline at end of file
diff --git a/doc/api-group-member-procedures.markdown b/doc/api-group-member-procedures.markdown
new file mode 100644
index 00000000..54153537
--- /dev/null
+++ b/doc/api-group-member-procedures.markdown
@@ -0,0 +1,152 @@
+Group Member API Procedures
+===========================
+
+### getGroupMembers
+
+- Purpose: **Get all members of a group**
+- Parameters:
+ - **group_id** (integer, required)
+- Result on success: **List of users**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getGroupMembers",
+ "id": 1987176726,
+ "params": [
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1987176726,
+ "result": [
+ {
+ "group_id": "1",
+ "user_id": "1",
+ "id": "1",
+ "username": "admin",
+ "is_ldap_user": "0",
+ "name": null,
+ "email": null,
+ "notifications_enabled": "0",
+ "timezone": null,
+ "language": null,
+ "disable_login_form": "0",
+ "notifications_filter": "4",
+ "nb_failed_login": "0",
+ "lock_expiration_date": "0",
+ "is_project_admin": "0",
+ "gitlab_id": null,
+ "role": "app-admin"
+ }
+ ]
+}
+```
+
+### addGroupMember
+
+- Purpose: **Add a user to a group**
+- Parameters:
+ - **group_id** (integer, required)
+ - **user_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "addGroupMember",
+ "id": 1589058273,
+ "params": [
+ 1,
+ 1
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1589058273,
+ "result": true
+}
+```
+
+### removeGroupMember
+
+- Purpose: **Remove a user from a group**
+- Parameters:
+ - **group_id** (integer, required)
+ - **user_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "removeGroupMember",
+ "id": 1730416406,
+ "params": [
+ 1,
+ 1
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1730416406,
+ "result": true
+}
+```
+
+### isGroupMember
+
+- Purpose: **Check if a user is member of a group**
+- Parameters:
+ - **group_id** (integer, required)
+ - **user_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "isGroupMember",
+ "id": 1052800865,
+ "params": [
+ 1,
+ 1
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1052800865,
+ "result": false
+}
+```
diff --git a/doc/api-group-procedures.markdown b/doc/api-group-procedures.markdown
new file mode 100644
index 00000000..1e976b8c
--- /dev/null
+++ b/doc/api-group-procedures.markdown
@@ -0,0 +1,174 @@
+Group API Procedures
+====================
+
+### createGroup
+
+- Purpose: **Create a new group**
+- Parameters:
+ - **name** (string, required)
+ - **external_id** (string, optional)
+- Result on success: **link_id**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "createGroup",
+ "id": 1416806551,
+ "params": [
+ "My Group B",
+ "1234"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1416806551,
+ "result": 2
+}
+```
+
+### updateGroup
+
+- Purpose: **Update a group**
+- Parameters:
+ - **group_id** (integer, required)
+ - **name** (string, optional)
+ - **external_id** (string, optional)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "updateGroup",
+ "id": 866078030,
+ "params": {
+ "group_id": "1",
+ "name": "ABC",
+ "external_id": "something"
+ }
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 866078030,
+ "result": true
+}
+```
+
+### removeGroup
+
+- Purpose: **Remove a group**
+- Parameters:
+ - **group_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "removeGroup",
+ "id": 566000661,
+ "params": [
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 566000661,
+ "result": true
+}
+```
+
+### getGroup
+
+- Purpose: **Get one group**
+- Parameters:
+ - **group_id** (integer, required)
+- Result on success: **Group dictionary**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getGroup",
+ "id": 1968647622,
+ "params": [
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1968647622,
+ "result": {
+ "id": "1",
+ "external_id": "",
+ "name": "My Group A"
+ }
+}
+```
+
+### getAllGroups
+
+- Purpose: **Get all groups**
+- Parameters: none
+- Result on success: **list of groups**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getAllGroups",
+ "id": 546070742
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 546070742,
+ "result": [
+ {
+ "id": "1",
+ "external_id": "",
+ "name": "My Group A"
+ },
+ {
+ "id": "2",
+ "external_id": "1234",
+ "name": "My Group B"
+ }
+ ]
+}
+```
diff --git a/doc/api-json-rpc.markdown b/doc/api-json-rpc.markdown
index 710b0b1b..34559df5 100644
--- a/doc/api-json-rpc.markdown
+++ b/doc/api-json-rpc.markdown
@@ -48,16 +48,19 @@ Usage
- [Authentication](api-authentication.markdown)
- [Examples](api-examples.markdown)
-- [Application Procedures](api-application-procedures.markdown)
-- [Project Procedures](api-project-procedures.markdown)
-- [Board Procedures](api-board-procedures.markdown)
-- [Swimlane Procedures](api-swimlane-procedures.markdown)
-- [Category Procedures](api-category-procedures.markdown)
-- [Automatic Action Procedures](api-action-procedures.markdown)
-- [Task Procedures](api-task-procedures.markdown)
-- [Subtask Procedures](api-subtask-procedures.markdown)
-- [File Procedures](api-file-procedures.markdown)
-- [Link Procedures](api-link-procedures.markdown)
-- [Comment Procedures](api-comment-procedures.markdown)
-- [User Procedures](api-user-procedures.markdown)
-- [User API Access Procedures](api-me-procedures.markdown)
+- [Application](api-application-procedures.markdown)
+- [Projects](api-project-procedures.markdown)
+- [Project Permissions](api-project-permission-procedures.markdown)
+- [Boards](api-board-procedures.markdown)
+- [Swimlanes](api-swimlane-procedures.markdown)
+- [Categories](api-category-procedures.markdown)
+- [Automatic Actions](api-action-procedures.markdown)
+- [Tasks](api-task-procedures.markdown)
+- [Subtasks](api-subtask-procedures.markdown)
+- [Files](api-file-procedures.markdown)
+- [Links](api-link-procedures.markdown)
+- [Comments](api-comment-procedures.markdown)
+- [Users](api-user-procedures.markdown)
+- [Groups](api-group-procedures.markdown)
+- [Group Members](api-group-member-procedures.markdown)
+- [Me](api-me-procedures.markdown)
diff --git a/doc/api-project-permission-procedures.markdown b/doc/api-project-permission-procedures.markdown
new file mode 100644
index 00000000..f64028b9
--- /dev/null
+++ b/doc/api-project-permission-procedures.markdown
@@ -0,0 +1,274 @@
+Project Permission API Procedures
+=================================
+
+### getProjectUsers
+
+- Purpose: **Get all members of a project**
+- Parameters:
+ - **project_id** (integer, required)
+- Result on success: **Dictionary of user_id => user name**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getProjectUsers",
+ "id": 1601016721,
+ "params": [
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1601016721,
+ "result": {
+ "1": "admin"
+ }
+}
+```
+
+### getAssignableUsers
+
+- Purpose: **Get users that can be assigned to a task for a project** (all members except viewers)
+- Parameters:
+ - **project_id** (integer, required)
+ - **prepend_unassigned** (boolean, optional, default is false)
+- Result on success: **Dictionary of user_id => user name**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "getAssignableUsers",
+ "id": 658294870,
+ "params": [
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 658294870,
+ "result": {
+ "1": "admin"
+ }
+}
+```
+
+### addProjectUser
+
+- Purpose: **Grant access to a project for a user**
+- Parameters:
+ - **project_id** (integer, required)
+ - **user_id** (integer, required)
+ - **role** (string, optional)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "addProjectUser",
+ "id": 1294688355,
+ "params": [
+ "1",
+ "1",
+ "project-viewer"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1294688355,
+ "result": true
+}
+```
+
+### addProjectGroup
+
+- Purpose: **Grant access to a project for a group**
+- Parameters:
+ - **project_id** (integer, required)
+ - **group_id** (integer, required)
+ - **role** (string, optional)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "addProjectGroup",
+ "id": 1694959089,
+ "params": [
+ "1",
+ "1"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 1694959089,
+ "result": true
+}
+```
+
+### removeProjectUser
+
+- Purpose: **Revoke user access to a project**
+- Parameters:
+ - **project_id** (integer, required)
+ - **user_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "removeProjectUser",
+ "id": 645233805,
+ "params": [
+ 1,
+ 1
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 645233805,
+ "result": true
+}
+```
+
+### removeProjectGroup
+
+- Purpose: **Revoke group access to a project**
+- Parameters:
+ - **project_id** (integer, required)
+ - **group_id** (integer, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "removeProjectGroup",
+ "id": 557146966,
+ "params": [
+ 1,
+ 1
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 557146966,
+ "result": true
+}
+```
+
+### changeProjectUserRole
+
+- Purpose: **Change role of a user for a project**
+- Parameters:
+ - **project_id** (integer, required)
+ - **user_id** (integer, required)
+ - **role** (string, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "changeProjectUserRole",
+ "id": 193473170,
+ "params": [
+ "1",
+ "1",
+ "project-viewer"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 193473170,
+ "result": true
+}
+```
+
+### changeProjectGroupRole
+
+- Purpose: **Change role of a group for a project**
+- Parameters:
+ - **project_id** (integer, required)
+ - **group_id** (integer, required)
+ - **role** (string, required)
+- Result on success: **true**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "method": "changeProjectGroupRole",
+ "id": 2114673298,
+ "params": [
+ "1",
+ "1",
+ "project-viewer"
+ ]
+}
+```
+
+Response example:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2114673298,
+ "result": true
+}
+```
diff --git a/doc/api-project-procedures.markdown b/doc/api-project-procedures.markdown
index acb4297e..2d23615b 100644
--- a/doc/api-project-procedures.markdown
+++ b/doc/api-project-procedures.markdown
@@ -409,104 +409,3 @@ Request example:
]
}
```
-
-### getMembers
-
-- Purpose: **Get members of a project**
-- Parameters:
- - **project_id** (integer, required)
-- Result on success: Key/value pair of user_id and username
-- Result on failure: **false**
-
-Request example:
-
-```json
-{
- "jsonrpc": "2.0",
- "method": "getMembers",
- "id": 1944388643,
- "params": [
- 1
- ]
-}
-```
-
-Response example:
-
-```json
-{
- "jsonrpc": "2.0",
- "id": 1944388643,
- "result": {
- "1": "user1",
- "2": "user2",
- "3": "user3"
- }
-}
-```
-
-### revokeUser
-
-- Purpose: **Revoke user access for a given project**
-- Parameters:
- - **project_id** (integer, required)
- - **user_id** (integer, required)
-- Result on success: **true**
-- Result on failure: **false**
-
-Request example:
-
-```json
-{
- "jsonrpc": "2.0",
- "method": "revokeUser",
- "id": 251218350,
- "params": [
- 1,
- 2
- ]
-}
-```
-
-Response example:
-
-```json
-{
- "jsonrpc": "2.0",
- "id": 251218350,
- "result": true
-}
-```
-
-### allowUser
-
-- Purpose: **Grant user access for a given project**
-- Parameters:
- - **project_id** (integer, required)
- - **user_id** (integer, required)
-- Result on success: **true**
-- Result on failure: **false**
-
-Request example:
-
-```json
-{
- "jsonrpc": "2.0",
- "method": "allowUser",
- "id": 2111451404,
- "params": [
- 1,
- 2
- ]
-}
-```
-
-Response example:
-
-```json
-{
- "jsonrpc": "2.0",
- "id": 2111451404,
- "result": true
-}
-```
diff --git a/doc/tests.markdown b/doc/tests.markdown
index 5e5ad389..b2d95491 100644
--- a/doc/tests.markdown
+++ b/doc/tests.markdown
@@ -1,7 +1,7 @@
-How to run units and functional tests?
-======================================
+Automated tests
+===============
-[PHPUnit](https://phpunit.de/) is used to run automatic tests on Kanboard.
+[PHPUnit](https://phpunit.de/) is used to run automated tests on Kanboard.
You can run tests across different databases (Sqlite, Mysql and Postgresql) to be sure that the result is the same everywhere.
@@ -9,31 +9,18 @@ Requirements
------------
- Linux/Unix machine
-- PHP command line
+- PHP cli
- PHPUnit installed
- Mysql and Postgresql (optional)
-Install the latest version of PHPUnit
--------------------------------------
-
-Simply download the PHPUnit PHAR et copy the file somewhere in your `$PATH`:
-
-```bash
-wget https://phar.phpunit.de/phpunit.phar
-chmod +x phpunit.phar
-sudo mv phpunit.phar /usr/local/bin/phpunit
-phpunit --version
-PHPUnit 4.2.6 by Sebastian Bergmann.
-```
-
-Running unit tests
-------------------
+Unit Tests
+----------
-### Testing with Sqlite
+### Test with Sqlite
Sqlite tests use a in-memory database, nothing is written on the file system.
-The config file is `tests/units.sqlite.xml`.
+The PHPUnit config file is `tests/units.sqlite.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.sqlite.xml`.
Example:
@@ -41,21 +28,26 @@ Example:
```bash
phpunit -c tests/units.sqlite.xml
-PHPUnit 4.2.6 by Sebastian Bergmann.
+PHPUnit 5.0.0 by Sebastian Bergmann and contributors.
-Configuration read from /Volumes/Devel/apps/kanboard/tests/units.sqlite.xml
+............................................................... 63 / 649 ( 9%)
+............................................................... 126 / 649 ( 19%)
+............................................................... 189 / 649 ( 29%)
+............................................................... 252 / 649 ( 38%)
+............................................................... 315 / 649 ( 48%)
+............................................................... 378 / 649 ( 58%)
+............................................................... 441 / 649 ( 67%)
+............................................................... 504 / 649 ( 77%)
+............................................................... 567 / 649 ( 87%)
+............................................................... 630 / 649 ( 97%)
+................... 649 / 649 (100%)
-................................................................. 65 / 74 ( 87%)
-.........
+Time: 1.22 minutes, Memory: 151.25Mb
-Time: 9.05 seconds, Memory: 17.75Mb
-
-OK (74 tests, 6145 assertions)
+OK (649 tests, 43595 assertions)
```
-**NOTE:** PHPUnit is already included in the Vagrant environment
-
-### Testing with Mysql
+### Test with Mysql
You must have Mysql or MariaDb installed on localhost.
@@ -68,27 +60,10 @@ By default, those credentials are used:
For each execution the database is dropped and created again.
-The config file is `tests/units.mysql.xml`.
+The PHPUnit config file is `tests/units.mysql.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.mysql.xml`.
-Example:
-
-```bash
-phpunit -c tests/units.mysql.xml
-
-PHPUnit 4.2.6 by Sebastian Bergmann.
-
-Configuration read from /Volumes/Devel/apps/kanboard/tests/units.mysql.xml
-
-................................................................. 65 / 74 ( 87%)
-.........
-
-Time: 49.77 seconds, Memory: 17.50Mb
-
-OK (74 tests, 6145 assertions)
-```
-
-### Testing with Postgresql
+### Test with Postgresql
You must have Postgresql installed on localhost.
@@ -100,37 +75,20 @@ By default, those credentials are used:
- Database: **kanboard_unit_test**
Be sure to allow the user `postgres` to create and drop databases.
-For each execution the database is dropped and created again.
+The database is recreated for each execution.
-The config file is `tests/units.postgres.xml`.
+The PHPUnit config file is `tests/units.postgres.xml`.
From your Kanboard directory, run the command `phpunit -c tests/units.postgres.xml`.
-Example:
-
-```bash
-phpunit -c tests/units.postgres.xml
-
-PHPUnit 4.2.6 by Sebastian Bergmann.
-
-Configuration read from /Volumes/Devel/apps/kanboard/tests/units.postgres.xml
-
-................................................................. 65 / 74 ( 87%)
-.........
-
-Time: 52.66 seconds, Memory: 17.50Mb
-
-OK (74 tests, 6145 assertions)
-```
-
-Running functionals tests
--------------------------
+Integration Tests
+-----------------
Actually only the API calls are tested.
Real HTTP calls are made with those tests.
-So a local instance of Kanboard is necessary and must listen on `http://localhost:8000`.
+So a local instance of Kanboard is necessary and must listen on `http://localhost:8000/`.
-Don't forget that all data will be removed/altered by the test suite.
+All data will be removed/altered by the test suite.
Moreover the script will reset and set a new API key.
1. Start a local instance of Kanboard `php -S 127.0.0.1:8000`
@@ -138,27 +96,27 @@ Moreover the script will reset and set a new API key.
The same method as above is used to run tests across different databases:
-- Sqlite: `phpunit -c tests/functionals.sqlite.xml`
-- Mysql: `phpunit -c tests/functionals.mysql.xml`
-- Postgresql: `phpunit -c tests/functionals.postgres.xml`
+- Sqlite: `phpunit -c tests/integration.sqlite.xml`
+- Mysql: `phpunit -c tests/integration.mysql.xml`
+- Postgresql: `phpunit -c tests/integration.postgres.xml`
Example:
```bash
-phpunit -c tests/functionals.sqlite.xml
-
-PHPUnit 4.2.6 by Sebastian Bergmann.
+phpunit -c tests/integration.sqlite.xml
-Configuration read from /Volumes/Devel/apps/kanboard/tests/functionals.sqlite.xml
+PHPUnit 5.0.0 by Sebastian Bergmann and contributors.
-..........................................
+............................................................... 63 / 135 ( 46%)
+............................................................... 126 / 135 ( 93%)
+......... 135 / 135 (100%)
-Time: 1.72 seconds, Memory: 4.25Mb
+Time: 1.18 minutes, Memory: 14.75Mb
-OK (42 tests, 160 assertions)
+OK (135 tests, 526 assertions)
```
-Continuous Integration with Travis-ci
+Continuous Integration with Travis-CI
-------------------------------------
After each commit pushed on the main repository, unit tests are executed across 5 different versions of PHP:
@@ -171,6 +129,4 @@ After each commit pushed on the main repository, unit tests are executed across
Each version of PHP is tested against the 3 supported database: Sqlite, Mysql and Postgresql.
-That mean we run 15 jobs each time the repository is updated. The execution time is around 25 minutes.
-
The Travis config file `.travis.yml` is located on the root directory of Kanboard.
generated by cgit v1.2.3 (git 2.39.1) at 2024-10-21 06:33:15 +0000