mirror of
https://github.com/TheAnachronism/docspell.git
synced 2024-11-13 02:31:10 +00:00
104 lines
3.9 KiB
Markdown
104 lines
3.9 KiB
Markdown
+++
|
|
title = "Usage"
|
|
insert_anchor_links = "right"
|
|
description = "How to use addons"
|
|
weight = 20
|
|
template = "docs.html"
|
|
+++
|
|
|
|
# Using Addons
|
|
|
|
This shows with an example, how to install and use an addon. If the ui
|
|
doesn't show these forms, addons are probably disabled. Addons need to
|
|
be enabled in the config file of the rest server.
|
|
|
|
## Discovering
|
|
|
|
Addons can be installed from any URL to a zip file. One way is to use
|
|
URLs generated by forges like github or gitlab. They provide zip files
|
|
containing the repository contents. Alternatively an addon may provide
|
|
specific files in their release section.
|
|
|
|
For example, this is the url to the first release of the rotate-pdf
|
|
addon:
|
|
|
|
- <https://github.com/docspell/rotate-pdf-addon/archive/refs/tags/v0.1.0.zip>
|
|
|
|
This url points to a fixed version. It is also possible to use urls
|
|
that are "moving targets":
|
|
|
|
- <https://github.com/docspell/rotate-pdf-addon/archive/refs/heads/master.zip>
|
|
|
|
The contents behind the above url will very likely change over time.
|
|
|
|
For better discoverability, repositories for addons on public forges
|
|
can be tagged with *docspell-addon*.
|
|
|
|
## Install
|
|
|
|
With an URL like above, you can go to *Manage Data -> Addons -> New*
|
|
and insert the url:
|
|
|
|
{{ figure2(light="addon-install-01.png", dark="addon-install-01_dark.png") }}
|
|
|
|
It might take a while for Docspell to download, extract and verify the
|
|
addon. The addon will be downloaded into the database. Once installed,
|
|
the given URL is not used anymore, unless a manual update is issued.
|
|
|
|
After this finishes, you cannot change the URL anymore:
|
|
|
|
{{ figure2(light="addon-install-02.png", dark="addon-install-02_dark.png") }}
|
|
|
|
When using URLs pointing to "moving targets", you could click the
|
|
*Update Addon* button to re-download the contents at the url. This
|
|
doesn't make much sense for URLs to fixed versions (in *theory* these
|
|
could change as well, of course) and it is not without risk. It can be
|
|
useful for own addons to have them quickly updated.
|
|
|
|
Now the addon is installed. It can now be used by creating a *run configuration*.
|
|
|
|
## Run Configuration
|
|
|
|
A run configuration is comprised of one or more addons, their inputs
|
|
and some settings regarding their runtime environment.
|
|
|
|
The name is used for displaying in the webapp. You can disable/enable
|
|
a run configuration.
|
|
|
|
It is possible that addons use [dsc](@/docs/tools/cli.md) or call the
|
|
rest-server otherwise. Usually a valid session is required (to set
|
|
tags or do searches). When selecting to run *on behalf of a user*, a
|
|
valid authenticator for that user is injected into the environment of
|
|
the addon run.
|
|
|
|
The *Trigger Run* setting specfies when this run configuraiton should
|
|
be executed. You can choose from options that all addons in the list
|
|
must support. In this example, only `existing-item` is used. This
|
|
means the run configuration can be selected to run on any item.
|
|
|
|
Other options include:
|
|
- `final-process-item`: executes automatically as the last step when
|
|
processing uploaded files
|
|
- `final-reprocess-item`: like `final-process-item` but applies when
|
|
an existing item is reprocessed.
|
|
- `scheduled`: runs periodically based on a schedule (and independent
|
|
from any item)
|
|
|
|
Each addon may require arguments. Click on *Configure* to enable the
|
|
*Arguments* section and add arguments for the corresponding addon.
|
|
What to insert here is completely specific to the addon. In this case,
|
|
it expects a JSON object with only one field `"degree"` that indicates
|
|
how to rotate. In this example, it should be rotated by 90°
|
|
counter-clockwise. You need to click *Update* to set it into the addon
|
|
and then *Submit* to save everything.
|
|
|
|
{{ figure2(light="addon-install-03.png", dark="addon-install-03_dark.png") }}
|
|
|
|
|
|
With this run configuration in place, you can try it out on some item:
|
|
|
|
{{ figure2(light="addon-install-04.png", dark="addon-install-04_dark.png") }}
|
|
|
|
This example configured the *rotate-pdf-addon* to rotate left by 90°.
|
|
Create a simlar run configuration to rotate to the right.
|