diff options
| -rw-r--r-- | app/Core/ExternalTask/ExternalTaskProviderInterface.php | 4 | ||||
| -rw-r--r-- | doc/plugin-external-tasks.markdown | 76 | ||||
| -rw-r--r-- | doc/plugins.markdown | 1 |
3 files changed, 79 insertions, 2 deletions
diff --git a/app/Core/ExternalTask/ExternalTaskProviderInterface.php b/app/Core/ExternalTask/ExternalTaskProviderInterface.php index 932912d9..f67f7552 100644 --- a/app/Core/ExternalTask/ExternalTaskProviderInterface.php +++ b/app/Core/ExternalTask/ExternalTaskProviderInterface.php @@ -70,8 +70,8 @@ interface ExternalTaskProviderInterface /** * Build external task URI based on import form values * - * @param array $values + * @param array $formValues * @return string */ - public function buildTaskUri(array $values); + public function buildTaskUri(array $formValues); } diff --git a/doc/plugin-external-tasks.markdown b/doc/plugin-external-tasks.markdown new file mode 100644 index 00000000..0701ea38 --- /dev/null +++ b/doc/plugin-external-tasks.markdown @@ -0,0 +1,76 @@ +External Task Providers +======================= + +Kanboard can be used to manage tasks stored in another system. +For example, an external system can be a bug tracker or any kind of ticketing software. +In this way, you can use Kanboard to manage external tasks in the same way as native tasks. + +Workflow +-------- + +Creation: + +1. The end-user select an alternative task provider during the task creation +2. The external task provider expose a form to the user to be able to fetch the external task +3. The external task is retrieved from the other system +4. A customized form is shown to the user + +Visualization: + +When the task detail page is opened, Kanboard will load asynchronously the remote task. +This information might be cached by the plugin to improve the loading time. + +Modification: + +Optionally, the plugin can offer a custom form to save extra information to the external system. + +Interfaces +---------- + +External task providers must implements at least two interfaces: + +- `Kanboard\Core\ExternalTask\ExternalTaskProviderInterface` +- `Kanboard\Core\ExternalTask\ExternalTaskInterface` + +### ExternalTaskProviderInterface + +| Method | Usage | +|----------------------------------------------------|-----------------------------------------------------------------| +| `getName()` | Get provider name (label) | +| `fetch()` | Retrieve task from external system or cache | +| `save($uri, array $formValues, array &$formErrors)`| Save external task to another system | +| `getImportFormTemplate()` | Get task import template name | +| `getCreationFormTemplate()` | Get creation form template | +| `getModificationFormTemplate()` | Get modification form template | +| `getViewTemplate()` | Get task view template name | +| `buildTaskUri(array $formValues)` | Build external task URI based on import form values | + +### ExternalTaskInterface + +| Method | Usage | +|---------------------------------------------------|-----------------------------------------------------------------| +| `getUri()` | Return Uniform Resource Identifier for the task | +| `getFormValues()` | Return a dict to populate the task form | + + +Exceptions +---------- + +The plugin may raise an exception if something goes wrong: + +- `Kanboard\Core\ExternalTask\ExternalTaskException`: Generic error related to the external system +- `Kanboard\Core\ExternalTask\AccessForbiddenException`: Access not allowed by the external system +- `Kanboard\Core\ExternalTask\NotFoundException`: External task not found + +Provider Registration +--------------------- + +```php +class Plugin extends Base +{ + public function initialize() + { + $this->externalTaskManager->register(new MyExternalTaskProvider()); + } +} +``` diff --git a/doc/plugins.markdown b/doc/plugins.markdown index cff3eb6c..ff9f7b8c 100644 --- a/doc/plugins.markdown +++ b/doc/plugins.markdown @@ -23,6 +23,7 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I - [Authorization architecture](plugin-authorization-architecture.markdown) - [Custom group providers](plugin-group-provider.markdown) - [External link providers](plugin-external-link.markdown) +- [External tasks](plugin-external-tasks.markdown) - [Add avatar providers](plugin-avatar-provider.markdown) - [LDAP client](plugin-ldap-client.markdown) |