Add documentation to create external task providers

1 files changed, 76 insertions, 0 deletions

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());
+    }
+}
+```