Merge pull request #929 from openBackhaul/AP-v2.0.2_spec

AP v2.1.0

doc/ElementsApplicationPattern/Functions/ConceptOfProfiles/ConceptOfProfiles.md

@@ -59,7 +59,7 @@ It occurs several times in all existing applications.
 
 **FileProfile**  
 The _FileProfile_ contains the information, which is required for connecting with a file that holds application data.  
-Aside identifying and describing the referenced file, it makes file path, access credentials and allowed operations available for configuration.  
+Aside identifying and describing the referenced file, it makes file path and allowed operations available for configuration.  
 The _FileProfile_ is used whenever the application uses one or several files for storing internal data.  
 
 **GenericResponseProfile** 

doc/ElementsApplicationPattern/Functions/StructureOfInternalForwarding/StructureOfInternalForwarding.md

@@ -4,13 +4,15 @@ _ForwardingConstructs_ are describing relationships between events and reactions
 Since we are dealing with REST servers,  
 - an event is a request, which has been received (_Input_) by one of the _OperationServers_ offered by the application and  
 - the reaction is a request, which has to be sent (_Output_) via one of the _OperationClients_ that are for addressing other applications.  
+
 Obviously, a definition of a _ForwardingConstruct_ must comprise at least one _Input_ (reference to an _OperationServer_) and at least one _Output_ (reference to an _OperationClient_).  
 
 ![scheme](https://user-images.githubusercontent.com/57349523/230372750-3ad03353-7854-49d6-a7ab-4b2780806de5.jpg)
 
-As described above, we are documenting the relationships, because we want to be able to modify them.  
-If we want to automate the modification, there must be services available on the REST API for facilitating this.  
-Thus, a definition of a _ForwardingConstruct_ needs also to comprise a _Management_ (reference to an _OperationServer_), if it shall be possible to automate changes (otherwise, the _ForwardingConstruct_ would have to be altered by editing in the CONFIGfile).  
+We are documenting the relationships, because we want to be able to modify them.  
+If we want to automate the modification (e.g. creating a subscription), there must be services available on the REST API for facilitating this.  
+In this case, the definition of a _ForwardingConstruct_ needs also to comprise a _Management_ (reference to an _OperationServer_).  
+Otherwise, the _ForwardingConstruct_ would have to be altered by editing in the CONFIGfile.  
 
 ![fc](https://user-images.githubusercontent.com/57349523/230372906-aef8be4b-38e2-43bd-a5d5-4553628eba4c.jpg)
 
@@ -21,6 +23,6 @@ A _Forwarding_ from registration to notifying the _TypeApprovalRegister_ has to
 This _Forwarding_ has to comprise the following _Servers_ and _Clients_:  
 - _Management_: The _TypeApprovalRegister_ is informing the _RegistryOffice_ about its TCP/IP address and _OperationName_ for receiving notifications about new registrations by addressing the _RegistryOffice's OperationServer /v1/inquire-application-type-approvals_. The _RegistryOffice_ creates or updates a stack of _Clients_ with these information and it complements the corresponding _ForwardingConstruct_ by an _Output_ reference to the _OperationClient_.  
 - _Input_: Some new application is addressing the _RegistryOffice's OperationServer /v1/register-application_ for registering.  
-- _Output_: The _RegistryOffice_ is activating its _OperationClient _TypeApprovalRegister://v1/regard-application_ for sending the notification to the _TypeApprovalRegister_.  
+- _Output_: The _RegistryOffice_ is activating its _OperationClient_ _TypeApprovalRegister://v1/regard-application_ for sending the notification to the _TypeApprovalRegister_.  
 
 ![example](https://user-images.githubusercontent.com/57349523/230372426-089b8ee3-9244-4570-b98f-879b67d64c7d.jpg)

doc/ElementsApplicationPattern/Functions/StructureOfTestCaseCollection/StructureOfTestCaseCollection.md

@@ -2,36 +2,55 @@
 
 The Test Case Collection is implemented in a kind of framework.  
 
-First there is Postman. Postman supports the sending of requests to REST interfaces.  
-Several methods are provided. Some are more for quick and dirty shots. Some facilitate to create sophisticated programs.  
-The TCC uses Postman in an advanced form where many requests are combined and executed in a predefined sequence.  
-
-Second there is the InterfaceValidator. The InterfaceValidator was originally designed to test implementations of the ONF TR-532.  
+First there is Postman.  
+Postman supports the sending of HTTP requests to REST interfaces.  
+Several different approaches are supported.  
+Some are more for quick and dirty shots.  
+Some facilitate to create sophisticated programs.  
+The TCC uses Postman in an advanced form where many Requests get executed in a sequential order.  
+Every individual Request consists of a  
+- Pre-request Script that is used for preparing sending the HTTP request, an  
+- HTTP request and a  
+- Tests Script that is used for analysing the response of the HTTP request.  
+Both Scripts are written a JavaScript code into the respective Postman sandbox.  
+
+Second there is the InterfaceValidator.  
+The InterfaceValidator was originally designed to test implementations of the ONF TR-532.  
 It basically provides  
-- a set of basic requests that are always required, 
-- a concept for handling variables and 
-- methods for retrieving results from the test case execution.  
-
-This results in a framework that can be flexibly adapted to the respective application.  
+- a structure of folders that allows flexibly adding test cases,  
+- a set of basic requests that are always required,  
+- a concept for handling variables,  
+- a scripting structure that allows to quickly read and navigate code contributed by different people,  
+- a simple programming method that prevents the program flow from being interrupted when an error occurs,
+- a harmonized way to represent testing results and  
+- a unified way to display error messages and warnings that pop up during TCC execution.  
+
+The framework can be flexibly adapted to the respective application under test.  
 It can hold high numbers of test cases.  
 Every test case may combine multiple Requests.  
-Each Request combines Pre-Request Script, request and Test Script.  
+Each Request combines Pre-Request Script, HTTP request and Test Script.  
 
 ![OuterStructure](./pictures/OuterStructure.png)  
 
+Postman allows presenting Output in two ways:
+- in the CollectionRunner
+- in the PostmanConsole
+
+The InterfaceValidator uses these two possibilities in the following way:
+- The CollectionRunner represents the results of the test case.  
+  The represented information is related with the application under test.  
+- PostmanConsole shows information about the program flow of the InterfaceValidator.  
+  This covers the sent requests, the data inside the InterfaceValidator, and notifications provided by the InterfaceValidator, etc.
+
 
 
 
+.
+.
+.
 
 
-Postman
-- GUI
-- Sending request
-  - individually
-  - or fully automated collections of sequentially executed requests
-- Sandbox for code being executed before => preparation e.g. composing the URI and the body
-- Sandbox for code being executed afterwards => assessing the response
-- for rest of text: Request = combination of Sandbox + request + Sandbox
+Stoffsammlung
 
 - Properly assessing the response requires reference values
   - could either be read from file

doc/ElementsApplicationPattern/InformationModel/LogicalTerminationPoint/LogicalTerminationPoint.md

@@ -12,7 +12,7 @@ The following attributes are hold by the LogicalTerminationPoint:
   - **core-model-1-4:TERMINATION_DIRECTION_SOURCE**: Looking at the _Forwarding_ inside the applications, it is the OperationServer, where the event, which causes a reaction at the OperationClient, happens. Consequently, the LTPs that are describing servers (OperationServer, HttpServer, TcpServer) are identified by being sources of the internal flow.  
   - **core-model-1-4:TERMINATION_DIRECTION_SINK**: Again looking at the internal _Forwarding_, the information is propagating towards the clients (OperationClient, ElasticsearchClient, HttpClient, TcpClient). Consequently, these interfaces are associated with being sinks of the internal flow.  
 - **clientLtp**: This attribute does not relate to the relationship between applications, but OSI network layers. Example: An Ethernet PHY would be required for transporting an Ethernet MAC, and an Ethernet MAC would be required for transporting an IP layer. So, the Ethernet PHY is serving the Ethernet MAC, and the IP is client of the Ethernet MAC. Example in case of applications: OperationClients/OperationServers are referenced in the clientLtp attribute of the HttpClient/HttpServer.  
-- **serverLtp**: Example in case of applications: TcpClients/TcpServers are referenced in the serverLtp attribute of the HttpClient/HttpServer.
+- **serverLtp**: Example in case of applications: the TcpClient/TcpServer is referenced in the serverLtp attribute of the HttpClient/HttpServer.
 - **layerProtocol**: List of logical layers that are terminated at the LTP. In case of MW SDN applications, but also in case of the MW information model, there is always just a single instance of LayerProtocol in this list.  
 
 ![ClientServerRelationships](pictures/clientServerLtp.png)  
@@ -78,7 +78,7 @@ Each service that is provided by the application is represented as an **Operatio
 }
 ```
 
-- The **TcpServer** represents the current IP address and port of the application that is subject to the specification. There must be at least one instance of TcpServer. If the application shall be reachable from within and from outside the virtual private cloud (name space behind TLS layer termination), separate TcpServers are required for http and https. The TcpServer has a complex data structure that offers multiple ways of expressing the address information. Several attributes are for alternative usage (means: exclusive alternatives). It is recommended to study the definition of the ControlConstruct in the OpenApiSpecification of the ApplicationPattern, if a different way of expressing the application's own address would be required. In all the existing applications, the following attributes got augmented:  
+- The **TcpServer** represents the current IP address and port of the application that is subject to the specification. The TcpServer has a complex data structure that offers multiple ways of expressing the address information. Several attributes are for alternative usage (means: exclusive alternatives). It is recommended to study the definition of the ControlConstruct in the OpenApiSpecification of the ApplicationPattern, if a different way of expressing the application's own address would be required. In all the existing applications, the following attributes got augmented:  
 ```
 "tcp-server-interface-1-0:tcp-server-interface-pac": {
   "tcp-server-interface-configuration": {
@@ -133,7 +133,7 @@ Each service that is provided by the application is represented as an **Operatio
 }
 ```
 
-- The **TcpClient** stores the IP address and port of a serving application. In contrast to the TcpServer, just a single TcpClient shall be described. Alike the TcpServer, the TcpClient has a complex data structure that offers multiple ways of expressing the address information. Several attributes are for alternative usage (means: exclusive alternatives). It is recommended to study the definition of the ControlConstruct in the OpenApiSpecification of the ApplicationPattern, if a different way of expressing the serving application's address would be required. In all the existing applications, the following attributes got augmented:  
+- The **TcpClient** stores the IP address and port of a serving application. Alike the TcpServer, the TcpClient has a complex data structure that offers multiple ways of expressing the address information. Several attributes are for alternative usage (means: exclusive alternatives). It is recommended to study the definition of the ControlConstruct in the OpenApiSpecification of the ApplicationPattern, if a different way of expressing the serving application's address would be required. In all the existing applications, the following attributes got augmented:  
 ```
 "tcp-client-interface-1-0:tcp-client-interface-pac": {
   "tcp-client-interface-configuration": {

doc/ElementsApplicationPattern/InformationModel/Profile/Profile.md

@@ -76,8 +76,6 @@ In case of the **FileProfile** the following attributes get augmented:
   },
   "file-profile-configuration": {
     "file-path": "../application-data/application-data.json",
-    "user-name": "RegistryOffice",
-    "password": "Operations to add password",
     "operation": "file-profile-1-0:OPERATION_TYPE_READ_WRITE"
   }
 }

doc/SpecifyingApplications/ConceptOfServiceList/ConceptOfServiceList.md

@@ -12,7 +12,7 @@ It provides full focus on composing a complete and well-structured set of _Opera
 * The _ReleaseNumber_ ...
   * ... has to follow the definitions in [Structure of _ReleaseNumbers_](../../ElementsApplicationPattern/Names/StructureOfReleaseNumbers/StructureOfReleaseNumbers.md),
   * ... has to identify the version resulting from the specification (if originally planned to fix some bugs and later decided to add functionality the _ReleaseNumber_ has to be changed accordingly).  
-* The CONFIGfile contains all data that is necessary to establish the connections, which are required for properly operating the application. TCP/IP addresses, _OperationNames_ and _ReleaseNumber_ might depend on the environment (e.g. SDN test laboratory or live network) in which the application gets instantiated in. As a consequence the CONFIGfile has to be adapted to the environment before instantiation. This adaption shall be automated. For supporting the automation, fake IP addresses have to be put into the _ServiceList_ during specification. Fake IP addresses will be replaced by environmental specific addresses during the creation of docker image. New IP addresses and TCP ports will be assigned by the _PlatformOwner_. Please, request for an address and look it up at [Fake TCP/IP addresses](../../TestingApplications/Infrastructure/SdnLaboratory/FakeAddresses/IpAddresses.md).
+* The CONFIGfile contains all data that is necessary to establish the connections, which are required for properly operating the application. TCP/IP addresses, _OperationNames_ and _ReleaseNumber_ might depend on the environment (e.g. SDN test laboratory or live network) in which the application gets instantiated in. As a consequence the CONFIGfile has to be adapted to the environment before instantiation. This adaption has been automated by running a script. The automation requires a default IP address and an idividual TCP port to be put into the into the _ServiceList_ during specification. This fake address will be replaced by environmental specific addresses during the creation of docker image. New TCP ports will be assigned by the _PlatformOwner_. Please, request for an address and look it up at [Fake TCP/IP addresses](../../TestingApplications/Infrastructure/SdnLaboratory/FakeAddresses/IpAddresses.md).
 
 
 ### OperationServers

doc/SpecifyingApplications/CreatingConfigFile/CreatingConfigFile.md

@@ -4,7 +4,7 @@ This is the step by step cookbook for creating the _CONFIGfile_.
 
 Please read the following conceptual documents before working on the _CONFIGfile_:  
 - [Concept of the CONFIGfile](../../ElementsApplicationPattern/Functions/ConceptOfConfigFile/ConceptOfConfigFile.md)  
-- [Structure of the CONFIGfile](../../ElementsApplicationPattern/Functions/ConceptOfConfigFile/ConceptOfConfigFile.md)  
+- [Structure of the CONFIGfile](../../ElementsApplicationPattern/Functions/StructureOfConfigFile/StructureOfConfigFile.md)  
 - [ONF Core Information Model](../../ElementsApplicationPattern/InformationModel/Overview/Overview.md)  
 
 
@@ -31,7 +31,7 @@ Several need to be added, and it is recommended to copy and paste the existing o
 
 - Use CTRL+h for replacing 'xx-1-0-0' by the abbreviation of your application's name and release number e.g. 'ro-2-0-1'.  
 - Use CTRL+f for searching '"http-server-interface-1-0:http-server-interface-pac":', and update the information about your application. Keep being consistent with the ServiceList.  
-- Use CTRL+f for searching '"tcp-server-interface-1-0:tcp-server-interface-pac":', and update the FakeIP address information of your application. Keep being consistent with the ServiceList. It might be required to add or delete a TcpServer instance.  
+- Use CTRL+f for searching '"tcp-server-interface-1-0:tcp-server-interface-pac":', and update the fake TCP port of your application. Keep being consistent with the ServiceList. It might be required to add or delete a TcpServer instance.  
 
 #### Profiles
 
@@ -59,7 +59,7 @@ Several need to be added, and it is recommended to copy and paste the existing o
 - Search for 'http-s-000",' and put the same UUIDs into the clientLtp list attribute.  
 
 - Check the HttpClients in the CONFIGfile and delete all stacks of OperationClients, HttpClients and TcpClients that belong to HttpClients that are not required in your ServiceList.  
-- Step through the HttpClients in your ServiceList and check, whether all the required OperationClients are available in the CONFIGfile. If not, copy a stack of one OperationClient, an HttpClient and a TcpClient, adapt the values of the applicationName and releaseNumber attributes at the HttpClient and the fakeIP address and port at the TcpClient. Take care that the UUIDs at the three new objects get update with the official abbreviation of the application's name.  
+- Step through the HttpClients in your ServiceList and check, whether all the required OperationClients are available in the CONFIGfile. If not, copy a stack of one OperationClient, an HttpClient and a TcpClient, adapt the values of the applicationName and releaseNumber attributes at the HttpClient and the fake TCP port at the TcpClient. Take care that the UUIDs at the three new objects get update with the official abbreviation of the application's name.  
 - Double check that all the HttpClients of the ServiceList are now covered in the same ordering as in the CONFIGfile.  
 - Step through the list of HttpClients in the CONFIGfile and check, whether all the OperationClients from the ServiceList are available in the CONFIGfile. If not, copy an existing OperationClient object on the same HttpClient and replace the value of the operationName attribute. Delete obsolete OperationClient objects. Update the clientLtp list attribute at the HttpClient objects.  
 - After you updated the OperationClients at all the HttpClients, double check whether the ordering of the OperationClients is consistent with the ServiceList.  

doc/SpecifyingApplications/CreatingProfileInstanceList/CreatingProfileInstanceList.md

@@ -87,18 +87,9 @@ This is a step by step cookbook for creating the _ProfileInstanceList_.
 * Document the content of the file.  
 * Even if the exact format of the information is to be defined by the implementer, the information could be listed here.  
 
-**file-path**  
+**file-name**  
 * The content of this field is actually determined by the implementer.  
-* Maybe, '../application-data/application-data.json' is a good choice for being a default value.  
-
-**UserName**  
-* This field is not mandatory.  
-* If access to the file shall be protected by user name and password, some value should be added here.  
-* Maybe, the application's name is a good choice.  
-
-**Password**  
-* This field is not mandatory.  
-* If access to the file shall be protected by user name and password, some value should be added here.  
+* Maybe, 'application-data.json' is a good choice for being a default value.  
 
 **Operations**  
 * This field allows restricting the access rights of the application to the file.