Knowhow-api NPM

knowhow-api

This is a node.js api for connect and manipulating a knowhow server. A command line tool that exposes the API to bash, KHCommand, is also provided for shell scripting. Uses of this API include:

creating and deleting repositories
add and deleting file in repositories
adding and deleting agents
executing jobs
executing other knowhow jobs from knowhow itself

Installation

This is installed by default when installing knowhow package. If you want to install this package individually

	npm install -g knowhow-api

Examples

List all active repositories on a knowhow server

	var serverURL = "http://localhost:3001";
	var khClient =  require('knowhow-api')(serverURL);
	khClient.khRepository.listRepositories(function(err, repos) {
	  	if (err) {
	  		console.log("unable to get repositories: "+err.message);
			console.log(err.stack);
			callback(err);
			return;
	  	}
	  	console.log(repos);
	});

or using KHCommand

	KHCommand listRepositories http://localhost:3001

Execute a job on a knowhow server

	var serverURL = "http://localhost:3001";
	var khClient =  require('knowhow-api')(serverURL);
	testJob = { "jobRef": "MyRepo://jobs/dummyJob.json"}
	khClient.khJob.executeJob(agent, createAgentJob, function (err, result) {
		
	});

or using KHCommand

	KHCommand executeJob http://localhost:3001 '{"host": "container02", "user": "serverClub", "password": "serverClub", "port": 3141}' '{"jobRef": "zenzic:///jobs/dummyJob.json"}'

Add/delete an agent

	var serverURL = "http://localhost:3001";
	var khClient =  require('knowhow-api')(serverURL);
	var agentInfo = {
			"host": "myHost",
			"user": "myUser",
			"password": "myPassword",
			"port": 3141
		};
	
	//add agent
	khClient.khAgent.addAgent(agentInfo, function(err, addedAgent) {
	
	});
	
	//delete agent
	khClient.khAgent.deleteAgent(agentInfo, function(err, deletedAgent) {
	
	});

or using KHCommand: KHCommand.sh addAgent http://localhost:3001 '{"host": "container02", "user": "serverClub", "password": "serverClub", "port": 3141}'

Import a repository from GIT

	var exampleRepo = {
		"name": "knowhow-example",
		"path": "/tmp/knowhow-example"
	};
	var gitURL = "https://github.com/jfelten/knowhow_example_repo.git";
	var gitUser = undefined;
	var gitPassword = undefined;
	khClient.khRepository.importFileRepositoryFromGit(exampleRepo, gitURL, gitUser, gitPassword, function(err, loadedRepo) {
	});

Download a repository as a tarball

	khClient.khRepository.downloadRepoAsTarBall(exampleRepo, './testRepo.tar.gz', function(err, savedPath) {
	});

Execute a workflow

	khClient.khRepository.loadURL("knowhow-example:///environments/test/environment.json", function(err, testEnvironment) {
		if (err) {
			console.log(err.stack);
			return;
			throw err;
			prcoess.exit(1);
		}
		//connect all the agents for the environment
		khClient.khWorkflow.connectEnvironmentAgents(testEnvironment, function(err) {
		
			if (err) {
				throw err;
				prcoess.exit(1);
			}
			//load a test workflow and execute it
			khClient.khRepository.loadURL("knowhow-example:///workflows/test/testWorkflow.json", function(err, testWorkflow){
				if (err) {
					throw err;
					prcoess.exit(1);
				}
				khClient.khWorkflow.executeWorkflow(testEnvironment, testWorkflow,function(err, workflowREsult) {
					process.exit(0);
				});
				
			});
		});
	});

other examples:

add a file to a repository, create a new repository, delete a repository, delete a file in a repository

knowhow urls

All files and resources on a knowhow server are designed to be accessed in url syntax:

	<REPO_NAME>://<PATH_TO_RESOURCE>

For example: MyRepo:///jobs/myJob.json would refer to the file myJob.json located in the jobs folder of the MyRepo repositorhy

Events

An event listener is provided to listen for the following server side events:

'agent-update'
'agent-error'
'agent-delete'
'agent-add'
'job-start'
'job-update'
'job-cancel'
'job-complete'
'job-error'
'cancel-job-on-agent'
'execution-start'
'execution-complete'
'execution-error'
'execution-password-prompt'

Example: var serverURL = "http://localhost:3001"; var khEventHandler = require('knowhow-api').khEventsHandler(serverURL); khEventHandler.on("job-complete", function(job) { console.log("done event"); });

API

Agent API (accessed via khClient.khAgent)

Functions

Kind: global function

Param	Description
agentInfo	agentInfo only host is requred - ex: {"host": "myHost", "port": 3141, "user": "MyUSer", "passwordEnc": "DSAF@#R##EASDSAS@#"}
callback	callback function with parameters (error, agentInfo)

addAgentSync(agentInfo)

Synchronous version of addAgent call

Kind: global function

Param	Description
agentInfo	json representaion of the agent to add

updateAgent(agentInfo, callback)

Updates agent info with values specified in agentInfo

Kind: global function

Param	Description
agentInfo	agentInfo must specify _id - ex: {"_id": "1234:", "host": "myHost", "port": 3141, "user": "MyUser", "passwordEnc": "DSAF@#R##EASDSAS@#"}
callback	callback function with parameters (error, agentInfo)

deleteAgent(agentInfo, callback)

deletes an agent on a knowhow server

Kind: global function

Param	Description
agentInfo	agentInfo must specify _id - ex: {"_id": "1234"}
callback	callback function with parameters (error, agentInfo)

deleteAgentSync(agentInfo) ⇒

deletes an agent on a knowhow server

Kind: global function
Returns: agent or undefined if it didn't work

Param	Description
agentInfo	agentInfo must specify _id - ex: {"_id": "1234"}

resetAgent(agentInfo, callback)

resets an agent on a knowhow server by stopping and restarting.

Kind: global function

Param	Description
agentInfo	agentInfo only host is requred - ex: {"host": "myHost", "port": 3141, "user": "MyUSer", "passwordEnc": "DSAF@#R##EASDSAS@#"}
callback	callback function with parameters (error, agentInfo)

resetAgentSync(agentInfo)

Synchronous version of addAgent call

Kind: global function

Param	Description
agentInfo	json representaion of the agent to add

getAgentInfo(agentInfo, callback)

retrives agent info base on _id.

Kind: global function

Param	Description
agentInfo	agentInfo must specify _id - ex: _id: "1234"
callback	callback function with parameters (error, agentInfo)

getAgentLogs(agentInfo, callback)

retrives agent info base on _id.

Kind: global function

Param	Description
agentInfo	agentInfo must specify _id - ex: 1234
callback	callback function with parameters (error, agentInfo)

getAgentList(callback)

retrieves a list of all agents on a knowhow server

Kind: global function

Param	Description
callback	callback function with parameters (error, agentInfo)

agentHeartbeat(agent, callback) ⇒

Checks if an agent is alive by attempting to contact it through the server.

Kind: global function
Returns: {alive: true} if the agent can be reached.

Param	Description
agent	agent json
callback

waitForAgentStartup(agent, callback) ⇒

Waits for an agent to start up and returns when done. Used for flow control in scripts.

Kind: global function
Returns: {alive: true} if the agent can be reached.

Param	Description
agent	agent json
callback

Repository API (accessed via khClient.khRepository)

Functions

Kind: global function

Param	Description
serverURL
callback	function to call when done with parameters (error, repoList)

loadRepoFromName(repoName, callback)

loads a populated repo json object based on a name

Kind: global function

Param	Description
repoName	the name of the repositry
callback	callback function to execute when complete with parameters (error, repoObject)

addRepo(newRepo)

Adds a new repository to a knowhow server specified by param serverUDL

Kind: global function

Param	Description
newRepo	A json object describing the new repository with parameters (error, repoObject)

updateRepo(serverURL, existingRepo, callback)

Modifies an existing repo obejct on a knowhow server with the values specified in the repo object

Kind: global function

Param	Description
serverURL	the URL of the knowhow server ex :http://localhost:3001
existingRepo	a json object describing a repository - _id must be specified
callback	callback functions with parameters (error, modifiedRepoObject)

deleteRepo(repo, callback)

Deletes a repository on a knowhow server

Kind: global function

Param	Description
repo	a json object representing the repo to delete - _id must be specified
callback	callback function with parameters (error, deletedRepo)

loadRepo(repo, subDir, callback)

Returns a directory tree structure starting at a specified subDir- used to load a tree widget

Kind: global function

Param	Description
repo	a json object representing a repository to use
subDir	the point in the repository to start - ex: /jobs
callback	callback function with params (error, repoTree)

addFile(path, newFile, content, isDirectory, callback)

Adds a file to specified repository

Kind: global function

Param	Description
path	the repository path of the file - ex: /jobs/myJob.json
newFile	new file name
content	text content of the file to add
isDirectory	flag for whether of not file is a directory
callback	callback function with parameters (error, newFile)

deleteFile(filePath, force, callback)

Deletes specified file from a repository

Kind: global function

Param	Description
filePath	the absolute directory structure of the file to delete ex /myRepo/job/myJob.json
force
callback	callback function with parameters (error, deletedFile)

saveFile(filePath, fileContent, callback)

saves a file in the specified filePAth on a knowhow server

Kind: global function

Param	Description
filePath	the absolute directory path of a specified file on the knowhow server host
fileContent	the text content of the file
callback	callbacj function with params (error, file)

loadURL(URL)

retrieves an environment object from a knowhow URL

Kind: global function

Param	Description
URL	the knowhow URL we are attempting to load

importFileRepositoryFromGit(repo, gitURL, gitUser, gitPAssword, callback)

Imports a repository from a git server Url into a new file repository.

Kind: global function

Param	Description
repo	a json object with the expected repo values: name and path
gitURL	URL of the git repository
gitUser	if supplied will attempt to use as part of the url
gitPAssword	use only if server requires password authentication
callback	to execute when finished

importFileRepositoryFromTarBall(repo, tarBallFile, callback)

Imports a repository from a tarball(.tar.gz) file

Kind: global function

Param	Description
repo	a json object with the expected repo values: name and path
tarBallFile	the file path of the tarball file
callback	to execute when finished

importFileRepositoryFromServer(repoToCreate, KHHostRepoName, KHServerURL, callback)

Imports a repository from a a knowhow server

Kind: global function

Param	Description
repoToCreate	a json object with the expected repo values: name and path
KHHostRepoName	the name of the repo on the knowhow server we are importing from
KHServerURL	the url of the knowhow server
callback	to execute when finished

downloadRepoAsTarBall(repo, savePath)

Downloads a knowhow repository as a tarball. This tarball may be reimport as a new repository on any knowhow server.

Kind: global function

Param	Description
repo	the knowhow repository to download
savePath	where to save the tarball

KHRepository(serverURL, EventHandler)

Factory method for KHJob

Kind: global function

Param	Description
serverURL	the url of the server
EventHandler

loadFile : function

Loads a File from the specified repository

Kind: global typedef

Param	Description
serverURL	the URL of the knowhow server ex :http://localhost:3001
repo	a json object representing a repository to use
path	the repository path of the file - ex: /jobs/myJob.json

Job API (accessed via khClient.khJob)

Functions

Kind: global function

Param	Description
agent	agentInfo _id is required is requred - ex: {_id: "1234"}
job	a json job to execute
callback	callback function with parameters (error, agentInfo)

executeJobSync(agentInfo, job)

Synchronous version of addAgent call

Kind: global function

Param	Description
agentInfo	json representaion of the agent to add
job	to run

cancelJob(agent, job, callback)

Cancels a running job on a knowhow server

Kind: global function

Param	Description
agent	agentInfo _id is required is requred - ex: {_id: "1234"}
job	a json job to execute
callback	callback function with parameters (error, agentInfo)

getRunningJobsList(agent, callback)

Retreives a list of currently executing jobs on a knowhow server

Kind: global function

Param	Description
agent	agentInfo _id is required is requred - ex: {_id: "1234"}
callback	callback function with parameters (error, runningJobList)

KHJob(serverURL, EventHandler)

Factory method for KHJob

Kind: global function

Param	Description
serverURL	the url of the server
EventHandler

Workflow API (accessed via khClient.khWorkflow)

Functions

Kind: global function

Param	Description
environment	the environment to load

connectEnvironmentAgents(environment)

Ensures that all agents for an environment are running. IF a defined agent does not exist an attempt is made to add it.

Kind: global function

Param	Description
environment	an environment json object

executeWorkflow(environment, workflow, callback)

Executes a workflow on a knowhow server

Kind: global function

Param	Description
environment	json environment representation (i.e. collection of knowhow agents that represent the environment)
workflow	a json workflow to execute
callback	callback function with parameters (error, agentInfo)

executeWorkflowSync(environment, workflow)

Synchronous version of addWorkflow call

Kind: global function

Param	Description
environment	json representaion of the workflow's environment
workflow	to run

cancelWorkflow(environment, workflow, callback)

Cancels a running workflow on a knowhow server

Kind: global function

Param	Description
environment	environment to cancel
workflow	a json workflow to execute
callback	callback function with parameters (error, agentInfo)

getRunningWorkflowsList(callback)

Retreives a list of currently executing workflows on a knowhow server

Kind: global function

Param	Description
callback	callback function with parameters (error, runningJobList)

KHWorkflow(serverURL, khEventHandler, the, khClient)

Factory method for KHWorkflow

Kind: global function

Param	Description
serverURL	the url of the server
khEventHandler	EventHandler
the	khJob object for this workflow engine
khClient

Event API (accessed via khClient.khEventHandler)

commits since last release

	Merge branch 'master' of https://github.com/jfelten/knowhow-api.git

fix tests, agent/workflow callbacks 0.0.20 updated documentation fix more jsdoc tags fixed @returns annotation fix documentation typo expose wait for startup and heartbeat methods in agent api Merge branch 'master' of https://github.com/jfelten/knowhow-api.git added heartbeat and waitForStartup methods for better scripting control flow when automatically starting and stopping knowhow servers and agents. Added a test for KHCommand. 0.0.19 updated documentation Merge branch 'master' of https://github.com/jfelten/knowhow-api.git 0.0.18 updated documentation added space to render properly on github Update aPI tempalte updated documentation to fix npm formatting issues and to break up apis into separate sections Merge branch 'master' of https://github.com/jfelten/knowhow-api.git 0.0.17 updated documentation fix documentation so it renders properly on github added new examples Completed workflow API, Added additona tests, fix agent api runtime errors added workflow commands Merge branch 'master' of https://github.com/jfelten/knowhow-api.git fix load URL call fix typo 0.0.16 updated documentation Merge branch 'master' of https://github.com/jfelten/knowhow-api.git add latest repository functions to KHCommand added repository page functions to API as well as eom real unit tests 0.0.15 updated documentation Merge branch 'master' of https://github.com/jfelten/knowhow-api.git 0.0.14 updated documentation fix runtime error - make error handling a little mroe robust Merge branch 'master' of https://github.com/jfelten/knowhow-api.git fix environment substitution and add more verbose command output 0.0.13 updated documentation 0.0.12 updated documentation 0.0.11 updated documentation fix KHCommand error handling 0.0.10 updated documentation Merge branch 'master' of https://github.com/jfelten/knowhow-api.git fixed job execution api and agent createion api. properly parse json objects from command line tool. Correct callback after job execution. Updated documentation to reflect correct usage examples 0.0.9 updated documentation updated version updated test added travis buiuld icon added build test Merge remote-tracking branch 'origin/master' added travis file 0.0.7 updated documentation Merge branch 'master' of https://github.com/jfelten/knowhow-api.git fix execution issues job execution fixes 0.0.6 updated documentation 0.0.5 updated documentation Update README.md incremented version fix command line doc generation Merge remote-tracking branch 'origin/master' moved to a client model for easier event management moved to a client model where events are managed for synchronous processing 0.0.3 updated documentation fix package executable error Merge remote-tracking branch 'origin/master' fixed event list Update README.md 0.0.2 updated documentation configured readme generation fixed js doc issues refactored fix compile error initial add first commit