Skip to content

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.

Back to index

Methods

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 develop source; 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 develop source; 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 (the providerId), code and label.

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 develop source; 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 develop source; 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. leadReporters include 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 develop source; needs a custodian's, steward's or steward support's login token (no ApiKey branch).