Document Parameterization via UI

[richardtreier]

Feature Request

Description

The idea is to improve our publicly available documentation regarding asset parameterization at the explicit request of the MDS.

Here is how the parameterization works right now:

• There are fields in the UI when selecting a HTTP Data asset to optionally enable the overridability of certain HTTP fields:
  • Method overridability, if enabled, a method MUST be set on the consumer side.
  • Path overridability, if enabled, an additional path will be appended.
  • Query Param overridability, if enabled, additional query params will be merged (and can override) the existing query params.
  • Request Body overridability, if enabled, request bodies can be overriden.
• There is a tricky interdependency between the request method and the request body. For example:
  • When using GET, HEAD or DELETE, or others (OPTIONS, maybe), there can't be a request body.
  • When using POST, PUT, PATCH, there must be a request body.
• If the validation of the parameters fails, the transfer process will be in the state of COMPLETE, but there won't be data arriving. This happens, because the validation only happens in the data plane, and can't reach the control plane.
• The above also happens, if for example the method is missing, because its parameterization was enabled.
• Our parameterization leaves special asset properties that tell consumers which parameterization is enabled. Currently they aren't displayed in the UI, this should be tracked in an issue.
• In general the idea is, that the parameterization of a data source should be addressed in the endpoint documentation link or description so that users can understand how to receive data from the asset they negotiated a contract for.
• In general there is a bug, that asset properties can't be shown on the consumer side, so that one will have to note down manually, which endpoint documentation an asset has / how to tranfser data from an asset.
• This all is unfortunate, but unavoidable right now.
• For the same previous reason it is currently not possible to show on consumption, which parts of the parameterization are enabled, despite us enriching the asset properties on the providing side when creating assets via our UI. Because of that we added a button "show all parameterization options" on data consumption, so one can "override" values for the parameterization in case the asset was created without the parameterization hint fields.

The above just to explains the current state of the feature. The idea is now to create an user documentation that describes to users how things work right now and the current technical limitations so that these do not end in bug requests.

Stakeholders

MDS

Solution Proposal and Work Breakdown

• Test the way parameterization works with two connectors (with the dev docker compose of edc-extensions and two webhook.site tabs), to understand the current limits from a user perspective.
• Refine the above information into a documentation article in our edc UI "docs/parameterized_assets.md"
• Clean up our edc-extensions documentation. They are currently in the wrong folder "docs/gettings-started/documentation". Instead we should have our documentation in just "docs" with a "docs/README.md" giving a list of articles with titles / links. The old files should be truncated to a message "this documentation was moved to ..." with links.
• Add a reference in our edc-extensions parameterized_assets documentation at the very top, saying that there is a documentation how to get things done with our UI.
• Add the same "directory" / index README.md with links to available articles for our EDC UI.
• Communicate / ask Jakob to communicate the available documentation to the MDS.
• Check edc-extensions / edc-ui for the "technical limitations" you've found out while finally refining the documentation. Each of these should have a bug issue with details created, so that the progress can be tracked. Also the causes of these technical limitations should be added to this issue Investigate EDC0 for known MS8 issues #387
• Also let @SebastianOpriel review the documentation for wording
• EDIT: We also need a full example, e.g. with the "Deutscher Wetterdienst" where we show how parameterization can be used to comfortably combine multiple data sets as one.