Arrowhead (and its continuation, Productive4.0) is an ambitious holistic innovation project, meant to open the doors to the potentials of Digital Industry and to maintain a leadership position of the industries in Europe. All partners involved will work on creating the capability to efficiently design and integrate hardware and software of Internet of Things (IoT) devices. Linking the real with the digital world takes more than just adding software to the hardware.

Please be aware, that versions starting from 4.1.3 are NOT backwards compatible with 4.1.2. If you have older systems please refer to the Migration Guide

1. Quick Start Guide
   1. Docker
      • System Requirements
      • Examples
      • Guide
      • Cheat-Sheet
      • Troubleshooting
   2. Debian Installer
   3. Compile Code
2. Migration Guide 4.1.2 -> 4.1.3
3. Certificates
4. Gatekeeper and Gateway Setup with ActiveMQ Relay
5. Continuous Integration / Continuous Delivery
6. How to Contribute
7. Documentation
   1. Service Registry
      • System Design Description Overview
      • Services and Use Cases
      • Security
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints
   2. Authorization
      • System Design Description Overview
      • Services and Use Cases
      • Service Description Overview
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints
   3. Orchestrator
      • System Design Description Overview
      • Services and Use Cases
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints
   4. EventHandler
      • System Design Description Overview
      • Services and Use Cases
      • Service Description Overview
      • Endpoints
        • Client
        • Management
        • Private
        • Removed Endpoints
   5. Gatekeeper
      • System Design Description Overview
      • Services and Use Cases
      • Endpoints
        • Client
        • Private
        • Management
        • Removed Endpoints
   6. Gateway
      • System Design Description Overview
      • Services and Use Cases
      • Endpoints
        • Client
        • Private
        • Management
   7. DataManager
      • System Design Description Overview
      • Services and Use Cases
      • Service Description Overview
      • Endpoints
        • Client
   8. TimeManager
      • System Design Description Overview
      • Services and Use Cases
      • Service Description Overview
      • Endpoints
        • Client
   9. Certificate Authority
      • System Design Description Overview
      • Services and Use Cases
      • Endpoints
        • Client
        • Private
        • Management
   10. Onboarding Controller
       • System Design Description Overview
       • Services and Use Cases
       • Security
       • Endpoints
         • Onboarding
   11. Device Registry
       • System Design Description Overview
       • Services and Use Cases
       • Security
       • Endpoints
         • Onboarding
         • Client
   12. System Registry
       • System Design Description Overview
       • Services and Use Cases
       • Security
       • Endpoints
         • Onboarding
         • Client
   13. Choreographer
       • System Design Description Overview
       • Services and Use Cases
       • Endpoints
       • Client
         • Management
   14. Plant Description Engine
   15. HawkBit Configuration Manager
   16. Device Hub with Eclipse Hono

Docker is a container platform that can be used to package and deploy applications in server environments, among other. In particular, the docker-compose utility may with advantage be used during application development to test integration with the Arrowhead Core systems. Here, we provide brief instructions on how to install and run both Docker and container images for the Arrowhead Core systems.

Note: A system with 4GB of RAM is advised.

• Docker
  • Ubuntu
  • Debian
  • Mac OS - Helpful tool for container management: Kitematic
  • Windows
• Docker Compose

cp scripts/initSQL.sh docker/
cd docker
./initSQL.sh

We provide two examples of how Docker containers can be used to host Arrowhead Core systems in this repository. The first one is located in the docker folder and the second one in the docker-all folder. The former example shows how some prebuilt Docker images can be used to bring up networks, while the second describes how a Docker image can be constructed that contains all Arrowhead Core systems. Please refer to those folders for more information. In particular, each folder contains its own README.md file with more instructions.

Note: Don't forget to set domain.name and domain.port properties!

Example Docker Compose file is located here. The interesting part is the volumes section. Format is /path/on/your/local/machine:/path/inside/docker/container

You may want to copy the config files elsewhere with the compose file too. If you copy them, please don't forget to change the volume mounting point, but DON'T change the volume mounting point inside the container, otherwise it will start up with default config.

To update the images: execute docker-compose pull command in the directory where the compose file is.

To start the containers: execute docker-compose up -d command in the directory where the compose file is.

Don't forget to check, are all containers up and running?

If all of their is Up, you are all set. If they die, please check their logs.

If you change your config you have to restart the appropriate container

docker restart <containerName>

Q: MySQL won't start. What did went wrong?
A: Probably you missed to copy the init SQL script next to the compose file, or you have a typo in its name. Solution: https://github.com/arrowhead-f/core-java-spring/issues/105

The Debian installer files are located in the deb-installer/package/arrowhead-installers-4.1.3 folder. Please follow this guide to install them: Debian Installer Guide

Note: Preferred installation mode for Raspberry Pi.

Note: A system with 2GB of RAM is advised.

The project has the following dependencies:

• JRE/JDK 11 Download from here
• Maven 3.5+ Download from here | Install guide
• MySQL server 5.7+ (other SQL databases can work with Hibernate ORM, but the common module pom.xml has to include the appropriate connector dependency to use them)

Verify that you have Java (java -version), Maven (mvn -version), MySQL installed properly!

Pull this code and enter the directory. git clone https://github.com/arrowhead-f/core-java-spring.git

Go to the scripts folder, execute mysql -u root -p < create_empty_arrowhead_db.sql and mysql -u root -p < create_arrowhead_tables.sql MySQL script. If you won't run these scripts first, the project won't build.

cd core-java-spring

Execute mvn install -DskipTests command. Wait until the build succeeds. This command builds all available projects.

After the build is complete, the jars with the appropriate application.properites will be available in their directory.

Change directory to:

• serviceregistry/target directory. cd serviceregistry/target
  and execute: java -jar arrowhead-serviceregistry-4.1.3.jar
• authorization/target directory. cd authorization/target
  and execute: java -jar arrowhead-authorization-4.1.3.jar
• orchestrator/target directory. orchestrator/target
  and execute: java -jar arrowhead-orchestrator-4.1.3.jar

After successful build enter the scripts folder and execute start_core_systems.sh or start_core_systems.bat depending on your operating system.

Wait until servers start...

Note: By default servers start in SECURE mode. To access them, you need to use an example certificate, provided in the certificate directory.

Note: If you wish to change the the configuration, do it by by modifying the application.properties file in the target directory! Don't forget to change all of them!

Service Registry will be available on https://localhost:8443
Authorization will be available on https://localhost:8445
Orchestrator will be available on https://localhost:8441
Event Handler will be available on https://localhost:8455
DataManager will be available on https://localhost:8461
TimeManager will be available on https://localhost:8463
Gatekeeper will be available on https://localhost:8449
Gateway will be available on https://localhost:8453

Swagger with API documentation is available in the root route.

To start in insecure mode, you have to change the server.ssl.enabled property to false. You'll have to do it for each core system, under the path target/application.properties. Note that if you recompile after the changes, the target/application.properties file will be overwritten by the default ones in the src/main/resources/application.properties.

The Gatekeeper and Gateway use encryption based on the certificates, hence there is no way to start the Gatekeeper and Gateway in insecure mode. But you can use the local cloud without these core systems. All you have to do is to set gatekeeper_is_present=false in the application.properties of the ochestrator, and start the script start_coresystems_local.bat or start_coresystems_local.sh depending on your operating system.

4.1.3 is NOT backwards compatible with 4.1.2! Earlier it was redundant and contained gaps. Now the database and the endpoints are redesigned, they are clean, more logical and easier to use.

You can migrate your existing database manually. See the Quick Start Guide, how to deploy the Core Systems.

Major endpoint changes:

The following endpoints no longer exist, instead use the ones on the right:

• PUT /mgmt/services -> POST /serviceregistry/mgmt/services

• PUT /mgmt/systems -> POST /serviceregistry/mgmt/systems

• GET /serviceregistry/mgmt/systemId/{systemId} -> GET /serviceregistry/mgmt/systems/{id}

• GET /serviceregistry/mgmt/serviceId/{serviceId}/providers

• PUT /serviceregistry/mgmt/query -> POST /serviceregistry/query

• PUT /serviceregistry/mgmt/subscriptions/{id}

• PUT /serviceregistry/support/remove -> DELETE /serviceregistry/unregister

• DELETE /serviceregistry/mgmt/all

• serviceregistry/register - data structure changed

Description for this endpoint is available here: Register

Old payload, which is no longer usable

{
 "providedService" : {
   "serviceDefinition" : "IndoorTemperature",
   "interfaces" : [ "JSON", "XML" ],
   "serviceMetadata" : {
     "unit" : "celsius"
   }
 },
 "provider" : {
   "systemName" : "InsecureTemperatureSensor",
   "address" : "192.168.0.2",
   "port" : 8080
 },
 "serviceURI" : "temperature",
 "version" : 1,
 "udp" : false,
 "ttl" : 0
} 

New payload - you can easily map the old fields to the new ones.

{
 "serviceDefinition": "IndoorTemperature",
 "providerSystem": {
   "systemName": "InsecureTemperatureSensor",
   "address": "192.168.0.2",
   "port": 8080,
 "authenticationInfo": "eyJhbGciOiJIUzI1Ni..."
},
 "serviceUri": "temperature",
 "endOfValidity": "2019-12-05T12:00:00",
 "secure": "TOKEN",
 "metadata": {
   "unit": "celsius"
},
 "version": 1,
 "interfaces": [
   "HTTP-SECURE-JSON"
 ]
}

• /mgmt/intracloud - data structure changed
• /mgmt/intercloud - data structure changed

How to Add Intracloud rules
How to Add Intercloud rules

• /mgmt/store - data structure changed
• /orchestrator/orchestration - data structure changed

Description for this endpoint is available here: Orchestration

Old payload, which is no longer usable

{
 "requesterSystem" : {
   "systemName" : "client1",
   "address" : "localhost",
   "port" : 0,
   "authenticationInfo" : "null"
 },
 "requestedService" : {
   "serviceDefinition" : "IndoorTemperature",
   "interfaces" : [ "json" ],
   "serviceMetadata" : {
     "unit" : "celsius"
   }
 },
 "orchestrationFlags" : {
   "onlyPreferred" : false,
   "overrideStore" : true,
   "externalServiceRequest" : false,
   "enableInterCloud" : true,
   "enableQoS" : false,
   "matchmaking" : false,
   "metadataSearch" : true,
   "triggerInterCloud" : false,
   "pingProviders" : false
 },
 "preferredProviders" : [ ],
 "requestedQoS" : { },
 "commands" : { }
}

New payload - you can easily map the old fields to the new ones.

{
  "requesterSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "requestedService": {
    "serviceDefinitionRequirement": "string",
    "interfaceRequirements": [
      "string"
    ],
    "securityRequirements": [
      "NOT_SECURE", "CERTIFICATE", "TOKEN"
    ],
    "metadataRequirements": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "versionRequirement": 0,
    "maxVersionRequirement": 0,
   "minVersionRequirement": 0
  },
  "preferredProviders": [
    {
      "providerCloud": {
        "operator": "string",
        "name": "string"
      },
      "providerSystem": {
        "systemName": "string",
        "address": "string",
        "port": 0
      }
    }
  ],
  "orchestrationFlags": {
    "additionalProp1": true,
    "additionalProp2": true,
    "additionalProp3": true
  }
}

Arrowhead Framework's security is relying on SSL Certificate Trust Chains. The Arrowhead trust chain consists of three level:

1. Master certificate: arrowhead.eu
2. Cloud certificate: my-cloud.my-company.arrowhead.eu
3. Client certificate: my-client.my-cloud.my-company.arrowhead.eu The certificate naming convention have strict rules:

• The different parts are delimited by dots, therefore parts are not allowed to contain any of them.
• A single part is allowed to contain maximum 63 character of letters (english alphabet), numbers and dash (-), and has to start with a letter (also cannot ends with dash).
• A cloud certificate name has to consist of four part and the last two part have to be 'arrowhead' and 'eu'.
• A client certificate name has to consist of five part and the last two part have to be 'arrowhead' and 'eu'.

The trust chain is created by issuing the cloud certificate from the master certificate and the client certificate from the cloud certificate. With other words, the cloud certificate is signed by the master certificate's private key and the client certificate is signed by the cloud certificate's private key which makes the whole chain trustworthy.

The Key-Store is intended to store the certificates and/or key-pair certificates. Key-pair certificates are contain the certificate chain with some additinal data, such as the private-public keys, which are necessary for the secure operation. Certificates located in this store (without the keys) will be attached to the outcoming HTTPS requests. Arrowhead Framework is designed for handling the p12 type of Key-Stores.

(Note: When you creating a new key-pair certificate, then the key-password and the key-store-password must be the same.)

The Trust-Store is containing those certificates, what the web-server considers as trusted ones. Arrowhead Framework is designed for handling the p12 type of Trust-Stores. Typically your Trust-Store should contain only the cloud certificate, which ensures that only those incoming HTTPS requests are authorized to access, which are having this certificate within their certificate chain.

Currently Arrowhead community have the possibility to create only "self signed" certifications. See the tutorials:

• Create Arrowhead Cloud Self Signed Certificate
• Create Arrowhead Client Self Signed Certificate
• Create Trust Store

If you wish to generate all Certificates by a script, you can use the scripts in the scripts/certificate_generation folder.

Note: Basic scripting knowledge is required!

• lib_certs.sh - Certificate generation code
• mk_certs.sh - Usage example
• rm_certs.sh - Delete generated certs

You can also use the arrowhead script. For this barely any scripting knowledge is needed, just follow the instructions.

Arrowhead scripts.

The System Operator Certificate is a special client certificate with the naming convention of sysop.my-cloud.my-company.arrowhead.eu. SysOp certificate allows the client to use the management endpoints of the Arrowhead Core Systems. Typical usage of SysOp certificate is by front end applications running in a web browser (for example if you want to access the Swagger or use the Management Tool in secure mode.

• Import SysOp Certificate (Windows 10)
• Import SysOp Certificate (macOS)
• Import SysOp Certificate (Linux)

The following guide describes step by step, how to include your own certificates into a Docker container.

• How to include certificate in Docker

Please follow this guide to setup the Arrowhead Gatekeeper and Gateway core systems: Gatekeeper & Gateway Setup Guide with ActiveMQ Relay

Arrowhead's CI/CD pipeline is based on the work of Haris Isakovic and Peter Ketcher from TU Wien. Thank you for providing this amazing guide and countless hours of help setting it up properly. CI/CD Tutorial for Arrowhead Framework

All work on Arrowhead repositories happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

The latest version of the core systems are available in the master branch. The code for the next release is merged in the development branch. If you would like to contribute, please check out the development branch. Create a new branch from development. Don't forget do write documentation, unit and integration tests. When finished, create a pull request back into development. If accepted, your contribution will be in the next release. :)

Before you make a pull request, please make sure you clean your code as best as you can. The following resources can help to understand what clean code means:

• Clean Coding in Java
• A short summary of Java Coding best practices

We are using GitHub Issues for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn’t already exist.

The best way to get your bug fixed is to provide a reduced test case.

Join our developer team on Slack. Write an email to szvetlin@aitia.ai for an invite.

This System provides the database, which stores information related to the currently actively offered Services within the Local Cloud.

The purpose of this System is therefore to allow:

• Application Systems to register what Services they offer at the moment, making this announcement available to other Application Systems on the network.
• They are also allowed to remove or update their entries when it is necessary.
• All Application Systems can utilize the lookup functionality of the Registry to find Public Core System Service offerings in the network, otherwise the Orchestrator has to be used.

However, it is worth noting, that within this generation the lookup functionality of Services is integrated within the “orchestration process”. Therefore, in the primary scenario, when an Application System is looking for a Service to consume, it shall ask the Orchestrator System via the Orchestration Service to locate one or more suitable Service Providers and help establish the connection based on metadata submitted in the request. Direct lookups from Application Systems within the network is not advised in this generation, due to security reasons.

However, the lookup of other Application Systems and Services directly is not within the primary use, since access will not be given without the Authorization JWT (JSON Web Token). The use of the TokenGeneration is restricted to the Orchestrator for general System accountability reasons.

This System only provides one Core Service the Service Discovery

There are two use case scenarios connected to the Service Registry.

• Service registration, de-registration
• Service Registry querying (lookup)

The register method is used to register services. The services will contain various metadata as well as a physical endpoint. The various parameters are representing the endpoint information that should be registered.

The unregister method is used to unregister service instances that were previously registered in the Registry. The instance parameter is representing the endpoint information that should be removed.

The query method is used to find and translate a symbolic service name into a physical endpoint, for example an IP address and a port. The query parameter is used to request a subset of all the registered services fulfilling the demand of the user of the service. The returned listing contains service endpoints that have been fulfilling the query.

There is another functionality that does not bound to any Services, just an internal part of the Service Registry. There are two optional cleanup tasks within the Service Registry, which can be used to remove old, inactive service offerings. The first task is based on pinging the service provider and if the provider does not respond to the ping, its offered services will be deleted. The second task is based on a feature, called “Time to Live”. Service providers upon registration can provide a timestamp called “end_of_validity” number, which specifies how long the service will be offered by the provider, making the service de-registrations unnecessary, if this task is active. The task is used to remove expired services. The third task is using a feature called "Heartbeat" (Not yet implemented), where the Service provider periodically signals to the Service Registry that it is still alive. When it misses it will be removed. All of these internal tasks can be configured in the application.properties file.

This System can be secured via the HTTPS protocol. If it is started in secure mode, it verifies whether the Application System possesses a proper X.509 identity certificate and whether that certificate is Arrowhead compliant in its making. This certificate structure and creation guidelines ensure:

• Application System is properly bootstrapped into the Local Cloud
• The Application System indeed belongs to this Local Cloud
• The Application System then automatically has the right to register its Services in the Registry.

If these criteria are met, the Application System’s registration or removal message is processed. An Application System can only delete or alter entries that contain the Application System as the Service Provider in the entry.

The Service Registry offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/serviceregistry

These services can only be used by other core services, therefore they are not part of the public API.

There endpoints are mainly used by the Management Tool and Cloud Administrators.

The following endpoints no longer exist:

• PUT /mgmt/services
• PUT /mgmgt/systems
• GET /serviceregistry/mgmt
• GET /serviceregistry/mgmt/systemId/{systemId}
• GET /serviceregistry/mgmt/serviceId/{serviceId}/providers
• PUT /serviceregistry/mgmt/query
• PUT /serviceregistry/mgmt/subscriptions/{id}
• PUT /serviceregistry/support/remove
• DELETE /serviceregistry/mgmt/all

GET /serviceregistry/echo

Returns a "Got it!" message with the purpose of testing the core service availability.

Note: 4.1.2 version: GET /serviceregistry

POST /serviceregistry/query

Returns ServiceQueryList that fits the input specification. Mainly used by the Orchestrator.

{
 "serviceDefinitionRequirement": "string",
 "interfaceRequirements": [
   "string"
 ],
 "securityRequirements": [
   "NOT_SECURE"
 ],
 "metadataRequirements": {
   "additionalProp1": "string",
   "additionalProp2": "string",
   "additionalProp3": "string"
 },
 "versionRequirement": 0,
 "maxVersionRequirement": 0,
 "minVersionRequirement": 0,
 "pingProviders": true
}

{
 "serviceQueryData": [
   {
     "id": 0,
     "serviceDefinition": {
       "id": 0,
       "serviceDefinition": "string",
       "createdAt": "string",
       "updatedAt": "string"
     },
     "provider": {
       "id": 0,
       "systemName": "string",
       "address": "string",
       "port": 0,
       "authenticationInfo": "string",
       "createdAt": "string",
       "updatedAt": "string"
     },
     "serviceUri": "string",
     "endOfValidity": "string",
     "secure": "NOT_SECURE",
     "metadata": {
       "additionalProp1": "string",
       "additionalProp2": "string",
       "additionalProp3": "string"
     },
     "version": 0,
     "interfaces": [
       {
         "id": 0,
         "interfaceName": "string",
         "createdAt": "string",
         "updatedAt": "string"
       }
     ],
     "createdAt": "string",
     "updatedAt": "string"
    }
 ],
 "unfilteredHits": 0
}

POST /serviceregistry/register

Registers a service. A provider is allowed to register only its own services. It means that provider system name and certificate common name must match for successful registration.

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
  ]
}

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}

DELETE /serviceregistry/unregister

Removes a registered service. A provider is allowed to unregister only its own services. It means that provider system name and certificate common name must match for successful unregistration.

Query params:

Note: 4.1.2 version: PUT /serviceregistry/remove
In this version the input was a JSON object with many unnecessary information.

POST /serviceregistry/query/system

This service can only be used by other core services, therefore is not part of the public API.

GET /serviceregistry/system/{id}

This service can only be used by other core services, therefore is not part of the public API.

GET /serviceregistry/mgmt

Returns a list of Service Registry records. If page and item_per_page are not defined, returns all records.

Query params:

Note: Default value for sort_field is id. All possible values are:

• id
• createdAt
• updatedAt

Note: Default value for direction is ASC. All possible values are:

• ASC
• DESC

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "endOfValidity": "string",
      "secure": "NOT_SECURE",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "version": 0,
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}

POST /serviceregistry/mgmt

Creates service registry record and returns the newly created record.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTP-SECURE-JSON)

Note: Possible values for secure are:

• NOT_SECURE (default value if field is not defined)
• CERTIFICATE
• TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}

Note: 4.1.2 version: POST /serviceregistry/support/register
It was available for clients as well, not only for the system operator of the local cloud. Interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

GET /serviceregistry/mgmt/{id}

Returns the Service Registry Entry specified by the ID path parameter.

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}

Note: 4.1.2 version: GET /serviceregistry/mgmt/id/{id}
In this version interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

PUT /serviceregistry/mgmt/{id}

Updates and returns the modified service registry record specified by the id path parameter. Not defined fields are going to be updated to "null" value.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTP-SECURE-JSON)

Note: Possible values for secure are:

• NOT_SECURE (default value if field is not defined)
• CERTIFICATE
• TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}

Note: 4.1.2 version: PUT /serviceregistry/mgmt/update/{id}
In this version interfaces and metadata were bound to the service definition and security type was not defined at all. The response object did not contain any modification related time stamp information. Service Registry object did contain an "udp" flag beside the interface definition.

PATCH /serviceregistry/mgmt/{id}

Updates and returns the modified service registry record specified by the id path parameter. Not defined fields are NOT going to be updated.

ServiceRegistryEntry is the input

{
  "serviceDefinition": "string",
  "providerSystem": {
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    "string"
 ]
}

Note: Valid interfaces name pattern: protocol-SECURE or INSECURE format. (e.g.: HTTP-SECURE-JSON)

Note: Possible values for secure are:

• NOT_SECURE (default value if field is not defined)
• CERTIFICATE
• TOKEN

Returns a ServiceRegistryEntry

{
  "id": 0,
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "provider": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceUri": "string",
  "endOfValidity": "string",
  "secure": "NOT_SECURE",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "version": 0,
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
 }
 ],
 "createdAt": "string",
 "updatedAt": "string"
}

Note: 4.1.2 version: Not existed

DELETE /serviceregistry/mgmt/{id}

Remove the service registry record specified by the id path parameter.

Note: 4.1.2 version: DELETE /serviceregistry/mgmt/{entryId}
This version did return Http 404 (not found), when record was not found by id.

GET /serviceregistry/mgmt/grouped

Returns all Service Registry Entries grouped for the purpose of the Management Tools' Service Registry view:

• autoCompleteData
• servicesGroupedByServiceDefinition
• servicesGroupedBySystems

{
  "autoCompleteData": {
    "interfaceList": [
      {
        "id": 0,
        "value": "string"
      }
    ],
    "serviceList": [
      {
        "id": 0,
        "value": "string"
      }
    ],
    "systemList": [
      {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  },
  "servicesGroupedByServiceDefinition": [
    {
      "serviceDefinitionId": 0,
      "serviceDefinition": "string",
      "providerServices": [
        {
          "id": 0,
          "serviceDefinition": {
            "id": 0,
            "serviceDefinition": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "provider": {
            "id": 0,
            "systemName": "string",
            "address": "string",
            "port": 0,
            "authenticationInfo": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "serviceUri": "string",
          "endOfValidity": "string",
          "secure": "NOT_SECURE",
          "metadata": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "version": 0,
          "interfaces": [
            {
              "id": 0,
              "interfaceName": "string",
              "createdAt": "string",
              "updatedAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ],
  "servicesGroupedBySystems": [
    {
      "systemId": 0,
      "systemName": "string",
      "address": "string",
      "port": 0,
      "services": [
        {
          "id": 0,
          "serviceDefinition": {
            "id": 0,
            "serviceDefinition": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "provider": {
            "id": 0,
            "systemName": "string",
            "address": "string",
            "port": 0,
            "authenticationInfo": "string",
            "createdAt": "string",
            "updatedAt": "string"
          },
          "serviceUri": "string",
          "endOfValidity": "string",
          "secure": "NOT_SECURE",
          "metadata": {
            "additionalProp1": "string",
            "additionalProp2": "string",
            "additionalProp3": "string"
          },
          "version": 0,
          "interfaces": [
            {
              "id": 0,
              "interfaceName": "string",
              "createdAt": "string",
              "updatedAt": "string"
            }
          ],
          "createdAt": "string",
          "updatedAt": "string"
        }
      ]
    }
  ]
}

GET /serviceregistry/mgmt/servicedef/{serviceDefinition}

Returns a list of Service Registry records specified by the serviceDefinition path parameter. If page and item_per_page are not defined, returns all records.

Query params:

Note: Default value for sort_field is id. All possible values are:

• id
• createdAt
• updatedAt

Note: Default value for direction is ASC. All possible values are:

• ASC
• DESC

Returns a ServiceRegistryEntryList

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceUri": "string",
      "endOfValidity": "string",
      "secure": "NOT_SECURE",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "version": 0,
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}

Note: 4.1.2 version: GET /serviceregistry/mgmt/servicedef/{serviceDefinition}
This version always returned the records in an array of JSON objects. The objects did not contain any modification related time stamp information. Interfaces and metadata were bound to the service definition and security type was not defined. Service Registry object did contain an "udp" flag beside the interface definition.

GET /serviceregistry/mgmt/services

Returns a list of Service Definition records. If page and item_per_page are not defined, returns all records.

Query params:

Note: Default value for sort_field is id. All possible values are:

• id
• createdAt
• updatedAt

Note: Default value for direction is ASC. All possible values are:

• ASC
• DESC

{
  "data": [
    {
      "id": 0,
      "serviceDefinition": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
   ],
  "count": 0
}

POST /serviceregistry/mgmt/services

Creates service definition record and returns the newly created record.

{
  "serviceDefinition": "string"
}

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /serviceregistry/mgmt/services/{id}

Returns the Service Definition record specified by the id path parameter.

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: GET /mgmt/services/{serviceId} The response object did not contain any modification related time stamp information. Interfaces and metadata were part of the service definition entity.

PUT /serviceregistry/mgmt/services/{id}

Updates and returns the modified Service Definition record specified by the ID path parameter.

ServiceDefinition is the input

{
  "serviceDefinition": "string"
}

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: PUT /mgmt/services/{serviceId}
The response object did not contain any modification related time stamp information. Interfaces and metadata were part of the service definition entity.

PATCH /serviceregistry/mgmt/services/{id}

Updates and returns the modified Service Definition record specified by the ID path parameter.

ServiceDefinition is the input

{
  "serviceDefinition": "string"
}

Returns a ServiceDefinition

{
  "id": 0,
  "serviceDefinition": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: Not existed

DELETE /serviceregistry/mgmt/services/{id}

Removes the service definition record specified by the id path parameter.

Note: 4.1.2 version: DELETE /mgmt/services/{serviceId} This version did return HTTP 404 (Not Found), when record was not found by ID.

GET /serviceregistry/mgmt/systems

Returns a list of System records. If page and item_per_page are not defined, it returns all records.

Query params:

Note: Default value for sort_field is id. All possible values are:

• id
• createdAt
• updatedAt

Note: Default value for direction is ASC. All possible values are:

• ASC
• DESC

{
  "data": [
    {
      "id": 0,
      "systemName": "string",
      "address": "string",
      "port": 0,
      "authenticationInfo": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "count": 0
}

POST /serviceregistry/mgmt/systems

Creates a System record and returns the newly created record.

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

GET /serviceregistry/systems/{id}

Returns the System record specified by the ID path parameter.

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

PUT /serviceregistry/mgmt/systems/{id}

Updates and returns the modified System record specified by the ID path parameter. Not defined fields are going to be updated to "null" value.

System is the input

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: PUT /mgmt/systems/{systemId}
In this version the response object did not contain any modification related time stamp information.

PATCH /serviceregistry/mgmt/systems/{id}

Updates and returns the modified system record specified by the id path parameter. Not defined fields are going to be NOT updated.

System is the input

{
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string"
}

Returns a System

{
  "id": 0,
  "systemName": "string",
  "address": "string",
  "port": 0,
  "authenticationInfo": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Note: 4.1.2 version: Not existed

DELETE /serviceregistry/mgmt/systems/{id}

Removes the System record specified by the ID path parameter.

Note: 4.1.2 version: DELETE /mgmt/systems/{systemId}
This version did return HTTP 404 (Not Found), when record was not found by ID.

This System has:

• A database that describes which Application System can consume what Services from which Application Systems (Intra-Cloud access rules)
• A database that describes which other Local Clouds are allowed to consume what Services from this Cloud (Inter-Cloud authorization rules)

The purpose of this System is therefore to:

• Provide AuthorizationControl Service (both intra- and inter-Cloud)
• Provide a TokenGeneration Service for allowing session control within the Local Cloud

The purpose of the TokenGeneration functionality is to create session control functionality through the Core Sytems. The output is JSON Web Token that validates the Service Consumer system when it will try to access the Service from another Application System (Service Provider). This Token shall be primarily generated during the orchestration process and only released to the Service Consumer when all affected Core Systems are notified and agreed to the to-be-established Service connection.

This System (in line with all core Systems) utilizes the X.509 certificate Common Name naming convention in order to work.

This System only provides two Core Services:

• AuthorizationControl
• TokenGeneration

There are two use cases connected to the Authorization System:

• Check access rights (invoke the AuthorizationControl)
• Generate an access token (the Orchestrator invokes the TokenGeneration)

Figure 1. Authorization crosscheck during orchestration process

The AuthorizationControl Service provides 2 different interfaces to look up authorization rights:

• Intra-Cloud authorization: defines an authorization right between a consumer and provider system in the same Local Cloud for a specific Service.
• Inter-Cloud authorization: defines an authorization right for an external Cloud to consume a specific Service from the Local Cloud.

The Authorization offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/authorization

These services can only be used by other core services, therefore they are not part of the public API.

There endpoints are mainly used by the Management Tool and Cloud Administrators.

The following services no longer exist:

• GET /authorization/mgmt/intracloud/systemId/{systemId}/services
• GET /authorization/mgmt/intracloud/systemId/{systemId}
• GET /authorization/mgmt/intracloud/servicedef/{serviceDefinition}
• PUT /authorization/mgmt/intracloud
• DELETE /authorization/mgmt/intracloud/systemId/{systemId}
• GET /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}/services
• GET /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}
• GET /authorization/mgmt/intercloud/servicedef/{serviceDefinition}
• PUT /authorization/mgmt/intercloud
• DELETE /authorization/mgmt/intercloud/operator/{operator}/cloudname/{cloudName}

GET /authorization/echo

Returns a "Got it!" message with the purpose of testing the core service availability.

Note: 4.1.2 version: GET /authorization/mgmt It was only available for the system operator of the local cloud.

GET /authorization/publickey

Returns the public key of the Authorization core service as a (Base64 encoded) text. This service is necessary for providers if they want to utilize the token based security.

Note:: 4.1.2 version: GET /authorization/mgmt/publickey It was only available for system operator of the local cloud.

POST /authorization/intercloud/check

This service can only be used by other core services, therefore is not part of the public API.

Checks whether a Cloud is authorized to use a Service

{
  "cloud": {
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ],
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "secure": true
  },
  "providerIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "serviceDefinition": "string"
}

{
  "authorizedProviderIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "cloud": {
    "authenticationInfo": "string",
    "createdAt": "string",
    "id": 0,
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "ownCloud": true,
    "secure": true,
    "updatedAt": "string"
  },
  "serviceDefinition": "string"
}

POST /authorization/intracloud/check

This service can only be used by other core services, therefore is not part of the public API.

Checks whether the consumer System can use a Service from a list of provider Systems

{
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "port": 0,
    "systemName": "string"
  },
  "providerIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "serviceDefinitionId": 0
}

{
  "authorizedProviderIdsWithInterfaceIds": [
    {
      "id": 0,
      "idList": [
        0
      ]
    }
  ],
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "createdAt": "string",
    "id": 0,
    "port": 0,
    "systemName": "string",
    "updatedAt": "string"
  },
  "serviceDefinitionId": 0
}

POST /authorization/token

This service can only be used by other core services, therefore is not part of the public API.

Generates a JWT for Authentication

{
  "consumer": {
    "address": "string",
    "authenticationInfo": "string",
    "port": 0,
    "systemName": "string"
  },
  "consumerCloud": {
    "authenticationInfo": "string",
    "gatekeeperRelayIds": [
      0
    ],
    "gatewayRelayIds": [
      0
    ],
    "name": "string",
    "neighbor": true,
    "operator": "string",
    "secure": true
  },
  "duration": 0,
  "providers": [
    {
      "provider": {
        "address": "string",
        "authenticationInfo": "string",
        "port": 0,
        "systemName": "string"
      },
      "serviceInterfaces": [
        "string"
      ]
    }
  ],
  "service": "string"
}

{
  "tokenData": [
    {
      "providerAddress": "string",
      "providerName": "string",
      "providerPort": 0,
      "tokens": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ]
}

GET /authorization/mgmt/intracloud

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

POST /authorization/mgmt/intracloud

Creates Intracloud authorization rules and returns the newly created rules.

{
  "consumerId": 0,
  "providerIds": [
    0
  ],
  "interfaceIds": [
    0
  ],
  "serviceDefinitionIds": [
    0
  ]
}

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "consumerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "providerSystem": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

GET /authorization/mgmt/intracloud/{id}

Returns the Intracloud related authorization rule specified by the ID path parameter.

{
  "id": 0,
  "consumerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "providerSystem": {
    "id": 0,
    "systemName": "string",
    "address": "string",
    "port": 0,
    "authenticationInfo": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "serviceDefinition": {
    "id": 0,
    "serviceDefinition": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "interfaces": [
    {
      "id": 0,
      "interfaceName": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "createdAt": "string",
  "updatedAt": "string"
}

DELETE /authorization/mgmt/intracloud/{id}

Removes the Intracloud related authorization rule specified by the ID path parameter.

Note: 4.1.2 version: DELETE /authorization/mgmt/intracloud/{id} Same the new version.

GET authorization/mgmt/intercloud

Returns a list of Intercloud related authorization rules. If page and item_per_page are not defined, it returns all records.

Query params:

Note: Default value for sort_field is id. All possible values are:

• id
• createdAt
• updatedAt

Note: Default value for direction is ASC. All possible values are:

• ASC
• DESC

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

POST /authorization/mgmt/intercloud

Creates Intercloud authorization rules and returns the newly created rules.

{
  "cloudId": 0,
  "providerIdList": [
    0
  ],
  "interfaceIdList": [
    0
  ],
  "serviceDefinitionIdList": [
    0
  ]
}

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

GET /authorization/mgmt/intercloud/{id}

Returns the Intercloud related authorization record specified by the ID path parameter.

Returns an IntercloudRuleList

{
  "count": 0,
  "data": [
    {
      "id": 0,
      "cloud": {
        "id": 0,
        "operator": "string",
        "name": "string",
        "authenticationInfo": "string",
        "secure": true,
        "neighbor": true,
        "ownCloud": true,
        "createdAt": "string",
        "updatedAt": "string"
      },
      "provider": {
        "id": 0,
        "systemName": "string",
        "address": "string",
        "port": 0,
        "authenticationInfo": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "serviceDefinition": {
        "id": 0,
        "serviceDefinition": "string",
        "createdAt": "string",
        "updatedAt": "string"
      },
      "interfaces": [
        {
          "id": 0,
          "interfaceName": "string",
          "createdAt": "string",
          "updatedAt": "string"
        }
      ],
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Note: 4.1.2 version: GET /authorization/mgmt/intercloud/{id}
The returned structure did not contain time information, provider and interface restrictions.

Removes the Intercloud related authorization record specified by the ID path parameter.

Note: 4.1.2 version: DELETE /authorization/mgmt/intercloud/{id} Same as the new version.

The Orchestrator provides runtime (late) binding between Application Systems.

The primary purpose for the Orchestrator System is to provide Application Systems with orchestration information: where they need to connect to. The outcome of the "Orchestration Service" include rules that will tell the Application System what Service provider System(s) it should connect to and how (acting as a Service Consumer). Such orchestration rules include:

• Accessibility information details of a Service provider (e.g network address and port),
• Details of the Service instance within the provider System (e.g. base URL, IDD specification and other metadata),
• Authorization-related information (e.g. access token and signature),
• Additional information that is necessary for establishing connection.

This orchestration rule information can reach the given Application System (consumer) in two different ways: the System itself can request it ("pull") or the Orchestrator itself can update the System when it is needed ("push method"). However, in both cases, there shall be an underlying, hidden process ("orchestration process"), which ensures the consistence of state between the various Core Systems.

In G4.0, only the pull method is implemented and the Orchestrator shall negotiate with the other Core Systems while trying to facilitate the new service request (or trying to push a new status). This is necessary for the following cases and requirements (basically, when ad hoc, unsupervised connections are not allowed):

• When accountability is required for all Systems in the Local Cloud: connections cannot be established without the knowledge, approval and logged orchestration events of the Core Systems ("central governance").
• QoS and resource management reasons: ad hoc peer-to-peer connections cannot be allowed in certain managed networks and deployment scenarios. Every connection attempt shall be properly authorized and its QoS expectations (resource reservations) handled.
• Inter-Cloud orchestration can only happen via negotiations between the two Core System sets. Ad hoc inter-cloud connections shall not be allowed in the Arrowhead framework.

In these cases, when the Orchestrator is the sole entry point to establishing new connections within the Local Cloud, Application Systems do not have the possibility to skip any of the control loops with all the appropriate Core Systems. When such security and safety concerns are not present, the orchestration process might be cut back or these interactions between Core Systems might be limited. Within G4.0, this is not the primary use case, but it is allowed. With the proper self-implemented (modified) and a self-compiled Orchestrator can fit the deployment best.

Therefore, the Orchestrator provides two core Services and may consume many other ones, but at least two -- again, depending on its deployment. This figure depicts the mandatory and optional interfaces of this System.

In here, the provided Services are:

• Orchestration Service
• OrchestrationStoreManagement Service

Meanwhile the consumed Services can vary, depending on the instantiation/installation of this System. For example, the Orchestrator can utilize the services of:

• ServiceDiscovery Service from the ServiceRegistry,
• AuthorizationControl Service from the Authorization System,
• TokenGeneration Service from the Authorization System,
• GlobalServiceDiscovery from the Gatekeeper,
• Inter-CloudNegotiations from the Gatekeeper,
• QoSVerify from the QoS Manager,
• QoSReserve from the QoS Manager,
• Logging services from other supporting Systems, e.g. Historian,
• and any other service from Core Systems that are necessary to settle during orchestration.

The Orchestrator mainly consumes services from other Core Systems in order to fulfil its primary functionality: provide connection targets for Application Systems in a secure and resource managed manner -- hence build an SoS.

During this orchestration process the Orchestrator either facilitates a service request from an Application System or processes a system-of-systems (SoS) level choreography push from the Plant Description Engine ("Choreographer"). For the latter case, the Orchestrator System consumes the OrchestrationPush from affected Application Systems in order to deliver a renewed set of connection rules to them.

Within the Orchestrator, there is a database which captures design time bindings between Application Systems, the Orchestration Store. Operators of the Cloud and other System-of-Systems designer tools ("SoS Choreographers") are allowed to modify the rules stored in the Orchestration Store, other generic Application Systems are not.

The ServiceDiscovery Service is used to publish the Orchestration Service in the Service Registry. This Service is also used to query the Service Registry and fetch (metadata) information on other Application Systems.

The Services of the Authorization System can be used to verify access control and implement other security-related administration tasks.

The Services of the Gatekeeper can be utilized when inter-Cloud collaboration, servicing is required.

The Services of the QoS management System can be used to manage device, network and service-level Quality of Service agreements and configurations.

Orchestrator can be used in two ways. The first one uses predefined rules (coming from the Orchestrator Store DB) to find the appropriate providers for the consumer. The second option is the dynamic orchestration in which case the core service searches the whole local cloud (and maybe some other clouds) to find matching providers.

• requester system is mandatory,
• requested service and all the other parameters are optional,
• if requested service is not specified, then this service returns the top priority local provider of all services contained by the orchestrator store database for the requester system. if requested service is specified, then you have to define the service definition and exactly one interface (all other service requirements are optional). In this case, it returns all accessible providers from the orchestrator store database that provides the specified service via the specified interface to the specified consumer.

• requester system is mandatory,
• requested service is mandatory, but just the service definition part, all other parameters of the requested service are optional,
• all other parameters are optional

• matchmaking: the service automatically selects exactly one provider from the appropriate providers (if any),
• metadataSearch: query in the Service Registry uses metadata filtering,
• onlyPreferred: the service filters the results with the specified provider list,
• pingProviders: the service checks whether the returning providers are online and remove the unaccessible ones from the results,
• overrideStore: Services uses dynamic orchestration if this flag is true, otherwise it uses the orchestration store,
• enableInterCloud: the service can search another clouds for providers if none of the local cloud providers match the requirements,
• triggerInterCloud: the service skipped the search in the local cloud and tries to find providers in other clouds instead.

For the Orchestrator System, the primary scenario is to provide Application Systems with orchestration information upon request (Service Request). The outcome (Orchestration Response) include orchestration rules that will tell the Application System what service provider(s) it should connect to and how.

An alternative, secondary version of this scenario involves the same information, however, provided by a connection initialized by the Orchestrator, rather than the Application Service itself ("orchestration push"). This is used to relay changes made in the Orchestration Store to the Application Systems ("changes information exchange setup within the SoS").

Another scenario is when the Orchestration Store (that stores design time orchestration-related information) of the Orchestrator is being configured via an HMI or via the Plant Description Engine (SoS Choreographer) by the operators of the Local Cloud.

Use case 1: Service Request From Application System

Use case 2: Orchestration information pushed to Application System

Use case 3: Orchestration information pushed to Application System

The Orchestrator offers three types of endpoints. Client, Management and Private.

Swagger API documentation is available on: https://<host>:<port>
The base URL for the requests: http://<host>:<port>/orchestrator

These services can only be used by other core services, therefore they are not part of the public API.

There endpoints are mainly used by the Management Tool and Cloud Administrators.