ApplicationPatternDocumentation.md

ApplicationPattern Modules Documentation

Purpose

The purpose of this document is to outline the technical design of the application pattern generic modules in detail.

It is detailing

• the functionality provided by each class/file in the modules
• the functionality, which will be provided by each component and shows how various components interacts in the design

This document will be updated based on the changing requirement in the application pattern specification.

Scope

The application pattern design charted in this document is based on the scope defined in the requirement (OAS).
This document is not intended to address the installation and configuration of the deployment.

Introduction

Application pattern module is a ready-made framework that provides components and solutions that has generic functionalities specific to the SDN application pattern microservice specifications.

This framework provides APIs,

• to manipulate the LOADfile, which is in the ONF Core model.
• to configure and automate the forwardings between applications (please refer chapter about ForwardingList to learn more about forwarding)
• to log the service and the oam request to ExecutionAndTraceLog and OamLog application respectively.
• to validate authentication by interacting with the AdministratorAdministration application.

By including this already existing framework, one can focus on business logics rather than developing their own logic to provision their application into the microservice architecture.

Application Pattern Modules Overview

The following application pattern modules are each described in one of the subsequent chapters:

• Callbacks
• Database
• DatabaseDriver
• Logging
• onfModel
• Rest
• Security
• Softwareupgrade

CALLBACKS Module

(up ↑) Callback module provides functionality to formulate and dispatch the HTTP request to a target REST server.

The callback module has the following components:

• requestBodyFactory
  • basicservices.js
  • individualServices.js
• eventDispatcher.js

requestBodyFactory

The requestBodyFactory provides functionality for formulating the request body of HTTP requests for both basic services and individual services.

---

basicservices.js

Provides functionality to formulate HTTP request body for the forwarding HTTP requests that are part of the basic services. This module is generic across all the application that are having core-model-1-4:control-construct as the root entity of their LOADfile.

Functions:

Method and description	Input parameters	Return type
prepareRequestBody: this function formulates and returns the request body based on the operationName, clientApplicationName and the attribute list passed from the service layer.	{String} clientApplicationName name of the client application. {String} operationName name of the client operation that needs to be addressed. {String} attributeList list of attributes that needs to be included in the request body based on the operation name.	{Promise} httpRequestBody formulated JSON HTTP request body.

individualservices.js

Provides functionality to formulate HTTP request body for the forwarding HTTP requests that are part of the individual services. This file should be modified according to the individual service forwarding requirements.eventDispatcher.js.

Functions:

Method and description	Input parameters	Return type
prepareRequestBody: this function formulates and returns the request body based on the operationName, clientApplicationName and the attribute list passed from the service layer.	{String} clientApplicationName name of the client application. {String} operationName name of the client operation that needs to be addressed. {String} attributeList list of attributes that needs to be included in the request body based on the operation name.	{Promise} httpRequestBody formulated JSON HTTP request body.

eventDispatcher.js

This module provides functionalities to trigger and dispatch the HTTP REST request from this application to other applications.
This module associates with the requestBodyFactory to formulate the httpRequestBody in JSON format and interacts with the Axios REST client in the rest/client module to trigger the formulated HTTP request.

Functions:

Method and description	Input parameters	Return type
dispatchEvent: This function formulates the HTTP request header and body and dispatches the event to the corresponding target REST server.	{String} serviceType provides "basic" if the service comes from the basicservice layer or "individual" otherwise. {String} serviceType provides "basic" if the service comes from the basicservice layer or "individual" otherwise. {String} remoteIpAndPort ip address and port of the client application in the format <ipaddress>:<port>. {String} clientApplicationName name of the client application to which the request is going to be sent. {String} operationKey operation key to access the service in the client application. {String} attributeList list of attribuges that needs to be included in the request body based on the operation name. {String} user username of the request iniator. {String} xCorrelator UUID for the service execution flow that allows to correlate requests and responses. {String} traceIndicator sequence number of the request. {String} customerJourney holds information supporting the customers journey to which the execution applies.	{Promise} true if the operation is successful.

DATABASE Module

(up ↑) This folder contains load.json file that consists of the ONF CoreModel representation of the application configuration.

DATABASEDRIVER Module

(up ↑) This module consists of functionalities, which we can interact with the load.json file in ONF CoreModel.

JSONDriver.js

This class provides functionality to perform CURD operation on the JSON database LOADfile, which is in the ONF CoreModel format.
The interaction with the file system will be performed with the use of 'fs module', which enables interacting with the file system in a way modeled on standard Portable Operating System Interface for UNIX(POSIX) functions.
Also, by using the 'path' module that provides utilities for working with files and directory paths. This module uses its own mechanism to traverse the ONF model JSON file based on the provided JSONPath.

Please refer the following flow for the ‘readFromDatabase’ operation:

Please refer the following flow for the ‘write/deleteFromDatabase’ operation:

Functions:

Method and description	Input parameters	Return type
readFromDatabase This function reads the requested JSONPath from the core-model.	{String} JSONPath JSON path that leads to the destined attribute.	return the requested value.
writeToDatabase This function updates an existing instance or creates a new instance in the LOADfile which is in ONF CoreModel based on the JSONPath and input parameters.	{String} JSONPath JSON path that leads to the destined attribute. {JSONObject|String} valueToBeUpdated value that needs to be updated. {boolean} isAList a boolean flag that represents whether the value to be updated is a list instance.	return true if the value is updated, otherwise return false.
deleteFromDatabase This function deletes the requested data in the JSONPath from the core-model.	{string} JSONPath JSON path that leads to the destined attribute. {JSONObject|String} valueToBeDeleted value that needs to be deleted. {boolean} isAList a boolean flag that represents whether the value to be deleted is a list.	{Promise} return true if the value is deleted, otherwise return false.

PrimaryKey.js

This file contains the primary key for the list attributes in core-model. If a new list is getting added, then the key attribute of the list should be updated in this file to make the JSONDriver functionalities to work as expected.

LOGGING Module

(up ↑)

ExecutionAndTraceService.js

This class provides functionalities to log the Service request to the ExecutionAndTraceLog application in the SDN microservice architecture. A REST call will be initiated from the current application to the ExecutionAndTracelog application to record the transaction happened in the service layer.

Functions:

Method and description	Input parameters	Return type
recordServiceRequest: This function formulates the request body with the required attributes that needs to be sent to record the service request in the ExecutionAndTraceLog application.	{string} xCorrelator correlation tag of the current execution. {string} traceIndicator sequence number of the execution. {string} userName name of the user who is accessed the service. {string} originator originator of the request. {string} operationName name of the called service. {string} responseCode response code of the REST call execution. {string} requestBody request body of the executed REST call. {string} responseBody response body of the executed REST call.	{Promise} return true if the operation is successful otherwise returns false.

OAMLogServices.js

This class provides functionality to log the OaM request to the OAMLog application in the SDN Microservice architecture.
A REST call will be initiated from this application to the OAMLog application to record the transaction happened in the OAM layer.

Functions:

Method and description	Input parameters	Return type
recordOamRequest: This function formulates the request body with the required attributes that needs to be sent to record the OaM request in the OamLog application.	{string} oamPath oam path that is accessed during the request. {string} requestBody incase if it is a put request, then the request body of the request. {string} responseCode response code of the REST call execution. {string} authorizationCode authorization code used to access the oam layer. This will then be decoded to find out the username. {string} method HTTP method of the OAM layer call. It can be PUT, GET.	{promise} return the requested value.

ONFMODEL Module

(up ↑) The detailed Onf model description covers details to the following contents and can be found here.

• model
  • CoreModel.js
• LogicalTerminationPoint.js
  • LayerProtocols.js
  • ForwardingDomain.js
  • ForwardingConstruct.js
  • ProfileCollection.js
  • Profile.js
• LayerProtocol
  • TcpServerInterface.js
  • HttpServerInterface.js
  • OperationServierInterface.js
  • TcpClientInterface.js
  • HttpClientInterface.js
    • OperationClientInterface.js
• profiles
  • Application Profile.js
• Services
  • LogicalTerminationPointService.js
    • ForwardingConstructServices.js
  • Utility
    • ONfAttributeFormatter.js

REST Module

The rest module description contains the following content:

• Client
  • Client.js
  • RequestBuilder.js
  • RequestHeader.js
• Server
  • ResponseBuilder.js
  • RequestHeader.js
  • responseBody
    • ConsequentAction.js
    • ResponseValue.js

Client

(up ↑) The module in this package provides a REST client which is used to communicate with the REST server in other applications.

---

Client.js

This module provides functionality to perform HTTP request to client application. It uses the AXIOS package as a REST client.

Function:

Method and description	Input parameters	Return type
post This function performs HTTP POST method.	{object} request object that consists of the httpRequestBody, httpRequestHeader, url.	{promise} return the response code.

RequestBuilder.js

This module provides functionality to construct a REST request.

Function:

Method and description	Input parameters	Return type
BuildAndTriggerRESTRequest This function triggers a REST request by calling the RESTClient	{string} remoteIpAddressAndPort ip address, port of the client application in the format :. {string} operationName service that needs to be addressed in the client application. {string} method HTTP method for the REST request. {string} requestHeader HTTP request header for the REST call. {string} requestBody request body for the REST call.	{promise} returns the HTTP response received.

RequestHeader.js

This class provides functionality to create a HTTP request header.

Field summary:

Type	Field
String	user
String	originator
String	xCorrelator
String	traceIndicator
String	customerJourney
String	operationKey
String	contentType

Constructor summary:

Constuctor and description

parameters

This instantiates a new Request header instance.

{String} user identifier from the system starting the service call. If not available, originator value will be copied to this attribute. {String} xCorrelator UUID for the service execution flow that allows to correlate requests and responses. {String} traceIndicator Sequence of request numbers along the flow, if it is empty, set it to 1. {String} customerJourney Holds information supporting customer’s journey to which the execution applies. {String} operationKey operation key to access the service in the client application.

Method Summary:

Method and description	Input parameters	Return type
xCorrelatorGenerator This function generates a xCorrelator based on the regular expression provided in the specification.		{promise} return the xCorrelator.

Server

(up ↑) The modules and classes in this package provide functionality to support the REST server to formulate the HTTP response (header, body, response code) as per the requirement of the "ApplicationPattern specification".

---

ResponseBuilder.js

This module provides functionality to build the HTTP response object.

Function:

Method and description	Input parameters	Return type
buildResponse This function builds the HTTP response object.	{JSONObject} response HTTP response object. {String} responseCode HTTP response code. {JSONObject} responseBody HTTP response body. {JSONObject} responseHeader HTTP response header.

RequestHeader.js

This class provides functionality to create a HTTP response header.

Field summary:

Type	Field
String	xCorrelator
String	execTime
String	backendTime
String	lifeCylceStatement
String	contentType

Constructor summary:

Constuctor and description

parameters

This instantiates a new response header instance.

{String} xCorrelator User identifier from the system starting the service call. If not available, originator value will be copied to this attribute. {String} execTime Identification for the system consuming the API, name of the current application. {String} backendTime UUID for the service execution flow that allows to correlate requests and responses. {String} lifeCycleState Sequence of request numbers along the flow, if it is empty, set it to 1.

Method Summary:

Method and description	Input parameters	Return type
xCorrelatorGenerator This function generates a xCorrelator based on the regular expression provided in the specification.		{promise} return the xCorrelator.
executionTimeInMilliseconds This function calculates the execution time for processing the request.	{JSONObject} startTime start time of the request.	{promise} return the execution time in milli seconds.
createResponseHeader This function creates response header based on the provided input values.	{JSONObject} xCorrelator of the request. {JSONObject} startTime start time of the request. {JSONObject} operationName of the request.	{promise} return the response header.

responseBody

This package contains classes that are used to represent generic response bodies.

---

ConsequentAction.js

This class provides a stub for the consequent action list.

Field summary:

Type	Field
String	label
String	request
String	displayInNewBrowserWindow

Constructor summary:

Constuctor and description	parameters
This instantiates a new consequent action list.	{String} label of the consequent action. {String} request url that needs to be addressed to perform the consequent action. {String} displayInNewBrowserWindow should be true if the consequent action needs to be displayed in a new tab.

ResponseValue.js

This class provides a stub for the consequent action list.

Field summary:

Type	Field
String	fieldName
String	value
String	datatype

Constructor summary:

Constuctor and description	parameters
This instantiates a new ResponseValue object.	{String} fieldName field name of the response value. {String} value of the field name. {String} datatype data type of the value.

SECURITY Module

(up ↑) This package contains modules that provides authorizing service.

AuthorizingService.js

This module provides functionality to authenticate an OAM layer request by getting an approval from the AdministratorAdministration.

Function:

Method and description	Input parameters	Return type
isAuthorized This function authorizes the user credentials.	{string} authorizationCode authorization code received from the header. {string} method is the https method name.	{boolean} return the authorization result.

AuthorizationDecoder.js

This module provides functionality to decode an authorization code.

Function:

Method and description	Input parameters	Return type
decodeAuthorizationCodeAndExtractUserName To decode base64 authorization code from authorization header.	{string} authorizationCode base64 encoded authorization code.	{Promise} returns user name based on the decoded authorization code.

SOFTWAREUPGRADE Module

(up ↑)

BequeathYourDataAndDie.js

This module provides functionality to migrate data from the current version to the next version. This file should be modified according to the individual service forwarding requirements.

Up to ImplementingApplications