Add documentation to create external task providers

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);
 }

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

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)