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

addAgent(agentInfo, callback): Adds a new agent to a knowhow server. If no login or password is specified it will attempt to scan for an already running agent on the specified host. If no port is specified the port 3141 is used. Plain text passwords may be used, but is discouraged. Use passowrddEnc to pass encrypted passwords that are descryped using the server's encrytion key
addAgentSync(agentInfo): Synchronous version of addAgent call
updateAgent(agentInfo, callback): Updates agent info with values specified in agentInfo
deleteAgent(agentInfo, callback): deletes an agent on a knowhow server
deleteAgentSync(agentInfo) ⇒: deletes an agent on a knowhow server
resetAgent(agentInfo, callback): resets an agent on a knowhow server by stopping and restarting.
resetAgentSync(agentInfo): Synchronous version of addAgent call
getAgentInfo(agentInfo, callback): retrives agent info base on _id.
getAgentLogs(agentInfo, callback): retrives agent info base on _id.
getAgentList(callback): retrieves a list of all agents on a knowhow server
agentHeartbeat(agent, callback) ⇒: Checks if an agent is alive by attempting to contact it through the server.
waitForAgentStartup(agent, callback) ⇒: Waits for an agent to start up and returns when done. Used for flow control in scripts.

## addAgent(agentInfo, callback) Adds a new agent to a knowhow server. If no login or password is specified it will attempt to scan for an already running agent on the specified host. If no port is specified the port 3141 is used. Plain text passwords may be used, but is discouraged. Use passowrddEnc to pass encrypted passwords that are descryped using the server's encrytion key

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

listRepositories(serverURL, callback): Lists all repositories on a server
loadRepoFromName(repoName, callback): loads a populated repo json object based on a name
addRepo(newRepo): Adds a new repository to a knowhow server specified by param serverUDL
updateRepo(serverURL, existingRepo, callback): Modifies an existing repo obejct on a knowhow server with the values specified in the repo object
deleteRepo(repo, callback): Deletes a repository on a knowhow server
loadRepo(repo, subDir, callback): Returns a directory tree structure starting at a specified subDir- used to load a tree widget
addFile(path, newFile, content, isDirectory, callback): Adds a file to specified repository
deleteFile(filePath, force, callback): Deletes specified file from a repository
saveFile(filePath, fileContent, callback): saves a file in the specified filePAth on a knowhow server
loadURL(URL): retrieves an environment object from a knowhow URL
importFileRepositoryFromGit(repo, gitURL, gitUser, gitPAssword, callback): Imports a repository from a git server Url into a new file repository.
importFileRepositoryFromTarBall(repo, tarBallFile, callback): Imports a repository from a tarball(.tar.gz) file
importFileRepositoryFromServer(repoToCreate, KHHostRepoName, KHServerURL, callback): Imports a repository from a a knowhow server
downloadRepoAsTarBall(repo, savePath): Downloads a knowhow repository as a tarball. This tarball may be reimport as a new repository on any knowhow server.
KHRepository(serverURL, EventHandler): Factory method for KHJob

## Typedefs

loadFile : function: Loads a File from the specified repository

## listRepositories(serverURL, callback) Lists all repositories on a server

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

executeJob(agent, job, callback): Executes a job on a knowhow server
executeJobSync(agentInfo, job): Synchronous version of addAgent call
cancelJob(agent, job, callback): Cancels a running job on a knowhow server
getRunningJobsList(agent, callback): Retreives a list of currently executing jobs on a knowhow server
KHJob(serverURL, EventHandler): Factory method for KHJob

## executeJob(agent, job, callback) Executes a 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)

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

loadAgentsForEnvironment(environment): loads all agents on an environment. Returns with the agent data fully populated
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.
executeWorkflow(environment, workflow, callback): Executes a workflow on a knowhow server
executeWorkflowSync(environment, workflow): Synchronous version of addWorkflow call
cancelWorkflow(environment, workflow, callback): Cancels a running workflow on a knowhow server
getRunningWorkflowsList(callback): Retreives a list of currently executing workflows on a knowhow server
KHWorkflow(serverURL, khEventHandler, the, khClient): Factory method for KHWorkflow

## loadAgentsForEnvironment(environment) loads all agents on an environment. Returns with the agent data fully populated

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

knowhow-api

knowhow-api

Installation

Examples

List all active repositories on a knowhow server

Execute a job on a knowhow server

Add/delete an agent

Import a repository from GIT

Download a repository as a tarball

Execute a workflow

other examples:

knowhow urls

Events

API

Agent API (accessed via khClient.khAgent)

Functions

addAgentSync(agentInfo)

updateAgent(agentInfo, callback)

deleteAgent(agentInfo, callback)

deleteAgentSync(agentInfo) ⇒

resetAgent(agentInfo, callback)

resetAgentSync(agentInfo)

getAgentInfo(agentInfo, callback)

getAgentLogs(agentInfo, callback)

getAgentList(callback)

agentHeartbeat(agent, callback) ⇒

waitForAgentStartup(agent, callback) ⇒

Repository API (accessed via khClient.khRepository)

Functions

loadRepoFromName(repoName, callback)

addRepo(newRepo)

updateRepo(serverURL, existingRepo, callback)

deleteRepo(repo, callback)

loadRepo(repo, subDir, callback)

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

deleteFile(filePath, force, callback)

saveFile(filePath, fileContent, callback)

loadURL(URL)

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

importFileRepositoryFromTarBall(repo, tarBallFile, callback)

importFileRepositoryFromServer(repoToCreate, KHHostRepoName, KHServerURL, callback)

downloadRepoAsTarBall(repo, savePath)

KHRepository(serverURL, EventHandler)

loadFile : function

Job API (accessed via khClient.khJob)

Functions

executeJobSync(agentInfo, job)

cancelJob(agent, job, callback)

getRunningJobsList(agent, callback)

KHJob(serverURL, EventHandler)

Workflow API (accessed via khClient.khWorkflow)

Functions

connectEnvironmentAgents(environment)

executeWorkflow(environment, workflow, callback)

executeWorkflowSync(environment, workflow)

cancelWorkflow(environment, workflow, callback)

getRunningWorkflowsList(callback)

KHWorkflow(serverURL, khEventHandler, the, khClient)

Event API (accessed via khClient.khEventHandler)

commits since last release

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

loadFile : `function`

Weekly Downloads