Contract Management

The Contract Management Service uses events defined by the TM Forum API to reflect the state of a contract in a data space. Depending on the provided data, permission to grant specified VerifiableCredentials is set at a Trusted Issuers List API service implementation.

Installation

Container

The Contract Management Service is provided as a container at quay.io.

The container can be started with

docker run --network host quay.io/fiware/contract-management:0.0.1

Configuration

Configurations can be provided with the standard mechanisms of the Micronaut-Framework, e.g. environment variables or appliction.yaml file. The following table concentrates on the most important configuration parameters:

Property	Env-Var	Description	Default
micronaut.server.port	MICRONAUT_SERVER_PORT	Server port to be used for the listener endpoint.	8080
micronaut.metrics.enabled	MICRONAUT_METRICS_ENABLED	Enable the metrics gathering	true
micronaut.http.services.til.url	MICRONAUT_HTTP_SERVICES_TIL_URL	URL of the Trusted Issuers List Endpoint	http://trusted-issuers-list:8080
micronaut.http.services.til.path	MICRONAUT_HTTP_SERVICES_TIL_PATH	Subpath of the Trusted Issuers List Endpoint	""
micronaut.http.services.product.url	MICRONAUT_HTTP_SERVICES_PRODUCT_URL	URL of the TM Forum Product Order Endpoint	http://tmforum:8080
micronaut.http.services.product.path	MICRONAUT_HTTP_SERVICES_PRODUCT_PATH	Subpath of the TM Forum Product Order Endpoint	"productordering"
micronaut.http.services.party.url	MICRONAUT_HTTP_SERVICES_PARTY_URL	URL of the TM Forum Party Endpoint	http://tmforum:8080
micronaut.http.services.party.path	MICRONAUT_HTTP_SERVICES_PARTY_PATH	Subpath of the TM Forum Party Endpoint	"party"
general.name	GENERAL_NAME	Name of the service, used for the callback/listener subscription	contract-management
general.basepath	GENERAL_BASEPATH	Basepath used for the provided listener endpoint	""

Logging

Env-Var	Description	Default
LOG_FORMAT	TEXT for human readable lines, JSON for one JSON object per line (case-sensitive; an unknown value makes logback print why there is no output)	TEXT
LOG_LEVEL	Root log level	INFO
LOGGER_LEVELS_ORG_FIWARE_IAM	Level of the contract-management itself, e.g. DEBUG to trace how an order is resolved	INFO
HTTP_CLIENT_LOG_EXCEPTION	Add the stack trace to failed outgoing calls	false
LOG_LEVEL_MICRONAUT_HTTP_CLIENT	Level of micronaut's own http client logging (its connection errors duplicate the one-line WARN of the failed call)	OFF

Levels are used as follows:

• ERROR - the service itself is broken (e.g. an unexpected exception, a failed startup registration)
• WARN - something was not applied, always with the reason: a downstream service rejected a call (with its status and body), a configuration is invalid, an order handler failed
• INFO - business results: a notification was received, and one line per handled order
• DEBUG - how the result was reached: every outgoing call, the resolved specifications, policies and credentials, each policy created at the PAP and each issuer allowed at the TIL

Every line concerning an order starts with Order <id>:. A failing order handler is logged once, with its name and the reason, and each handled order ends with one line, e.g.

WARN  ProductOrderEventHandler - Order urn:ngsi-ld:product-order:1: completion failed in handler PapProductOrderHandler: [pap_rejected_policy] The PAP rejected policy p-1-urn:ngsi-ld:product-order:1 for assignee did:web:consumer.org. - downstream answered with status=400 body={"detail":"..."}
org.fiware.iam.exception.PapException: [pap_rejected_policy] The PAP rejected policy p-1-urn:ngsi-ld:product-order:1 for assignee did:web:consumer.org.
	at ...
WARN  ProductOrderEventHandler - Order urn:ngsi-ld:product-order:1: completion failed for customer urn:ngsi-ld:organization:2 in the handlers [PapProductOrderHandler].

Failures carry a machine-readable code in brackets ([organization_did_missing], [specification_not_resolvable], [til_rejected_issuer], ...), see org.fiware.iam.exception.FailureReason.

Development

In order to support the development, a local environment can be started via mvn clean install -Pdev.

Supported Events

Contract Management supports events from different parts of the TMForum API.

Catalog

In order to provide integration with the IDSA Protocols Catalog API, Catalog objects from TMForum are translated and pushed to Rainbow.

Create

When receiving a "CatalogCreateEvent", it tries to translate a TMForum Catalog into an IDSA Catalog. The Catalog tilte dctColonTitle is taken from the name property of the TMForum object.

StateChange

When receiving a "CatalogStateChangeEvent" the changes from the TMForum Catalog Object are updated within the IDSA Catalog Object.

Delete

The Catalog with the same id as the contained Catalog-Object will be deleted.

Product Offering

In order to provide integration with the IDSA Protocols Catalog API, Product Offering objects from TMForum are translated to Data Services in Rainbow.

Create

The "ProductOfferingCreateEvent" will be translated to Data Services and pushed to the Rainbow API. Only Offerings that are connected to an existing Catalog will be pushed. The offering requires a connected ProductSpecification, that contains productSpecCharacteristic if type:

endpointUrl: Will be used as "dcat:endpointURL" in the Data Service endpointDescription: Will be used as "dcat:endpointDescription" in the Data Service

StateChange

When receiving a "CatalogStateChangeEvent" the changes from the TMForum ProductOffering Object are updated within the IDSA Data Service Object.

Delete

The Data Service with the same id as the contained ProductOffering-Object will be deleted.

Quote

In order to support the IDSA Contract Negotiation the Contract Management integrates the TMForum Quote-API. See Dataspace Connector DSP Integration for more details.

Product Order

The Product Order Object is used to integrate the TMForum with the authentication and authorization components of the Dataspace Connector.

Create / StateChange

A Product Order event will update the contract negotiation in TMForum when a Quote-Object is connected. Beside that, only Product Orders in state "completed" will be handled.

In case of a "completed" Product Order, the Product Specification linked in either the specification or the connected Quote will be taken and any Specification Characteristic of type credentialsConfiguration will be inserted to the connected TrustedIssuers-List. Value can contain a list of Claim-Objects, as defined by the Trusted Issuers List API. An example specification would look like:

{
    "brand": "M&P Operations",
    "version": "1.0.0",
    "lifecycleStatus": "ACTIVE",
    "name": "M&P K8S",
    "productSpecCharacteristic": [
      {
        "id": "credentialsConfig",
        "name": "Credentials Config",
        "valueType": "credentialsConfiguration",
        "productSpecCharacteristicValue": [
          {
            "isDefault": true,
            "value": {
              "credentialsType": "OperatorCredential",
              "claims": [
                {
                  "name": "roles",
                  "path": "$.roles[?(@.target==\\\"my-target-service\\\")].names[*]",
                  "allowedValues": [
                    "OPERATOR"
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }

License

Trusted-Issuers-List is licensed under the MIT License. See LICENSE for the full license text.

© 2023 FIWARE Foundation e.V.