77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
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());
|
|
}
|
|
}
|
|
```
|