update-subjects-from-table/README.md

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

- 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