connector/consumer

Step	Summary
connector/consumer/discover_connector	Discover a counter-party's DSP endpoint, ID and protocol from its BPN.
connector/consumer/do_dsp	Run the full DSP flow (catalog → negotiation → transfer) via the SDK.
connector/consumer/do_dsp_with_bpnl	Run the full DSP flow using BPNL-based connector discovery via the SDK.
connector/consumer/extract_dataset	Extract the first matching dataset from catalog offers by dct:type.
connector/consumer/get_edr	Retrieve the EDR data address for a completed transfer.
connector/consumer/initiate_transfer	Start a data transfer for a contract that has already been negotiated.
connector/consumer/negotiate	Negotiate a contract with the provider and wait for the outcome.
connector/consumer/pull_data_filtered	Run the full DSP flow in one step, optionally constrained to one policy.
connector/consumer/pull_data_filtered_by_policy	Run the full DSP flow, accepting an offer that matches any of several policies.
connector/consumer/query_catalog	Query a provider's catalog via the SDK connector consumer service.
connector/consumer/query_catalog_by_asset_id	Query the catalog filtered by a specific asset ID.
connector/consumer/query_catalog_by_bpnl	Query the catalog using BPNL-based connector discovery.
connector/consumer/query_catalog_with_filters	Query a provider's catalog with multiple filter expressions via the SDK.

connector/consumer/discover_connector

Discover a counter-party's DSP endpoint, ID and protocol from its BPN.

Saturn only. The endpoint this calls is a Saturn addition and the SDK exposes it on the Saturn consumer service alone, so the step is registered for that release and a test on any other cannot resolve it.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
bpnl	string	yes	—	—	BPN of the counter-party whose connector is discovered.
counter_party_address	string	no	''	—	DSP endpoint to discover against, as its root or as the versioned endpoint the SUT binding carries — a trailing version path is dropped, since discovery is what appends it. When omitted the connector resolves the address from the BPN alone.
namespace	string	no	'https://w3id.org/edc/v0.0.1/ns/'	—	Namespace the response keys are prefixed with; bare keys are read too.

Output — the value assertions and returns: read

Output contract of connector/consumer/discover_connector.

Field	Type	Description
discovery	any	The discovery response document, unchanged.
counter_party_address	string	DSP endpoint the counter-party is addressed at.
counter_party_id	string	ID the counter-party identifies itself as.
protocol	string	DSP protocol version the endpoint speaks, e.g. 'dataspace-protocol-http:2025-1'.

connector/consumer/do_dsp

Run the full DSP flow (catalog → negotiation → transfer) via the SDK.

Returns the resulting data-plane address so connector/dataplane/http_request can fetch the data without any further wiring.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
expected_policies	list of object	no	[]	—	ODRL policies the negotiation is allowed to accept, as the raw policy document, the testlab simplified spelling, JSON text, or the whole 'config/connector/policy' variable that holds one.

Output — the value assertions and returns: read

What every DSP flow step hands back: where the data is, and the token for it.

Field	Type	Description
dataplane_url	string	Data-plane URL the negotiated data is fetched from.
edr_token	string	Authorization token for that data-plane URL.

connector/consumer/do_dsp_with_bpnl

Run the full DSP flow using BPNL-based connector discovery via the SDK.

Returns the same data-plane address as do_dsp.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.
bpnl	string	yes	—	—	BPN used to discover the counter-party's connector.
counter_party_address	string	no	None	—	DSP endpoint to discover against, as its root or as the versioned endpoint the SUT binding carries — a trailing version path is dropped, since discovery is what appends it. When omitted it is resolved from the BPN alone.
expected_policies	list of object	no	None	—	ODRL policies the negotiation is allowed to accept, as the raw policy document, the testlab simplified spelling, JSON text, or the whole 'config/connector/policy' variable that holds one.

Output — the value assertions and returns: read

What every DSP flow step hands back: where the data is, and the token for it.

Field	Type	Description
dataplane_url	string	Data-plane URL the negotiated data is fetched from.
edr_token	string	Authorization token for that data-plane URL.

connector/consumer/extract_dataset

Extract the first matching dataset from catalog offers by dct:type.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
datasets	list of object	yes	—	—	Dataset offers returned by a catalog query.
dct_type	string	yes	—	—	The 'dct:type' @id used to select the dataset.

Output — the value assertions and returns: read

Output contract of connector/consumer/extract_dataset.

Field	Type	Description
dataset	object	The first dataset whose 'dct:type' matched.
offer_id	string	Policy/offer ID of the first match.
asset_id	string	Asset ID of the first match.
catalog_policy	object	The ODRL policy the matched offer is made under, as the provider wrote it. This is what 'negotiate' has to be given: an offer is accepted under the policy it was made under, and only the catalog knows that policy's offer id.

connector/consumer/get_edr

Retrieve the EDR data address for a completed transfer.

Returns the same data-plane pair as initiate_transfer, so it can stand in for that step when the transfer was started elsewhere — a PULL initiate_transfer resolves a negotiation_id down to a transfer_id and then does exactly what this step does.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
transfer_id	string	no	None	—	Transfer process to read the EDR of; falls back to the 'transfer_id' context variable.
verify	any	no	None	—	TLS verification passed through to the SDK; None keeps its default.

Output — the value assertions and returns: read

Output contract of connector/consumer/get_edr.

Field	Type	Description
dataplane_url	string	Data-plane URL the negotiated data is fetched from.
edr_token	string	Authorization token for that data-plane URL.
data_address	DataAddressPayload	The full EDR data address document, unchanged.

connector/consumer/initiate_transfer

Start a data transfer for a contract that has already been negotiated.

A PULL transfer turns a finished negotiation into something connector/dataplane/http_request can call: it resolves negotiation_id down to a transfer_id, then does exactly what connector/consumer/get_edr does with one — the two steps share that lookup rather than each fetching the data address their own way. A PUSH transfer instead asks the connector to deliver the data to a destination of the test's choosing, and waits for that transfer to settle.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
transfer_type	string	no	'HttpData-PULL'	—	How the data moves: 'HttpData-PULL' (the consumer fetches it) or a '-PUSH' type such as 'HttpData-PUSH' or 'AmazonS3-PUSH'.
negotiation_id	string	no	None	—	PULL only — negotiation to collect the EDR for; falls back to the 'negotiation_id' context variable.
agreement_id	string	no	None	—	PUSH only — contract agreement the transfer runs under; falls back to the 'agreement_id' context variable.
data_destination	object	no	None	—	PUSH only — the EDC data address the provider pushes to.
counter_party_address	string	no	''	—	PUSH only — DSP endpoint of the provider; defaults to the bound SUT connector's 'dsp_url'.
max_wait	number	no	60.0	—	Seconds to wait for the transfer to settle: for a PULL, until the EDR the negotiation started is written; for a PUSH, until the transfer reaches a final state.
poll_interval	number	no	1.0	—	Seconds between two reads while waiting.
verify	any	no	None	—	TLS verification passed through to the SDK; None keeps its default.

Output — the value assertions and returns: read

Output contract of connector/consumer/initiate_transfer.

Field	Type	Description
transfer_id	string	ID of the transfer process.
state	string	State the transfer settled at, e.g. 'STARTED' or 'COMPLETED'.
edr_entry	object	PULL only — the EDR entry the negotiation produced.
dataplane_url	string	PULL only — data-plane URL the data is fetched from.
edr_token	string	PULL only — authorization token for that data-plane URL.
data_address	DataAddressPayload	PULL only — the full data address document, for assertions on its other keys.

connector/consumer/negotiate

Negotiate a contract with the provider and wait for the outcome.

The SDK starts the negotiation and answers with its ID straight away; this step then polls the negotiation until it finalises or terminates, so what it returns is the settled outcome rather than "accepted for processing".

Inputs

Parameter	Type	Required	Default	Also accepts	Description
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
asset_id	any	no	None	—	Asset ID to negotiate for; falls back to the 'catalog_asset_id' context variable.
policy	any	no	None	—	ODRL policy to negotiate under, as the policy document itself, its JSON text, or the whole 'config/connector/policy' variable that holds it; falls back to the 'catalog_policy' context variable.
max_wait	number	no	60.0	—	Seconds to wait for the negotiation to reach a final state.
poll_interval	number	no	1.0	—	Seconds between two negotiation state reads.

Output — the value assertions and returns: read

Output contract of connector/consumer/negotiate.

Field	Type	Description
negotiation_id	string	ID of the started negotiation.
agreement_id	string	ID of the contract agreement, once the negotiation finalised.
state	string	State the negotiation settled at, e.g. 'FINALIZED' or 'TERMINATED'.

connector/consumer/pull_data_filtered

Run the full DSP flow in one step, optionally constrained to one policy.

expected_policies reaches the SDK as the raw ODRL policies its offer comparison takes, whichever way the test wrote them — see tractusx_testlab.steps.connector.policies.as_policy_list. With no policy the SDK takes the first offer.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
max_wait	number	no	60.0	—	Seconds to wait for the transfer to complete.
poll_interval	number	no	1.0	—	Seconds between transfer-state polls.
expected_policies	list of object	no	None	—	Policies the offer must satisfy, as the raw policy document, the testlab simplified spelling, JSON text, or the whole 'config/connector/policy' variable that holds one; omitted means the SDK picks the first offer.

Output — the value assertions and returns: read

Everything the DSP flow produced, from the catalog through to the token.

Field	Type	Description
dataplane_url	string	Data-plane URL the negotiated data is fetched from.
edr_token	string	Authorization token for that URL.
token_prefix	string	First characters of the token, safe to log or assert on.
catalog	object	Catalog document the offer was taken from.
datasets	list of object	Dataset offers in that catalog.
asset_id	string	Asset ID of the first offer.
negotiation_id	string	ID of the negotiation the flow ran.
agreement_id	string	ID of the contract agreement the negotiation produced.
transfer_id	string	ID of the transfer process the flow ran.

connector/consumer/pull_data_filtered_by_policy

Run the full DSP flow, accepting an offer that matches any of several policies.

Unlike pull_data_filtered, where expected_policies is optional and "no policies" means "take the first offer", this variant requires them. They are normalised the same way, so either spelling is accepted.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
max_wait	number	no	60.0	—	Seconds to wait for the transfer to complete.
poll_interval	number	no	1.0	—	Seconds between transfer-state polls.
expected_policies	list of object	yes	—	—	Policies, any one of which the negotiated offer must satisfy, in any of the forms 'pull_data_filtered' accepts.

Output — the value assertions and returns: read

Everything the DSP flow produced, from the catalog through to the token.

Field	Type	Description
dataplane_url	string	Data-plane URL the negotiated data is fetched from.
edr_token	string	Authorization token for that URL.
token_prefix	string	First characters of the token, safe to log or assert on.
catalog	object	Catalog document the offer was taken from.
datasets	list of object	Dataset offers in that catalog.
asset_id	string	Asset ID of the first offer.
negotiation_id	string	ID of the negotiation the flow ran.
agreement_id	string	ID of the contract agreement the negotiation produced.
transfer_id	string	ID of the transfer process the flow ran.

connector/consumer/query_catalog

Query a provider's catalog via the SDK connector consumer service.

Returns the catalog document and its offers side by side, so a returns: block reads datasets rather than the JSON-LD key the provider's DSP generation happens to spell them with, and downstream steps read the same offers.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
protocol	string	no	''	—	DSP protocol version the request is made under, e.g. 'dataspace-protocol-http:2025-1'. Left empty, the connector's dataspace version decides it.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.

Output — the value assertions and returns: read

What every catalog query returns: the document, and its offers as a list.

Field	Type	Description
catalog	CatalogPayload	The provider's catalog document, unchanged.
datasets	list of object	Dataset offers from the catalog, always as a list.

connector/consumer/query_catalog_by_asset_id

Query the catalog filtered by a specific asset ID.

Returns the catalog's first offer as catalog_asset_id / catalog_policy for the negotiation step that follows. Which policy that offer carries is reported, not judged: a step that asserts on the policy reads it from the output, and a step that must only accept certain policies is pull_data_filtered_by_policy.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
protocol	string	no	''	—	DSP protocol version the request is made under, e.g. 'dataspace-protocol-http:2025-1'. Left empty, the connector's dataspace version decides it.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.
asset_id	string	yes	—	—	Asset ID the catalog is filtered by.

Output — the value assertions and returns: read

Output contract of connector/consumer/query_catalog_by_asset_id.

Field	Type	Description
catalog	CatalogPayload	The provider's catalog document, unchanged.
datasets	list of object	Dataset offers from the catalog, always as a list.
catalog_asset_id	any	Asset ID of the first offer in the catalog.
catalog_policy	any	The ODRL policy that offer is made under.

connector/consumer/query_catalog_by_bpnl

Query the catalog using BPNL-based connector discovery.

Alone among the catalog steps this takes no protocol: discovery is what answers with one, so a protocol given here would be an assumption competing with the connector's own answer. Pin it by discovering explicitly with connector/consumer/discover_connector and passing the endpoint it resolves to query_catalog.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
bpnl	string	yes	—	—	BPN used to discover the counter-party's connector.
counter_party_address	string	no	None	—	DSP endpoint to discover against, as its root or as the versioned endpoint the SUT binding carries — a trailing version path is dropped, since discovery is what appends it. When omitted it is resolved from the BPN alone.
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.

Output — the value assertions and returns: read

What every catalog query returns: the document, and its offers as a list.

Field	Type	Description
catalog	CatalogPayload	The provider's catalog document, unchanged.
datasets	list of object	Dataset offers from the catalog, always as a list.

connector/consumer/query_catalog_with_filters

Query a provider's catalog with multiple filter expressions via the SDK.

Filter criteria are translated by the SDK's own get_filter_expression, so they carry whatever JSON-LD context the negotiated dataspace version expects.

Inputs

Parameter	Type	Required	Default	Also accepts	Description
protocol	string	no	''	—	DSP protocol version the request is made under, e.g. 'dataspace-protocol-http:2025-1'. Left empty, the connector's dataspace version decides it.
filters	list of FilterExpression	no	[]	—	Filter criteria applied to the catalog request.
counter_party_address	string	no	''	—	DSP endpoint of the counter-party connector; defaults to the bound SUT connector's 'dsp_url'.
counter_party_id	string	no	''	—	Dataspace identity of the counter-party; defaults to the bound SUT connector's 'participant_id'.

Output — the value assertions and returns: read

What every catalog query returns: the document, and its offers as a list.

Field	Type	Description
catalog	CatalogPayload	The provider's catalog document, unchanged.
datasets	list of object	Dataset offers from the catalog, always as a list.

Nested objects

CatalogPayload

A provider's DCAT catalog.

Field	Type	Required	Default	Also accepts	Description
@context	any	no	None	—	JSON-LD context.
@id	string	no	None	—	Catalog ID.
@type	any	no	None	—	JSON-LD type.

Additional keys sent by the counterpart are passed through unchanged.

DataAddressPayload

An EDR data address — where negotiated data is fetched and with what token.

Field	Type	Required	Default	Also accepts	Description
endpoint	string	no	None	—	Data-plane URL to fetch the data from.
authorization	string	no	None	—	Authorization token for that URL.
authCode	string	no	None	—	Legacy spelling of 'authorization' used by older connectors.

Additional keys sent by the counterpart are passed through unchanged.

FilterExpression

One catalog filter criterion.

Field	Type	Required	Default	Also accepts	Description
operand_left	string	yes	—	—	Left-hand property of the criterion, e.g. 'https://w3id.org/edc/v0.0.1/ns/id'.
operator	string	no	'='	—	Comparison operator.
operand_right	any	no	''	—	Value the left-hand property is compared against.