Update docs
This commit is contained in:
@@ -34,8 +34,8 @@ given is stored in the filename between the prefix and the original name, with a
|
|||||||
- Search for `ipp_upload_jane-smith,` to see everything Jane sent.
|
- Search for `ipp_upload_jane-smith,` to see everything Jane sent.
|
||||||
- Add a workflow per visitor to tag or sort their uploads: **Filter by filename**, match type `startsWith`, pattern
|
- Add a workflow per visitor to tag or sort their uploads: **Filter by filename**, match type `startsWith`, pattern
|
||||||
`ipp_upload_jane-smith,`, then **Add Tags** with a tag such as `Uploaded/Jane Smith`.
|
`ipp_upload_jane-smith,`, then **Add Tags** with a tag such as `Uploaded/Jane Smith`.
|
||||||
- Tag every visitor's uploads at once, including past ones, with the
|
- Tag the uploads of every visitor, including past ones, in one go with the
|
||||||
[bulk-tag script](#tag-every-visitor-s-uploads-at-once).
|
[bulk-tag script](#bulk-tag-uploads-by-visitor-name).
|
||||||
|
|
||||||
The comma matters: without it, `ipp_upload_jane` would also match `jane-smith` and `janet`. The name is whatever the
|
The comma matters: without it, `ipp_upload_jane` would also match `jane-smith` and `janet`. The name is whatever the
|
||||||
visitor typed, made lower case with hyphens for spaces and punctuation. A visitor who leaves the field empty is stored
|
visitor typed, made lower case with hyphens for spaces and punctuation. A visitor who leaves the field empty is stored
|
||||||
@@ -57,51 +57,71 @@ goes on the end, an empty one is written empty, and a file with no fields at all
|
|||||||
script that splits on the separator reads all of them: the last piece is the original filename, the rest are the
|
script that splits on the separator reads all of them: the last piece is the original filename, the rest are the
|
||||||
fields in order.
|
fields in order.
|
||||||
|
|
||||||
## Tag every visitor's uploads at once
|
## Bulk-tag uploads by visitor name
|
||||||
|
|
||||||
A workflow acts only on new uploads, and you need one for each visitor. The upload image includes a script that tags
|
A workflow only sees uploads that arrive after you create it, and you need a separate workflow for each visitor.
|
||||||
every upload with a visitor name, old and new, as `Uploaded/<name>`: `ipp_upload_jane-smith,IMG_0042.jpg` gets the
|
The upload image includes a script that does the same job in one pass over your whole library: it finds every file
|
||||||
tag `Uploaded/jane-smith`.
|
whose name starts with the upload prefix, reads the visitor's name from the filename, and tags the file
|
||||||
|
`Uploaded/<name>`. So `ipp_upload_jane-smith,IMG_0042.jpg` gets the tag `Uploaded/jane-smith`, whether it was
|
||||||
|
uploaded yesterday or months ago.
|
||||||
|
|
||||||
1. In Immich, sign in as the user who owns the shares. The script sees only that user's photos.
|
Adding a tag is something a share key cannot do, so the script needs an Immich API key. You pass the key to the one
|
||||||
2. Open **Account Settings**, then **API Keys**, and create a **New API Key** with the permissions `asset.read`,
|
command that runs the script, and nothing else. The upload service itself still holds no key, as described in
|
||||||
`user.read`, `tag.create` and `tag.asset`.
|
[Why IPP marks the filename](#why-ipp-marks-the-filename-instead-of-tagging).
|
||||||
3. Run the script in the upload container. Without `--apply` it changes nothing, and lists each file under the tag
|
|
||||||
it would get:
|
### Run the script
|
||||||
|
|
||||||
|
1. **Create an API key.** In Immich, sign in as the user who owns the shares, open **Account Settings**, then
|
||||||
|
**API Keys**, and create a **New API Key** with the permissions `asset.read`, `user.read`, `tag.create` and
|
||||||
|
`tag.asset`. The script only tags photos that belong to the user who made the key.
|
||||||
|
|
||||||
|
2. **Do a dry run.** The script runs inside the upload container, which is `ipp-upload` in the examples in this
|
||||||
|
guide. Without `--apply` it changes nothing, and lists each tag with the files that would get it:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js
|
docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js
|
||||||
```
|
```
|
||||||
|
|
||||||
4. Check the list, then run it again with `--apply` to add the tags:
|
3. **Add the tags.** Check the list, then run the same command with `--apply`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js --apply
|
docker exec -e IMMICH_API_KEY=your-api-key ipp-upload node dist/tag-uploads.js --apply
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Delete the API key in Immich if you don't plan to run the script again.
|
4. **Delete the API key** in Immich if you don't plan to run the script again.
|
||||||
|
|
||||||
The API key reaches only that one command. The upload service itself still holds no key, as described in
|
You can run the script again after each event. It adds only the tags that are missing, so files that already have
|
||||||
[Why IPP marks the filename](#why-ipp-marks-the-filename-instead-of-tagging).
|
their tag are left as they are.
|
||||||
|
|
||||||
The script reads [`upload.filenamePrefix`](/config/upload-service#filenameprefix) and
|
### What is tagged and what is skipped
|
||||||
[`upload.fieldSeparator`](/config/upload-service#fieldseparator) from the container's config. A second run adds only
|
|
||||||
the tags that are missing, so you can run it again after each event. Files without a visitor name, trashed files and
|
- A file with the prefix and a visitor name is tagged `Uploaded/<name>`.
|
||||||
files of other users are left alone.
|
- A file with the prefix but no name, from a visitor who left the name field empty, is left alone.
|
||||||
|
- Files in the trash, and files that belong to other Immich users, are left alone.
|
||||||
|
|
||||||
|
The script reads the prefix and the separator from the container's config, the same
|
||||||
|
[`upload.filenamePrefix`](/config/upload-service#filenameprefix) and
|
||||||
|
[`upload.fieldSeparator`](/config/upload-service#fieldseparator) the upload service uses. If you have changed either
|
||||||
|
setting since some files were uploaded, run the script once more with `--prefix` or `--separator` set to the old
|
||||||
|
value, so it can read those files too. When `upload.filenamePrefix` is `""`, visitor uploads look like any other
|
||||||
|
photo, so the script stops unless you pass `--prefix`.
|
||||||
|
|
||||||
|
### Options
|
||||||
|
|
||||||
| Option | Default | Effect |
|
| Option | Default | Effect |
|
||||||
|-----------------------|-------------------------|-------------------------------------------------------------------------------------------|
|
|-----------------------|-------------------------|-------------------------------------------------------------------------------------------|
|
||||||
| `--apply` | off | Add the tags. Without it, the script only reports. |
|
| `--apply` | off | Add the tags. Without it, the script only reports. |
|
||||||
| `--parent <tag>` | `Uploaded` | The parent tag. `--parent "Guests/Wedding"` gives `Guests/Wedding/jane-smith`. |
|
| `--parent <tag>` | `Uploaded` | The parent tag. `--parent "Guests/Wedding"` gives `Guests/Wedding/jane-smith`. |
|
||||||
| `--prefix <text>` | `upload.filenamePrefix` | The prefix to look for, when the files were stored with a different one. |
|
| `--prefix <text>` | `upload.filenamePrefix` | The prefix the files were stored with, if it differs from the current setting. |
|
||||||
| `--separator <chars>` | `upload.fieldSeparator` | The separator to read, when the files were stored with a different one. Quote it: `'^'`. |
|
| `--separator <chars>` | `upload.fieldSeparator` | The separator the files were stored with, if it differs from the current setting. Quote it: `'^'`. |
|
||||||
|
|
||||||
The script does not run when `upload.filenamePrefix` is `""`, because visitor uploads then look like any other photo.
|
### Files uploaded with IPP 4.0.0
|
||||||
|
|
||||||
Uploads from IPP 4.0.0 kept any comma in the visitor's filename, so `ipp_upload_Venice, Italy.jpg` looks as if it
|
IPP 4.0.0 kept a comma in the visitor's own filename, so a file such as `ipp_upload_Venice, Italy.jpg` looks as if
|
||||||
has a visitor field. The script skips a file when the text before the separator is not a name IPP writes, or the
|
`Venice` were a visitor name. The script skips a file when the text before the separator is not a name IPP would
|
||||||
text after it starts with a space, and lists each file it skips. A 4.0.0 file named `ipp_upload_venice,italy.jpg`
|
write, such as one with capitals or spaces, or when the text after it starts with a space, and lists each file it
|
||||||
still reads as a visitor called `venice`, so check the dry-run list before you use `--apply`.
|
skips. A 4.0.0 file named `ipp_upload_venice,italy.jpg` cannot be told apart from a visitor called `venice`, so
|
||||||
|
check the dry-run list before you use `--apply`.
|
||||||
|
|
||||||
## Review uploads before they appear
|
## Review uploads before they appear
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user