Representative (hand-written)
Generated by
scripts/generate_docs.py(scripts/regen_docs.sh). Do not edit by hand.
Methods of client.representative (reportnet_api.resources.representative_ext.RepresentativeResource). Every method also exists on AsyncReportnetClient as await a_client.representative.<name>(...) with the same arguments. Roles are copied from the API spec; where it states none, this page says so rather than guessing.
Methods
- create_lead_reporter
- create_representative
- data_provider
- data_provider_groups
- data_providers
- export_lead_reporters_file
- import_lead_reporters_file
- representatives
- validate_lead_reporters
create_lead_reporter
add a lead reporter.
HTTP: POST /representative/{representativeId}/leadReporter/dataflow/{dataflowId}
Call: client.representative.create_lead_reporter(...) (async client: await a_client.representative.create_lead_reporter(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
representative_id |
int |
yes | ||
dataflow_id |
int |
yes | ||
email |
str |
yes | ||
check |
bool |
no | True |
Returns: int
Allowed roles:
Not stated in the API spec.
RepresentativeControllerImpl#createLeadReporter (hidden), body
{"email": ...}. Returns the new lead reporter's id. Keyword-only:
Reportnet authorizes on dataflow_id but loads the representative by
representative_id alone, so swapped or mismatched ids would silently
add the lead reporter to another dataflow's representative. With
check (default) this first reads representatives(dataflow_id) and
raises ValueError if representative_id isn't among them.
The backend lower-cases the email and checks its form (400 otherwise);
the same email twice on one representative answers 400. An email
without a Reportnet account is still added, marked invalid, and gets
its permissions later through validate_lead_reporters().
@LockMethod per representative. The email is personal data.
Requires DATAFLOW_CUSTODIAN, DATAFLOW_STEWARD or DATAFLOW_STEWARD_SUPPORT.
Live-tested notes:
- Mocked tests only; not run live. Written from the
developsource; needs a custodian's, steward's or steward support's login token (no ApiKey branch).
create_representative
add a representative (data provider) to a dataflow.
HTTP: POST /representative/{dataflowId}
Call: client.representative.create_representative(...) (async client: await a_client.representative.create_representative(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dataflow_id |
int |
yes | ||
data_provider_id |
int |
yes | ||
data_provider_group_id |
int \| None |
no | None |
Returns: int
Allowed roles:
Not stated in the API spec.
RepresentativeControllerImpl#createRepresentative (hidden), body a
RepresentativeVO with dataProviderId (a data_providers() item's
id). Reportnet never reads dataProviderGroupId: it is sent only
when given, for the record. Returns the new representative's id, for
create_lead_reporter(). It starts without lead reporters, datasets
or receipt.
Errors: a provider the dataflow already has answers 400
(REPRESENTATIVE_DUPLICATED behind a generic message); an unknown
data_provider_id answers 500 (a foreign-key violation passed on by a
catch-all). @LockMethod without lock criteria: the lock is global,
across all dataflows, so concurrent calls (from anyone) can get 423.
Requires DATAFLOW_CUSTODIAN, DATAFLOW_STEWARD or DATAFLOW_STEWARD_SUPPORT.
Live-tested notes:
- Mocked tests only; not run live. Written from the
developsource; needs a custodian's, steward's or steward support's login token (no ApiKey branch).
data_provider
one provider (same fields as data_providers() items). Any authenticated user.
HTTP: GET /representative/dataProvider/id/{id}
Call: client.representative.data_provider(...) (async client: await a_client.representative.data_provider(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
data_provider_id |
int |
yes |
Returns: dict[str, Any]
Allowed roles:
Not stated in the API spec.
Live-tested notes:
- Live-checked with ApiKey and Bearer.
data_provider_groups
the country provider groups.
HTTP: GET /representative/dataProvider/countryGroups
Call: client.representative.data_provider_groups(...) (async client: await a_client.representative.data_provider_groups(...))
No arguments.
Returns: list[dict[str, Any]]
Allowed roles:
Not stated in the API spec.
Items are {"dataProviderGroupId", "label"} (note the key: the items of
data_providers() call the same id groupId); live there are two, 1
"Member countries" and 2 "All countries: member countries
PLUS other countries and territories". Any authenticated user.
Live-tested notes:
- Live-checked: two groups, 1 'Member countries' and 2 'All countries'.
data_providers
the providers in a group.
HTTP: GET /representative/dataProvider/{groupId}
Call: client.representative.data_providers(...) (async client: await a_client.representative.data_providers(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
group_id |
int |
yes |
Returns: list[dict[str, Any]]
Allowed roles:
Not stated in the API spec.
Items are {"id", "group", "label", "code", "groupId"}: id is the
providerId, code the country code, groupId the group (same value
as dataProviderGroupId on data_provider_groups() items; group was
always None live). Live: group 1 has 33 member countries, e.g.
id 2 = Austria AT. Any authenticated user.
Live-tested notes:
- Live-checked: group 1 returned 33 member countries with
id(theproviderId),codeandlabel.
export_lead_reporters_file
the web app's "Export lead reporters" CSV.
HTTP: GET /representative/export/{dataflowId}
Call: client.representative.export_lead_reporters_file(...) (async client: await a_client.representative.export_lead_reporters_file(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dataflow_id |
int |
yes |
Returns: bytes
Allowed roles:
Not stated in the API spec.
RepresentativeControllerImpl#exportLeadReportersFile (hidden),
RepresentativeServiceImpl#exportFile. Returns the file's bytes
(Dataflow-<id>-Lead-Reporters.csv, no BOM): a header line
Representing,Email (not quoted), then one line per lead reporter
with every value quoted ("AT","someone@example.org"), and "AT",""
for a representative without lead reporters. The delimiter is the
platform's exportDataDelimiter (, in configuration/consulKV.json);
lines end in \n. Representing is the data provider's code: the file
carries no provider group, label or flags. Emails are personal data.
Requires DATAFLOW_CUSTODIAN, DATAFLOW_STEWARD or DATAFLOW_STEWARD_SUPPORT
(login token only, see the module docstring).
Live-tested notes:
- Mocked tests only; not run live. Written from the
developsource; needs a custodian's, steward's or steward support's login token (no ApiKey branch).
import_lead_reporters_file
add lead reporters from a CSV.
HTTP: POST /representative/import/{dataflowId}/group/{groupId}
Call: client.representative.import_lead_reporters_file(...) (async client: await a_client.representative.import_lead_reporters_file(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dataflow_id |
int |
yes | ||
group_id |
int |
yes | ||
file |
str \| os.PathLike[str] |
yes |
Returns: bytes
Allowed roles:
Not stated in the API spec.
RepresentativeControllerImpl#importFileCountryTemplate (hidden),
RepresentativeServiceImpl#importLeadReportersFile; multipart file
in export_lead_reporters_file()'s format (Representing,Email).
group_id is the provider group whose codes Representing holds.
Only adds: nothing is removed or changed.
The backend discards the first line (so a BOM there is harmless),
splits the rest on \n and each line on the delimiter without reading
quotes, and strips \r only from the email. This method therefore
checks and cleans the file before sending it (see _upload): .csv
name, header first, line ends turned into \n, blank lines dropped,
exactly two comma-separated values per data line; otherwise it raises
ValueError and sends nothing.
Returns the backend's result CSV (Representing,Email,Imported), one
line per data line, Imported being:
- "OK - imported": a lead reporter was added, or a new representative
was created (also for a line with a blank email);
- "KO - invalid email": the email is malformed. For a provider the
dataflow doesn't have yet, the representative is still created, so
a KO line does not mean nothing changed;
- empty: that email is already a lead reporter of that representative
in Reportnet (nothing done);
- "KO - imported user already exists ... for the same Representative.":
the same email appears twice for one provider within this file;
- "KO - imported Representative already exists": a blank email for a
provider the dataflow already has;
- "Error during import, country (company) code doesn't correspond to
a country (company) in ReportNet": unknown code for group_id.
Errors: an empty file or an unknown dataflow answers 400, but an I/O error while reading is only logged and answers 200 with a partial result, and a line with more than two values has its email ignored (refused here before sending), so read the result lines. Not retried. Requires DATAFLOW_CUSTODIAN, DATAFLOW_STEWARD or DATAFLOW_STEWARD_SUPPORT.
Live-tested notes:
- Mocked tests only; not run live. Written from the
developsource; needs a custodian's, steward's or steward support's login token (no ApiKey branch).
representatives
a dataflow's representatives.
HTTP: GET /representative/v1/dataflow/{dataflowId}
Call: client.representative.representatives(...) (async client: await a_client.representative.representatives(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dataflow_id |
int |
yes |
Returns: list[dict[str, Any]]
Allowed roles:
Not stated in the API spec.
Each item has id, dataProviderId (the providerId other endpoints
take; resolve it with data_provider()), dataProviderGroupId,
leadReporters (a list that includes email addresses: personal data),
receiptDownloaded, receiptOutdated, hasDatasets and
restrictFromPublic. Backend rule: a dataflow role (custodian,
steward, editor, observer, lead reporter, reporter write, steward
support), an ApiKey for the dataflow, or ADMIN. A dataflow without
representatives (e.g. a design dataflow) gives an empty list.
Live-tested notes:
- Live-checked (ApiKey and Bearer) only on a dataflow with no representatives, so the empty list is verified and the item shape comes from the backend source.
leadReportersinclude email addresses (personal data).
validate_lead_reporters
recheck lead reporters.
HTTP: PUT /representative/validateLeadReporters/dataflow/{dataflowId}
Call: client.representative.validate_lead_reporters(...) (async client: await a_client.representative.validate_lead_reporters(...))
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
dataflow_id |
int |
yes |
Returns: None
Allowed roles:
Not stated in the API spec.
RepresentativeControllerImpl#validateLeadReporters (hidden; the
mapping is declared on the RepresentativeController interface).
Rechecks the dataflow's invalid lead reporters against the registered
users and grants the ones now found their permissions. Asynchronous
(@Async): answers 200 at once, and the outcome only reaches the web
app as a notification (VALIDATE_LEAD_REPORTERS_COMPLETED/FAILED_EVENT),
so reread representatives() to see it.
Requires DATAFLOW_CUSTODIAN, DATAFLOW_STEWARD or DATAFLOW_STEWARD_SUPPORT.
Live-tested notes:
- Mocked tests only; not run live. Written from the
developsource; needs a custodian's, steward's or steward support's login token (no ApiKey branch).