Skip to content

Commit

Permalink
Update changelog.md, README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@carlos-schmidt
carlos-schmidt committed Jun 29, 2023
2 parents e8255f6 + 02dca1f commit b44ee0b
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 34 deletions.
70 changes: 42 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,39 @@
# EDC Extension for Asset Administration Shell [![Build Status](https://github.com/FraunhoferIOSB/EDC-Extension-for-AAS/actions/workflows/gradle.yml/badge.svg)](https://github.com/FraunhoferIOSB/EDC-Extension-for-AAS/actions)

This [Eclipse Dataspace Connector (EDC)](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector) extension provides an easy way to share an [Asset Administration Shell (AAS)](https://www.plattform-i40.de/SiteGlobals/IP/Forms/Listen/Downloads/EN/Downloads_Formular.html?cl2Categories_TechnologieAnwendungsbereich_name=Verwaltungsschale) model via the EDC.

This [Eclipse Dataspace Connector (EDC)](https://github.com/eclipse-dataspaceconnector/DataSpaceConnector) extension
provides an easy way to share
an [Asset Administration Shell (AAS)](https://www.plattform-i40.de/SiteGlobals/IP/Forms/Listen/Downloads/EN/Downloads_Formular.html?cl2Categories_TechnologieAnwendungsbereich_name=Verwaltungsschale)
model via the EDC.

## Version compatibility

| Specification | Version |
|:-----------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| Eclipse Dataspace Connector | v0.0.1-milestone-8 |
| AAS - Details of the Asset Administration Shell - Part 1<br />The exchange of information between partners in the value chain of Industrie 4.0 | Version 3.0RC01<br />(based on [admin-shell-io/java-model](https://github.com/admin-shell-io/java-model)) |

## Repo Structure

The repository contains several material:

- `config`: Checkstyle files for code formatting
- `edc-extension4aas`: Source code for the extension
- `example`: Example use case for the edc-extension4aas with a preconfigured EDC launcher.
- `example`: Example use case for the edc-extension4aas with a preconfigured EDC launcher.

<!-- ------------------Template Section --------------------------- -->

## Example Usage

For a data transfer example using two connectors communicating with the IDS protocol, check the [Example's README](example/README.md).
For a data transfer example using two connectors communicating with the IDS protocol, check
the [Example's README](example/README.md).

## Functionality

AAS data can be shared over the EDC by linking an EDC Asset to the HTTP endpoint of the AAS element. Additionally, contracts have to be defined for each element.
In order to minimize configuration effort and prevent errors, this extension is able to link running AAS into EDC Assets. Furthermore, this extension can also start AAS by reading an AAS model. A default contract can be chosen to be applied for all elements. For critical elements, additional contracts can be placed.
AAS data can be shared over the EDC by linking an EDC Asset to the HTTP endpoint of the AAS element. Additionally,
contracts have to be defined for each element.
In order to minimize configuration effort and prevent errors, this extension is able to link running AAS into EDC
Assets. Furthermore, this extension can also start AAS by reading an AAS model. A default contract can be chosen to be
applied for all elements. For critical elements, additional contracts can be placed.
External changes to the model of an AAS are automatically synchronized by the Extension.

### Use Cases
Expand Down Expand Up @@ -73,35 +83,39 @@ Provide digital twin (AAS) data to business partners in Data Spaces like Catena-

### Configurations

| Key | Value Type | Description |
| :----| :-----------| :------|
|edc.aas.remoteAasLocation | URL | A URL of an AAS service (such as FA³ST service) that is already running and is conformant to official AAS API specification|
|edc.aas.localAASModelPath| path | A path to a serialized AAS environment compatible to specification version 3.0RC01 (see: https://github.com/FraunhoferIOSB/FAAAST-Service/blob/main/README.md)|
|edc.aas.localAASServicePort| (1-65535)| Port to locally created AAS service. Required, if localAASModelPath is defined and localAASServiceConfigPath is not defined.|
|edc.aas.localAASServiceConfigPath|path|Path to AAS config for locally started AAS service. Required, if localAASServicePort is not defined, but localAASModelPath is defined.|
|edc.aas.syncPeriod |whole number in seconds |Time period in which AAS services should be polled for structural changes (added/deleted elements etc.). Default value is 5 (seconds). Note: This configuration value is only read on startup, the synchronization period cannot be changed at runtime.|
|edc.aas.exposeSelfDescription| True/False| Whether the Self Description should be exposed on {edc}/api/selfDescription. When set to False, the selfDescription is still available for authenticated requests.|
|edc.aas.defaultAccessPolicyPath|path |Path to an access policy file (JSON). This policy will be used as the default access policy for all assets created after the configuration value has been set.|
|edc.aas.defaultContractPolicyPath|path |Path to a contract policy file (JSON). This policy will be used as the default contract policy for all assets created after the configuration value has been set.|
| Key | Value Type | Description |
|:----------------------------------|:------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| edc.aas.remoteAasLocation | URL | A URL of an AAS service (such as FA³ST service) that is already running and is conformant to official AAS API specification |
| edc.aas.localAASModelPath | path | A path to a serialized AAS environment compatible to specification version 3.0RC01 (see: https://github.com/FraunhoferIOSB/FAAAST-Service/blob/main/README.md) |
| edc.aas.localAASServicePort | (1-65535) | Port to locally created AAS service. Required, if localAASModelPath is defined and localAASServiceConfigPath is not defined. |
| edc.aas.localAASServiceConfigPath | path | Path to AAS config for locally started AAS service. Required, if localAASServicePort is not defined, but localAASModelPath is defined. |
| edc.aas.syncPeriod | whole number in seconds | Time period in which AAS services should be polled for structural changes (added/deleted elements etc.). Default value is 5 (seconds). Note: This configuration value is only read on startup, the synchronization period cannot be changed at runtime. |
| edc.aas.exposeSelfDescription | True/False | Whether the Self Description should be exposed on {edc}/api/selfDescription. When set to False, the selfDescription is still available for authenticated requests. |
| edc.aas.defaultAccessPolicyPath | path | Path to an access policy file (JSON). This policy will be used as the default access policy for all assets created after the configuration value has been set. |
| edc.aas.defaultContractPolicyPath | path | Path to a contract policy file (JSON). This policy will be used as the default contract policy for all assets created after the configuration value has been set. |
| edc.aas.defaultContractValidity | long value in seconds | "Number of seconds during which contract is valid starting from startDate." |

#### **Client Configurations**

| Key | Value Type | Description |
|:------------------------------------------| :-----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| edc.aas.client.waitForAgreementTimeout |whole number in seconds | How long should the extension wait for an agreement when automatically negotiating a contract? Default value is 10(s). |
| edc.aas.client.waitForTransferTimeout |whole number in seconds | How long should the extension wait for a data transfer when automatically negotiating a contract? Default value is 10(s). |
| edc.aas.client.waitForCatalogTimeout |whole number in seconds | How long should the extension wait for a catalog when automatically negotiating a contract? Default value is 10(s). |
| edc.aas.client.acceptAllProviderOffers |boolean| If true, the client accepts any contractOffer offered by a provider connector on automated contract negotiation (e.g., trusted provider). Default value: false |
| edc.aas.client.acceptedContractOffersPath |path| Path pointing to a JSON-file containing acceptable ContractOffers for automated contract negotiation in a list (only policies must match in a provider's ContractOffer) |
| Key | Value Type | Description |
|:------------------------------------------|:------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| edc.aas.client.waitForAgreementTimeout | whole number in seconds | How long should the extension wait for an agreement when automatically negotiating a contract? Default value is 10(s). |
| edc.aas.client.waitForTransferTimeout | whole number in seconds | How long should the extension wait for a data transfer when automatically negotiating a contract? Default value is 10(s). |
| edc.aas.client.acceptAllProviderOffers | boolean | If true, the client accepts any contractOffer offered by a provider connector on automated contract negotiation (e.g., trusted provider). Default value: false |
| edc.aas.client.acceptedContractOffersPath | path | Path pointing to a JSON-file containing acceptable ContractOffers for automated contract negotiation in a list (only policies must match in a provider's ContractOffer) |

## Terminology
| Term | Description |
| :----| :-----------|
|AAS | Asset Administration Shell (see [AAS reading guide](https://www.plattform-i40.de/IP/Redaktion/DE/Downloads/Publikation/Asset_Administration_Shell_Reading_Guide.html) or [AAS specification part 1](https://www.plattform-i40.de/IP/Redaktion/DE/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part1_V3.html)) |
|FA³ST Service | Open Source java implementation of the AAS part 2 see on [GitHub](https://github.com/FraunhoferIOSB/FAAAST-Service)|

| Term | Description |
|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| AAS | Asset Administration Shell (see [AAS reading guide](https://www.plattform-i40.de/IP/Redaktion/DE/Downloads/Publikation/Asset_Administration_Shell_Reading_Guide.html) or [AAS specification part 1](https://www.plattform-i40.de/IP/Redaktion/DE/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part1_V3.html)) |
| FA³ST Service | Open Source java implementation of the AAS part 2 see on [GitHub](https://github.com/FraunhoferIOSB/FAAAST-Service) |

## Roadmap

Features in development:
- Graphical interface to simplify providing and requesting AAS (see: https://github.com/FraunhoferIOSB/EDC-Extension-for-AAS-Dashboard)

- Graphical interface to simplify providing and requesting AAS (
see: https://github.com/FraunhoferIOSB/EDC-Extension-for-AAS-Dashboard)
- Built-in client to request AAS data from other EDC (automatic contract negotiation)
- Docker Hub container deployment
47 changes: 41 additions & 6 deletions changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,25 @@
# Changelog

## Current development version
## Current development version

Compatibility: **Eclipse Dataspace Connector v0.1.?**

**New Features**

**Bugfixes**

## V1.0.0-alpha3

This version is compatible to **Eclipse Dataspace Connection v0.0.1-Milestone 8**

**New Features**

* Support of **Eclipse Dataspace Connector v0.0.1-Milestone 8**

* Client Service
* Add custom HTTP endpoints for data transfers
* Add TLS/SSL config files
* Allows HTTPS communication between EDCs with non-self-signed certificates

**Bugfixes**

Expand All @@ -18,16 +29,38 @@
* Validity was set to max float value, is now set to 1 year (default)
* Dependencies
* Add data flow controller dependency
* Remove waiting for dataTransfer when specifying a custom data transfer target address
* Remove initial AAS service synchronization delay on connector startup
* Config
* Allow communication with DataDashboard (added to all configs except debug config)
* Synchronizer
* Extract AAS-EDC synchronizer to new class
* AAS service
* Prefer explicit service port to port inside AAS service configuration file
* Uploading accepted contracts required another dependency
* Update metamodel version

**Miscellaneous**

* Add missing license headers
* Client
* Reuse contractAgreements when available
* Clean up configuration class
* Improve test coverage
* Add missing license headers

## V1.0.0-alpha2

This version is compatible to **Eclipse Dataspace Connection v0.0.1-Milestone 7**

**New Features**

* Client Service
* Add functionality for automatically negotiating and requesting data from a provider EDC
* On automatic negotiation, provider contractOffers are matched against a set of own contractOffers (acceptedContractOffers)
* Provider data is sent to a specific client HTTP endpoint using a new authentication key for each transaction (derived from the agreementId)
* On automatic negotiation, provider contractOffers are matched against a set of own contractOffers (
acceptedContractOffers)
* Provider data is sent to a specific client HTTP endpoint using a new authentication key for each transaction (
derived from the agreementId)
* Add functionality for manually
* fetching a set of provider contractOffers for a provider asset,
* negotiating a contract with a provider using a contractOffer, returning an agreementId or an error message,
Expand All @@ -38,17 +71,19 @@ This version is compatible to **Eclipse Dataspace Connection v0.0.1-Milestone 7*
* CustomAuthenticationRequestFilter
* No requests were filtered when self description was exposed by config


## V1.0.0-alpha

This version is compatible to **Eclipse Dataspace Connection v0.0.1-Milestone 6**

**New Features**

* Custom AuthenticationRequestFilter
* Requests to the extension are now intercepted by a request filter
* Requests to all endpoints except `/api/selfDescription` require authentication
* The authentication method is defined within the launcher's build file. In the example launcher, a mocked identity and access management service is used: `_org.eclipse.edc:iam-mock_`
* Available authentication methods are defined by the EDC. For further information see the EDC's AuthenticationServices and AuthenticationRequestFilters.
* The authentication method is defined within the launcher's build file. In the example launcher, a mocked identity
and access management service is used: `_org.eclipse.edc:iam-mock_`
* Available authentication methods are defined by the EDC. For further information see the EDCs
AuthenticationServices and AuthenticationRequestFilters.

* Configuration value "exposeSelfDescription"
* Set to _False_ to not expose the extension's self descriptions
Expand Down

0 comments on commit b44ee0b

Please sign in to comment.