0.0.1 • Published 9 years ago

matr-db v0.0.1

Weekly downloads
9
License
Mattersight
Repository
github
Last release
9 years ago

#Analysis Data API A Node.js implementation of a RESTful service that provides 3 basic resources for accessing call level data.

  • Retrieve a list of available calls based on a date range
  • Retrieve meta-data associated with a specific call
  • Retrieve the WAV file associated with a specific call

##Table of Contents TOC

##Main App

The app runs as a Windows service an application server, connects to the backend database server that contains the call data, and listens for REST requests over HTTPS.

The app requires node and npm on the application server was tested with following versions of node and npm:

$ node -v
v0.10.25
$ npm -v
1.4.21

###Supporting Elements The app (Windows service) itself relies on several database objects on the database server. These objects are some stored procedures and synonyms, in a component specific schema.

The app relies on an exe to obtain the encryption key necessary to decrypt the WAV file associated with a call.

##Packaging The app and its supporting elements are packaged as npm package. The package contains the app, the supporting elements, as well as a test client app.

The package also contains installation scripts for the app, the Windows service, and the database objects.

The package.json file defines all the node dependencies of the app and supporting elements.

##Installation ###Manual Installation The overall process of manual installation is: unpack the package, get all the Node.js module dependencies, copy the files to the target server, install the Windows service, install database objects, configure the app, and go.

Getting all the Node.js dependencies requires access to the npm public registry. If the target server has this access then the file copy step is from a working directory to a final directory on the same server. If not, then the file copy is between two servers.

####Step 1: Install the npm package to a working location

  • Ensure the working server has node and npm installed, and has access to the npm public registry.
  • Create a working directory on the server.
  • Put the package file into the working directory.
  • Go to the working directory.
  • Run "npm install package name".

The npm install process will unpack the package, and get all the node dependencies from the npm registry. When completed the package content and all node modules will be in the following folder: node_modules/analysis-data-api.

Example:

mkdir c:/jenkins/workspace/AnalysisDataAPI
xcopy source c:/jenkins/workspace/AnalysisDataAPI
cd c:/jenkins/workspace/AnalysisDataAPI
npm install analysis-data-api.0.0.0.123.tgz
dir node_module/analysis-data-api

####Step 2: Copying files to target location

  • Ensure the target server has node installed.
  • On the target server create the component root folder as "Mattersight/components/AnalysisDataAPI" at the root of the target disk drive (c:, x:, etc.).
  • Copy the following folders from the working directory to the component root folder:
    • app_main
    • app_client
    • lib
    • node_modules
    • stub
    • _config
    • tools
    • Databases

Example:

mkdir x:/Mattersight/components/AnalysisDataAPI
cd x:/Mattersight/components/AnalysisDataAPI
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/app_main 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/lib 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/node_modules 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/stub 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/_config 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/tools 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/Databases 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/app_client 
xcopy c:/jenkins/workspace/AnalysisDataAPI/node_modules/analysis-data-api/media

####Step 3: Installing the Windows service

  • On the target server go to the component root for the Analysis Data API.
  • Run "node tools/installService.js" to install the app as a Windows service. This script expects the app to be located at Mattersight/components/AnalysisDataAPI on the drive upon which you are running the install script.

Example:

cd x:/Mattersight/components/AnalysisDataAPI
node tools/installService.js

The install process will uninstall the service named AnalysisDataAPI and create a new service named AnalysisDataAPI. The Windows service settings can be adjusted manually (the service account, startup mode, etc.)

####Step 4: Installing the database objects

  • On the target server go to the component root for the Analysis Data API.
  • Edit _config/db.json to set the correct database connection property values for the environment. The configuration properties that the database installation script depends upon are connection and databases.
    • connection.database must be a property in databases.
    • databases is an object with the properties being the generic database name (e.g., ccp, cca, etc.) and the value being the name of that database in the target environment.
  • Run "node tools/installDatabase.js" to install the database objects.

Example:

cd x:/Mattersight/components/AnalysisDataAPI
node tools/installDatabase.js

Example configuration:

"connection": {
	"server": "111.222.333.444",
	"port": 1433,
	"database": "ccp",
	"pool": {
		"max": 10,
		"min": 0,
		"idleTimeoutMillis": 30000
	}
},
"databases": {"ccp": "OrangeCCP"},

Note: The installDatabase script uses Integrated Authentication to connect to the database server, and will execute all the SQL scripts in the Databases/CCP/DDL folder.

The database objects can also be installed by any other means, such as via SSMS.

####Step 5: Configuring the Analysis Data API To this point you've already update the database connection configuration as a necessary pre-requisite for the installation of the database objects. These additional configuration items on the target server can be done at any point past copying the files to the target server.

#####HTTPS certificates _config/config.server.json has a property named https that in turn has 3 properties for specifying the SSL certificates: key, cert, and ca.

#####OAUTH2 _config/oauth.server.json has two properties named oAuthClients and users

The oAuthClients property is an array of client objects, each defining a clientId, a clientSecret, and a redirectURL. The clientId and clientSecret values that are provided to API users for oAuth authentication must be in this array. The redirectURL is not used by the app.

The users property is an array of user objects, each defining an id, username, and password. The username and password values that are provided to API users for oAuth authentication must be in this array. The id is not used by the app.

Example:

{	"oauthClients": [
		{	"clientId": "test",
			"clientSecret": "test",
			"redirectUri": ""
		}
	],
	"users": [
		{	"id": "456",
			"username": "test",
			"password": "test"
		}
	]
}

#####Client specific meta-data _config/db.json has a property named exposedAnalysisData that is an array of strings or objects. A string value is the name of a column in CCP.dbo.AnalysisData that is to be provided in the meta-data response with the same name as the column. An object has two properties column and label that allow the property in the meta-data response to be labeled differently from the column name.

Example:

"exposedAnalysisData": [
	{"column": "customerAccountNumber", "label": "customerBANID"},
	"CustomerTenure"
}

Note: CCP.dbo.AnalysisData is a table whose content is client specific. The stored procedure the app uses to get the meta-data is not client specific. Hence the purpose of this configuration item is to convey to the app what client specific data is actually desired for any given instance of app.

#####API resource constraints _config/config.server.json has a property named resourceConstraints that is an object with one resource constraint property. resourceConstraints.availableCalls.maxTimespan is the maximum number of seconds between the from and to dates in an availableCalls request.

Example:

"resourceConstraints" : {
	"availableCalls": {
		"maxTimespan": 3600
	}
}

Note: There are other properties in config.server.json, but there is no reason the default values should be altered.

#####Logging settings _config/logger.json has a properties for setting the logging level for events (Windows event log), console, and log file. Normal operation should use the default values. The default values are:

{	"console_level": "info",
	"winlog_level": "info",
	"winlog_source": "AnalysisDataAPI",
	"file_level": "debug",
	"filename": "./log/app.log",
	"maxsize": 100000,
	"maxFiles": 3
}

#####SafeNet.exe location _config/cmd.json has a property named win32 for specifying the location of the SafeNet.exe.

The default config assumes the SafeNet application and all its components to be placed to .\stub\MockSafeNet directory. The package contains this folder. No need to change this setting unless the desire is to use a SafeNet.exe located elsewhere.

####Step 6: Start the Windows service Set the account for the Windows service to an account that has rights to execute stored procedures on the database. Start the service.

####Step 7: Optional run the test client The app_client is a test application that will access the API over HTTPS, get an oAuth bearer token, make one request to availableCalls, and get the metadata and WAV files for the calls provided in the response. This test app requires the database objects in Databases/CCP/dev be installed in lieu of the objects in Databases/CCP/DDL. There are no scripts provided to install these test database objects. To run the test app:

  • Install the test database objects in Databases/CCP/dev.
  • Run node app_client/app.js
  • Re-install the database objects in Databases/CCP/DDL.

Example:

node app_client/app.js

####Optional cleanup After installation is complete any files copied from the working directory to the target component root directory that are not needed by the app at run time can be optionally deleted. The unneeded folders are Databases, tools, app_client, and media.

matr-db-tool
@everything-registry/sub-chunk-2141matr-app
0.0.1

9 years ago

0.0.0

9 years ago