Prometheus-X Components & Services
Consent/contracts negotiating agent BB – Design Document
The Consent/Contracts Negotiating Agent streamlines the process for individuals to set consent preferences regarding data usage, automates responses to consent requests from managers, and matches individuals with relevant services based on their consent profiles. Additionally, it assists organizations in negotiating and managing contractual agreements for data sharing within the dataspace ecosystem.
Its components encompass consent preference settings, service matching capabilities, communication with consent managers, contract profile management, and the provision for organizations to define default rules and conditions for contractual agreements.
Technical usage scenarios & Features
The Consent/Contracts Negotiating Agent empowers individuals and data providers to manage consent preferences, discover suitable services, and negotiate data sharing agreements within dataspace ecosystems. It facilitates automatic matching and recommendation processes based on an individual’s consent profile and organizations’ data sharing agreements.
Features/main functionalities
- Empowers individuals to set consent preferences for data usage.
- Automatic matching and recommendation process based on consent profiles and data sharing agreements.
- Communication with consent managers to handle consent requests and responses.
- Integration with dataspace ecosystems to ensure compatibility with ecosystem conditions.
- Provision for organizations to define default rules and conditions for contractual agreements.
Technical usage scenarios
- Enable individuals to manage their consent preferences efficiently and effectively.
- Facilitate automatic matching of individuals’ consent profiles with the conditions of dataspace ecosystems.
- Recommend the best services to individuals based on their needs and the permissibility of the data.
- Streamline the process of handling consent requests and responses between individuals and consent managers.
- Provide organizations with the capability to establish default rules and conditions for contractual agreements, ensuring compliance and consistency.
Requirements
| Requirement ID | Short Description | BB Input Format | BB Output Format | Requirement Type |
|---|---|---|---|---|
| BB-REQ_ID__1 | Must enable individuals to set and manage consent preferences for data usage | REST API call | REST API response | Functional (FUN) |
| BB-REQ_ID__2 | Must facilitate automatic matching and recommendation processes based on consent profiles and organizations’ data sharing agreements | REST API call | REST API response | Functional (FUN) |
| BB-REQ_ID__3 | Must communicate effectively with consent managers to handle consent requests and responses | REST API call | REST API response | Dependency, Functional (DEP, FUN) |
| BB-REQ_ID__4 | Must integrate seamlessly with dataspace ecosystems to ensure compatibility with ecosystem conditions | REST API call | REST API response | Dependency (DEP) |
| BB-REQ_ID__5 | Must provide configuration options for organizations to define default rules and conditions for contractual agreements | REST API call | REST API response | Functional (FUN) |
| BB-REQ_ID__6 | Should be able to process both bilateral and data space use case data sharing agreements | REST API call | REST API response | Dependency, Functional (DEP, FUN) |
Integrations
Direct Integrations with Other BBs
Core Building Blocks
Interaction with other building blocks are essential to ensuring the functionalities of Consent / Contract Negotiating Agent as it needs to be able to read from consents and contracts, as well as read information from the catalogue.
Integrations via Connector
This building block is not aimed to have a connector integration as it will be intimitely linked to the Consent and Contract building blocks which exist outside of the connector.
It will however be a source of data exchange trigger which will enable the Consent service to notify the connectors of the data exchange following the protocol defined in the consent building block.
Relevant Standards
Data Format Standards
- JSON-LD for schema definitions
- ISO 3166-1 alpha-2 for location country codes
- ISO 8601 for Date and time format
- ODRL for contract policies
Input / Output Data
This Building Block reads from existing contracts generated by the Contract building block and existing consent from the Consent building block.
Matching
Consent Matching
The consent negotiating agent interacts with the catalog to identify similar types of data and services based on individuals’ consent preferences. By analyzing consent profiles, the agent discerns the authorization levels, conditions, and preferences set by individuals regarding data usage.
Leveraging this information, it proposes potential data exchanges to individuals, recommending suitable data sources or services that align with their consent preferences. This process ensures that individuals have access to relevant and permissible data within the dataspace.
Contract Matching
The contract negotiating agent utilizes the catalog to identify comparable data categories and services based on organizations’ contract profiles. By examining the ODRL policies and values specified in the contract profiles, the agent identifies relevant organizations and datasets that align with the contractual agreements and obligations defined by the organizations.
It then proposes potential partners or datasets to organizations, facilitating streamlined negotiations and partnerships within the dataspace.
This approach enables organizations to efficiently discover and engage with compatible partners and datasets, optimizing data sharing and utilization while ensuring adherence to contractual agreements and regulatory requirements.
Streamlining Negotiation Process
sequenceDiagram
participant org as Organization
participant ca as Contract Agent
participant cat as Catalog Integration
org->>ca: Initiate negotiation with new organization
ca->>cat: Access contract profiles from catalog
cat-->>ca: Contract profiles retrieved
ca->>org: Pre-set ODRL policies and values based on contract profiles
Recommendations of Data Exchanges
sequenceDiagram
participant org as Organization
participant ca as Contract Agent
participant cat as Catalog Integration
org->>ca: Request recommendations for data exchanges/services
ca->>cat: Access contract profiles from catalog
cat-->>ca: Contract profiles retrieved
ca->>ca: Analyze ODRL policies and values in contract profiles
ca->>cat: Request data exchanges/services recommendations based on contract profiles
cat-->>ca: Data exchanges/services recommendations
ca-->>org: Provide recommendations based on contract profiles
Architecture
- Negotiating Agents: The core components responsible for managing consent and contract negotiations. These agents communicate with individuals, organizations, and the catalog to gather and analyze consent preferences and contract profiles.
- Catalog Integration: Integration with the catalog system to access metadata about available data sources, services, and organizations within the dataspace. This integration enables the negotiating agents to identify relevant data and services based on consent preferences and contract profiles.
- Consent Management Module: A module responsible for managing consent preferences of individuals. It allows individuals to set and update their consent preferences, including authorization levels and conditions for data uage.
- Contract Management Module: A module dedicated to managing contract profiles of organizations. It enables organizations to define ODRL policies and values for data categories and services, facilitating streamlined negotiations with potential partners.
- Communication Interface: An interface for communication between the negotiating agents, individuals, organizations and the catalog. This interface ensures seamless exchange of consent preferences, contract profiles, and negotiation proposals.
- Data Exchange Proposals: Components responsible for generating data exchange proposals for individuals based on their consent preferences and for proposing relevant organizations or datasets to organizations based on their contract profiles.
- Authorization Level Evaluation: Components for evaluating authorization levels and conditions specified in consent preferences and contract profiles. These components determine the permissibility of data exchanges and partnerships.
- Logging: Mechanisms for logging operations and monitoring the performance of the agents and related components.
- Error Handling & Recovery: Strategies and mechanisms for handling errors and recovering from failures gracefully.
classDiagram
class ConsentContractNegotiatingAgent {
- ConsentManagementModule consentModule
- ContractManagementModule contractModule
- CatalogIntegration catalogIntegration
- CommunicationInterface communicationInterface
- DataExchangeProposals dataExchangeProposals
- AuthorizationLevelEvaluation authorizationEvaluation
- LoggingMonitoring loggingMonitoring
- ErrorHandlingRecovery errorHandlingRecovery
}
class ConsentManagementModule {
+ setConsentPreferences()
+ updateConsentPreferences()
}
class ContractManagementModule {
+ setContractProfile()
+ updateContractProfile()
}
class CatalogIntegration {
+ accessMetadata()
}
class CommunicationInterface {
+ exchangeData()
}
class DataExchangeProposals {
+ generateProposals()
}
class AuthorizationLevelEvaluation {
+ evaluateAuthorization()
}
class LoggingMonitoring {
+ logOperations()
+ monitorPerformance()
}
class ErrorHandlingRecovery {
+ handleErrors()
+ recoverFromFailures()
}
ConsentContractNegotiatingAgent --> ConsentManagementModule
ConsentContractNegotiatingAgent --> ContractManagementModule
ConsentContractNegotiatingAgent --> CatalogIntegration
ConsentContractNegotiatingAgent --> CommunicationInterface
ConsentContractNegotiatingAgent --> DataExchangeProposals
ConsentContractNegotiatingAgent --> AuthorizationLevelEvaluation
ConsentContractNegotiatingAgent --> LoggingMonitoring
ConsentContractNegotiatingAgent --> ErrorHandlingRecovery
Dynamic Behaviour
This statechart shows the internal state changes of the component.
---
title: Setting of authorization level in consent preferences
---
stateDiagram-v2
[*] --> ManualConsent: Default State
ManualConsent --> AutomaticConsent: Authorization Level "always"
ManualConsent --> ConditionalConsent: Authorization Level "conditional"
ConditionalConsent --> ManualConsent: Conditions Not Met
ConditionalConsent --> AutomaticConsent: Conditions Met
AutomaticConsent --> ManualConsent: Authorization Level Changed to "conditional"
ConditionalConsent --> AutomaticConsent: Authorization Level Changed to "always"
Communication with other components
Verification of consent preferences to automate consent grant
sequenceDiagram
participant i as Individual
participant pdi as Personal Data Intermediary
participant ccna as Consent Negotiating Agent
i->>pdi: Request data sharing from <br>Data Provider to Data Consumer
pdi->>ccna: Send Consent
ccna->>ccna: Verify authorization level on <br>the user consent preferences
alt Authorization Level "always"
ccna-->>pdi: Consent granted automatically
else Authorization Level "never"
ccna-->>i: Request manual consent grant
else Authorization Level "conditional"
ccna->>ccna: Check conditions
alt Conditions Met
ccna-->>pdi: Consent granted automatically
else Conditions Not Met
ccna-->>i: Request manual consent grant
end
end
Technical Specifications
Consent Agent
graph TD
subgraph ConsentManager["Consent - Manager"]
subgraph ConsentAgent["Consent Agent"]
Algorithms["Algorithms<br/>(Consent preferences,<br/>consent matching,<br/>negotiation agent,<br/>Data exchanges recommendations)"]
API
Algorithms <--> API
end
end
MongoDB[(consent-manager<br/>mongodb)]
AtlasSearch[(Atlas Search)]
MongoDB <--> ConsentManager
AtlasSearch --> |consent<br/>& Data exchanges| ConsentManager
Consent preferences
Entities in the consent preferences are defined by the following UML diagram
classDiagram
class Data {
id: string/uri
authorizationLevel: string
conditions: Condition[]
}
class Service {
id: string/uri
authorizationLevel: string
conditions: Condition[]
}
class Participant {
id: string/uri
asDataProvider: Data
asServiceProvider: Service
}
class Condition {
time: TimeCondition
location: LocationCondition
}
class TimeCondition {
dayOfWeek: string[]
startTime: string
endTime: string
}
class LocationCondition {
countryCode: string
}
Participant -- Data
Participant -- Service
Condition -- TimeCondition
Condition -- LocationCondition
Service -- Condition
Data -- Condition
User input will allow setting the consent profile preferences. An example of a simple consent profile would follow the following structure:
API Endpoints
The agent provides API endpoints through the consent manager to give access to the algorithm’s output and to give access to the preferences options.
Get Recommendations
- GET /recommendations/:profileId/consent
Output example
```json { "consentRecommendations": ["6675866105d813cd97de8171"] } ```
Get Recommendations
- GET /recommendations/:profileId/dataexchanges
Output example
```json { "dataExchangesRecommendations": ["6675866105d813cd97de8171"] } ```
Consent preferences
-
GET /preferences/:id
-
POST /preferences
-
PUT /preferences/:id
-
DELETE /preferences/:id
Output example
```json { "id": "667bc534e22d10c930808556", "asDataProvider": { "id": "667bc534e22d10c930808556", "authorizationLevel": "always", "conditions": [ { "time": { "dayOfWeek": ["0"], "startTime": "2024-03-27T14:08:19.986Z", "endTime": "2025-03-27T14:08:19.986Z" }, "location": { "countryCode": "US" } } ] }, "asServiceProvider": { "id": "667bc534e22d10c930808556", "authorizationLevel": "always", "conditions": [ { "time": { "dayOfWeek": ["0"], "startTime": "2024-03-27T14:08:19.986Z", "endTime": "2025-03-27T14:08:19.986Z" }, "location": { "countryCode": "US" } } ] }, "configurations": { "allowRecommendations": true, "allowPolicies": true } } ```
Contract Agent
graph TD
subgraph ContractManager["Contract - Manager"]
subgraph ContractAgent["Contract Agent"]
Algorithms["Algorithms<br/>(Profile management,<br/>recommendation logic,<br/>policies management)"]
API
Algorithms <--> API
end
end
MongoDB[(contract-manager<br/>mongodb)]
AtlasSearch[(Atlas Search)]
MongoDB <--> ContractManager
AtlasSearch --> |recommendations<br/>& policies| ContractManager
Contract Profiles
For organizations within the dataspace, they are subject to negotiate and contractualise for the usage of their data or services under a certain set of ODRL policies. The contract profile and agent would enable a streamlined experience in setting up ODRL policies and their values when negotiating with new organisations if similar data or services has been configured within the contract profile.
classDiagram
class Policies {
+policy: string
+frequency: int
}
class Recommendations {
+policies: [Policies]
+ecosystemContracts: [string]
}
class profiles {
+_id: ObjectId
+url: string
+recommendations: [Recommendations]
+configurations: configurations
}
class Configurations {
+allowRecommendation: boolean
+allowPolicies: boolean
}
profiles "1" -- "1" Configurations
profiles "1" -- "*" Recommendations
Recommendations "1" -- "*" Policies
Organizations can create a contract profile where they define various data categories and services they offer or utilize. For each data category and service, organizations specify the corresponding ODRL policies, including permissions, prohibitions, obligations, and constraints. When negotiating with new organizations or entities, the contract negotiating agent leverages these pre-configured contract profiles. It identifies similarities between the data categories and services involved, utilizing existing policies and values whenever possible to expedite the negotiation process. This approach not only accelerates negotiation but also ensures consistency and compliance across contractual agreements within the dataspace ecosystem.
API Endpoints
The agent provides API endpoints through the contract manager to give access to the algorithm’s output and to give access to the configuration options.
Get Recommendations
- GET /recommendations/:profileId/contracts
Output example
```json { "contractsRecommendations": ["6675866105d813cd97de8171"] } ```
Get Policies
- GET /policies/:profileId
Output example
```json { "policies": ["6675867c2ef5d0e40b021e6b"] } ```
Profile Configurations
-
GET /profile/:id/configurations
-
POST /profile/configurations
-
PUT /profile/:id/configurations
-
DELETE /profile/:id/configurations
Output example
```json { "configurations": { "allowRecommendations": true, "allowPolicies": true } } ```
Library Setup - Example
Setting up the agent would look something like the following:
Although this is still at a specification level and can change, having an example setup helps to visualise the implication for setup in the other building blocks.
pnpm install contract-agent
Initialization Example
import { initializeConsentAgent } from "contract-consent-agent";
const express = require("express");
const mongoose = require("mongoose");
const app = express();
await mongoose.connect(url, { retryWrites: true });
const consentAgent = initializeConsentAgent(mongoose);
// ...other app code...
app.listen(3000, () => {
console.log("Server is running on port 3000");
});
API Integration Example
The library is expected to return a router used by the consent manager. Here is what it could look like
import { initializeConsentAgent } from "contract-consent-agent";
const express = require("express");
const mongoose = require("mongoose");
const app = express();
await mongoose.connect(url, { retryWrites: true });
const consentAgent = initializeConsentAgent(mongoose);
// ...other app code...
app.use("/", authMiddleware, consentAgent.router);
app.listen(3000, () => {
console.log("Server is running on port 3000");
});
Search Module for Contrat and Consent Agents
Objective
Provide an interface to search documents in the selected search engine (Atlas Search) in order to highlight suggestions or specific elements that might be found within the documents (ex: suggesting an ecosystem contract for a user, retrieving policies associated with a user).
Main Features
- API for document suggestion queries, precise document searches, or searches for sub-elements such as policies.
- Accept search parameters (filters, scoring, etc.).
- Execute queries on the search engine and return the results.
- Set up search profiles if necessary:
- Define search profiles for the relevant documents based on the required return format.
- Set up the search API:
- Implement a search interface (API) allowing the search for documents and sub-elements based on specific criteria.
Atlas Search Example
[
{
"$search": {
"index": "contracts",
"moreLikeThis": {
"like": [
{
"serviceOfferings.policies.description": "MUST use data for a specified time period"
}
]
}
}
},
{
"$limit": 5
},
{
"$project": {
"serviceOfferings": 1,
"score": { "$meta": "searchScore" }
}
}
]
Algorithms
The algorithms need to respond to the previous described requirements. To do so we will use Atlas search and its functionality to empower the recommendations and the matching.
Profile Algorithms Execution
This algorithm will create and manage the Contract profiles
See input/output example
Input ```json { "_id": "6661c8e34371f3eabe3ddfde", "createdAt": "2024-06-06T14:34:11.128Z", "ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536", "members": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "role": "orchestrator", "signature": "hasSigned", "date": "2024-06-06T14:34:16.722Z" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "role": "participant", "signature": "hasSigned", "date": "2024-06-06T14:35:51.524Z" } ], "orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "purpose": [], "revokedMembers": [], "rolesAndObligations": [], "serviceOfferings": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c8fb4371f3eabe3ddfea" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c9474371f3eabe3ddff0" } ], "status": "signed", "updatedAt": "2024-06-06T14:35:51.522Z" } ``` Output ```json [ { "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { "policies": [ { "policy": "MUST not use data for more than n times", "frequency": 1 } ], "ecosystemContracts": [] } ], "matching": [ { "policies": [], "ecosystemContracts": [] } ] }, { "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { "policies": [ { "policy": "MUST not use data for more than n times", "frequency": 1 } ], "ecosystemContracts": [] } ], "matching": [ { "policies": [], "ecosystemContracts": [] } ] } ] ```
Consent / contract Recommendation
This algorithm will handle the recommendations by sending a query to Altas Search and saving the results.
See input/output example
Input ```json { "_id": "6661c8e34371f3eabe3ddfde", "createdAt": "2024-06-06T14:34:11.128Z", "ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536", "members": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "role": "orchestrator", "signature": "hasSigned", "date": "2024-06-06T14:34:16.722Z" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "role": "participant", "signature": "hasSigned", "date": "2024-06-06T14:35:51.524Z" } ], "orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "purpose": [], "revokedMembers": [], "rolesAndObligations": [], "serviceOfferings": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c8fb4371f3eabe3ddfea" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c9474371f3eabe3ddff0" } ], "status": "signed", "updatedAt": "2024-06-06T14:35:51.522Z" } ``` Output ```json [ { "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { ...other fields "ecosystemContracts": [ "66796b01cbcaf23233cf4de1" ] } ], ...other fields }, { "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { ...other fields "ecosystemContracts": [ "66796b16b11a476c352a68bc" ] } ], ...other fields } ] ```
Consent / Contract Matching
See input/output example
Input ```json { "_id": "6661c8e34371f3eabe3ddfde", "createdAt": "2024-06-06T14:34:11.128Z", "ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536", "members": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "role": "orchestrator", "signature": "hasSigned", "date": "2024-06-06T14:34:16.722Z" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "role": "participant", "signature": "hasSigned", "date": "2024-06-06T14:35:51.524Z" } ], "orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "purpose": [], "revokedMembers": [], "rolesAndObligations": [], "serviceOfferings": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c8fb4371f3eabe3ddfea" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c9474371f3eabe3ddff0" } ], "status": "signed", "updatedAt": "2024-06-06T14:35:51.522Z" } ``` Output ```json [ { "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "configurations": { "allowRecommendation": true, "allowPolicies": true }, ...other fields "matching": [ { "policies": [ { "policy": "MUST not use data for more than n times" }, ], "ecosystemContracts": [ "66796b01cbcaf23233cf4de1" ] } ] }, { "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "configurations": { "allowRecommendation": true, "allowPolicies": true }, ...other fields "matching": [ { "policies": [ { "policy": "MUST not use data for more than n times" }, ], "ecosystemContracts": [ "66796b16b11a476c352a68bc" ] } ] } ] ```
Policies Algorithms Execution
See input/output example
Input ```json { "_id": "6661c8e34371f3eabe3ddfde", "createdAt": "2024-06-06T14:34:11.128Z", "ecosystem": "https://catalog.com/v1/catalog/ecosystems/6661c8e32ea0e41164285536", "members": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "role": "orchestrator", "signature": "hasSigned", "date": "2024-06-06T14:34:16.722Z" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "role": "participant", "signature": "hasSigned", "date": "2024-06-06T14:35:51.524Z" } ], "orchestrator": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "purpose": [], "revokedMembers": [], "rolesAndObligations": [], "serviceOfferings": [ { "participant": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3ed6a5aa76c541b64a79", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c8fb4371f3eabe3ddfea" }, { "participant": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "serviceOffering": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "policies": [ { "description": "MUST not use data for more than n times", "permission": [ { "action": "use", "target": "https://catalog.com/v1/catalog/serviceofferings/664f3e4ea5aa76c541b640bb", "constraint": [ { "leftOperand": "count", "operator": "lt", "rightOperand": 10 } ] } ], "prohibition": [] } ], "_id": "6661c9474371f3eabe3ddff0" } ], "status": "signed", "updatedAt": "2024-06-06T14:35:51.522Z" } ``` Output ```json [ { "url": "https://catalog.com/v1/catalog/participants/6564abb5d853e8e05b132057", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { "policies": [ { "policy": "MUST not use data for more than n times", "frequency": 2 }, ], ...other fields } ], ...other fields }, { "url": "https://catalog.com/v1/catalog/participants/6564aaebd853e8e05b1317c1", "configurations": { "allowRecommendation": true, "allowPolicies": true }, "recommendations": [ { "policies": [ { "policy": "MUST not use data for more than n times", "frequency": 2 }, ], ...other fields } ], ...other fields } ] ```
Change Stream
The change stream is a MongoDB functionality that allows listening to events from collections (insert, update, delete, …). This way we can manage to process the algorithm whenever we want through the entities lifecycle to keep the profiles up to date and give real time recommendations and matching.
3 potential events can be listened to for the contract agent:
- Creation or signature of bilateral: create a new profile or update the profile policies preferences.
- Signature of ecosystem contract for the policies and preferences of the ecosystem: create a new profile or update the policies preferences and recommendations.
- Revocation of ecosystem contract: update profile recommendations.
3 potential events can be listened to for the consent agent:
- Consent given: create a new profile or update the profile policies preferences.
- New data exchanges created: create a new profile or update the policies preferences and recommendations.
- Consent status changed: update profile recommendations.
Change Stream Handling
The agent will handle the change stream event provided by mongodb or mongoose (same usage).
const { MongoClient } = require("mongodb");
async function watchCollection(dbUrl, dbName, collectionName, onChange) {
const client = new MongoClient(dbUrl, {
useNewUrlParser: true,
useUnifiedTopology: true,
});
try {
await client.connect();
console.log("Connected to MongoDB");
const db = client.db(dbName);
const collection = db.collection(collectionName);
const changeStream = collection.watch();
changeStream.on("change", (change) => {
console.log("Change detected:", change);
onChange(change);
});
console.log(`Watching collection: ${collectionName}`);
} catch (err) {
console.error(err);
}
}
Example of a signature applied to a use case contract Workflow
sequenceDiagram
actor External
participant CM as Contract-manager
participant DB as Database
box rgb(33,66,99) Contract-Agent
participant CS as Change stream
participant PA as Profile algorithm
participant R as Recommendation
participant AS as Atlas Search
end
External->>CM: sign dsuo contract
CM->>DB: update document
DB->>CS: event
CS->>PA: Execute
PA->>PA: check if profile exists
PA->>DB: query
DB-->>PA: Profil
alt
PA->>PA: profile doesn't exists
PA->>CM: Create profile
end
CS->>R: Execute
R->>AS: Query
AS-->>R: Results
R->>DB: Update document
CM->>AS: Query
AS-->>DB: Update document
Example of a consent given
sequenceDiagram
actor External
participant CM as Consent-manager
participant DB as Database
box rgb(33,66,99) Consent-Agent
participant CS as Change stream
participant PA as Matching
participant R as Recommendation
participant AS as Atlas Search
end
External->>CM: give consent
CM->>DB: update document
DB->>CS: event
CS->>PA: Execute
PA->>PA: check if preferences exists
PA->>DB: query
DB-->>PA: preferences
alt
CS->>R: Execute
R->>AS: Query
AS-->>R: Results
R->>DB: Update document
end
Configuration and deployment settings
Logging and Operations
The Consent/Contracts Negotiating Agent logs operations, errors, and warnings to designated log files. Logging includes details such as consent requests, contract negotiations, integration errors, and system status updates. Error scenarios, such as failed consent requests or contract validation errors, are logged with appropriate error codes and descriptions to aid in troubleshooting and debugging.
Limits and Usage Constraints
The Consent/Contracts Negotiating Agent imposes certain limits and usage constraints to ensure efficient operation and resource allocation within the dataspace ecosystem. These limits may include maximum concurrent requests, maximum dataset size for contract profiles, and rate limiting for API calls to external systems. Additionally, the agent may enforce authentication and access control mechanisms to protect sensitive data and ensure compliance with regulatory requirements. Configuration options for these limits and constraints can be adjusted based on deployment requirements and scalability considerations.
OpenAPI Specification
TODO When ready.
Third Party Components & Licenses
| Component | Link | License |
|---|---|---|
| Atlas Search | https://www.mongodb.com/products/platform/atlas-search | Proprietary license |
Test specification
Test plan
The testing strategy for the Consent/Contracts Negotiating Agent will focus on ensuring the correctness, reliability, and performance of its functionalities. We will employ a combination of unit tests, integration tests, and possibly UI tests where relevant. The testing environment will replicate production-like conditions to validate the agent’s behavior accurately. Acceptance criteria will be defined based on user stories, functional requirements, and performance benchmarks.
Unit tests
For unit testing, we will utilize the Mocha testing framework along with Chai for assertions. The test cases will cover individual components and modules of the Consent/Contracts Negotiating Agent, including consent management, contract profile management, catalog integration, communication interface, and data exchange proposals. Mocking frameworks like Sinon may be used to isolate dependencies and simulate external interactions.
Integration tests
Integration tests will focus on validating the interaction between different components of the Consent/Contracts Negotiating Agent. We will use tools such as Postman for API testing to verify communication interfaces and data exchange protocols. Additionally, integration tests will ensure seamless integration with external systems like consent managers and catalog APIs. Continuous Integration (CI) pipelines will be set up to automate the execution of integration tests.
UI test
UI tests will be defined for any user interfaces or administrative dashboards provided by the Consent/Contracts Negotiating Agent. Testing frameworks like Cypress will be used to automate UI interactions and validate the usability and functionality of the user interface. UI tests will cover scenarios such as consent preference settings, contract profile management, and error handling.
Partnerships & Roles
Visions
- Source code of the contract agent
- Source code of the consent agent
- Integration documentation of the agent in the contract-manager
- Integration documentation of the agent in the consent-manager
- Definition of the indexation for the search engines
- OpenAPI specification (integrated in the contract/consent managers)
- Provide first implementation solution through VisionsTrust services
IMC
- Ensure alignment with consent management development in Gaia-x and IDSA
- Specification design review
NomadLabs
- Provide decentralized data governance expertise
Usage in the Dataspace
The Consent/Contracts Agent significantly enhances the management of data usage and sharing agreements within the dataspace ecosystem. By automating consent and contract negotiations, it ensures compliance with predefined policies and conditions, streamlining the process for both individuals and organizations.
For individuals, the agent provides an intuitive interface to manage consent preferences, facilitating personalized service recommendations and enabling data exchanges that align with their consent profiles. Organizations benefit from the agent’s ability to streamline negotiations, applying consistent contractual agreements through the use of ODRL policies and values to identify relevant partners and datasets.
Through integration with the dataspace ecosystem, the agent guarantees compatibility with ecosystem conditions and regulatory requirements. This integration not only improves data governance but also promotes collaboration and innovation within the dataspace by enabling efficient and secure data exchanges.