Initial / README

README.md

@@ -0,0 +1,89 @@
+# Uploader to automate the Upload and Import of Objects in museum-digital via WebDAV
+
+## Workflow
+
+### Setup
+
+Before becoming operational, the app needs to gather the information essential for an upload.
+It will hence attempt to do so when first run (or unless all relevant information is available).
+
+#### Required Information for Uploading
+
+- Link to the given instance of musdb (e.g. https://demo.museum-digital.org/musdb/)
+- Username
+- Mail address
+- Auth token for WebDAV access
+- Institution ID
+- Parser
+- Location of metadata files to upload
+- Location of images files to upload
+
+#### Setup workflow
+
+- First, the app requests the musdb *username* and *password*
+- It uses those to log in one time, retrieves `institution_id` and `user_mail`
+  via the yet to be created `/user/read/{id}` (see below) API as well as an
+  auth token for WebDAV uploads (via `/user/generate_webdav_access_token/{id}`)
+- The app verifies that a WebDAV connection can be established and leaves a
+  .txt file in the WebDAV directory to signal, that the import is run via the
+  uploader
+- The app lists the available parsers and requests the user to select one /
+  enter one's name
+- The app opens a file selection dialogue querying the user to select a folder
+  to upload metadata from
+- The app opens a file selection dialogue querying the user to select a folder
+  to upload images from
+- The thus gathered information is stored in a config file. The password is
+  discarded.
+
+### Upload workflow
+
+- Version check (*is the updater up to date*)
+- Config check (*is all necessary data configured*)
+- Check the configured location
+  + If the location does not exist, it displays a verbose warning
+  + If the metadata location exists and is not empty, the files upload is
+    triggered
+- Metadata files and image files are uploaded via WebDAV
+- The script generates the import configuration based on the data gathered
+  during setup
+
+## Commands
+
+- [ ] Upload
+- [ ] Verify ability to connect
+- [ ] Set optional setting (do the settings need to be validated?)
+- [ ] List config
+- [ ] Remove optional setting (in case an erroneous setting value has been set)
+- [ ] `--version` command to check currently installed version
+- [ ] Version check (via Gitea release RSS feed)
+
+## Interface
+
+- A command line interface is sufficient for this application
+
+## Libraries/resources to include
+
+- `requests` / HTTP library
+- JSON parser
+- XML parser (for version/update check)
+- [WebDAV client](https://pypi.org/project/webdav4/)
+
+Either JSON or XML may also serve to store the config data.
+
+## Additional, optional features
+
+- Multilinguality
+
+## Requirements
+
+- A museum to try this out with
+- Scripts connecting this one with the museum's collection management system:
+  + Runs export periodically, exports metadata to the target metadata folder,
+    copies relevant image files in the image folder. Negotiation of whether objects
+    need to be updated is handled by this script.
+
+## External requirements
+
+- [ ] [musdb API: /user/read/{id}](https://gitea.armuli.eu/museum-digital/musdb/issues/1291)
+- [ ] [musdb API: /list_import_formats](https://gitea.armuli.eu/museum-digital/musdb/issues/1292)