97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
# Generate and submit updated subject records from a TSV table
|
|
|
|
A composite action that reads a TSV file from the repository, derives subject records from its rows, and submits updated records to the knowledge pool.
|
|
|
|
It uses a JWT audience claim to fetch an access token, and then runs
|
|
`update_subject_records.py` against the given TSV file.
|
|
|
|
For each row in the TSV file, the script:
|
|
|
|
- validates the subject identifier
|
|
- optionally maps a recruiting-group code to a standard group identifier
|
|
- creates or updates a `TRR379Subject` record
|
|
- submits any new or modified record to the configured knowledge pool collection
|
|
|
|
By default, the script expects these columns:
|
|
|
|
- `trr-sub`: subject identifier
|
|
- `recr-group`: recruiting group code
|
|
|
|
## Inputs
|
|
|
|
| Input | Required | Default | Description |
|
|
|---|---:|---:|---|
|
|
| `study-pid` | yes | `""` | PID of the study this table belongs to. |
|
|
| `jwt-audience-claim` | yes | `""` | Audience claim used to fetch the Forgejo JWT. |
|
|
| `tsv-file` | yes | `""` | Path to the TSV file in the repository. |
|
|
| `options` | no | `""` | Extra command-line options passed to `update_subject_records.py`. |
|
|
|
|
## Usage
|
|
|
|
```yaml
|
|
- uses: your-org/your-action@v1
|
|
with:
|
|
study-pid: trr379:studies/...
|
|
jwt-audience-claim: ...
|
|
tsv-file: path/to/subjects.tsv
|
|
options: >-
|
|
--subid-colname trr-sub
|
|
--grpid-colname recr-group
|
|
--recr-group A group-a
|
|
--recr-group B group-b
|
|
```
|
|
|
|
## Usage information
|
|
|
|
```
|
|
Usage: update_subject_records.py [OPTIONS] STUDY_PID TABLE_PID INFILE
|
|
|
|
Read participant information and submit (updated) subject records
|
|
|
|
Three arguments are required (in order):
|
|
|
|
1. study PID
|
|
2. table PID
|
|
3. input file path
|
|
|
|
The input file must be in tab-separated value (TSV). Two items of
|
|
information are read from each row in this table (one row per participant):
|
|
|
|
- pseudonymized subject identifier (`trr-sub` column)
|
|
- subject recruiting group code (`recr-group` column)
|
|
|
|
Name and conventions for this information matches the agreement for ID
|
|
broker table formatting in TRR379.
|
|
|
|
The study PID identifies the the study (part) from which the imported
|
|
information originate. It should match an existing knowledge pool `Study`
|
|
record. For example, the value `trr379:studies/q01-fp1-aachen` would expand
|
|
to `https://trr379.de/ns/studies/q01-fp1-aachen`.
|
|
|
|
The table ID identifiers the specific version of the source table. For files
|
|
tracked in Git, this can be the content blob SHA (prefixed with `dldi:`).
|
|
Alternatively, an ISO date string can be given.
|
|
|
|
Options:
|
|
--subid-colname TEXT name of the TSV column holding the subject
|
|
identifiers [default: trr-sub]
|
|
--grpid-colname TEXT name of the TSV column holding the recruiting
|
|
group identifiers [default: recr-group]
|
|
--recr-group <TEXT TEXT>... code/id pair; may be given multiple times.
|
|
--subid-expr TEXT Regular expression any subject identifier must
|
|
match. [default: ^[A-Z]\d\d\d\d$]
|
|
--subpid-prefix TEXT prefix to prepend to the subject identifier to
|
|
form the record PID [default:
|
|
trr379:subjects/]
|
|
--pool-api-url TEXT Knowledge pool API URL to receive the subject
|
|
record submission. [default:
|
|
https://pool.v0.trr379.de/api]
|
|
--pool-collection TEXT Target knowledge pool record collection
|
|
[default: protected]
|
|
--help Show this message and exit.
|
|
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|