axway-flow-sdk

axway-flow-sdk

SDK for implementing custom flow nodes for API Builder flows

Features

• CLI tool for starting a new flow-node project
• SDK for building custom modules for API Builder flows

Install

npm install -g axway-flow-sdk

Generating a new flow-node project

Generates a new flow-node project named "mynode" in the current directory.

axway-flow -n mynode
cd mynode
npm install
npm run build

encodeURI example

const sdk = require('axway-flow-sdk');
exports = module.exports = sdk.init(module)
	.add('encodeURI', {
		name: 'Encode URI',
		icon: 'encode.svg',
		description: 'URI encoder'
	})
	.method('encode', {
		name: 'Encode URI',
		description: 'Encodes a URI by replacing each instance of certain characters with UTF-8 encodings.'
	})
	.parameter('uri', {
		type: 'string',
		description: 'The URI to encode.'
	})
	.output('encoded', {
		name: 'Encoded',
		description: 'The encoded URI.',
		context: '$.encodedURI',
		schema: {
			type: 'string'
		}
	})
	.action((req, cb) => {
		cb.encoded(null, encodeURI(req.params.uri));
	});

Type references

In Axway API Builder, it is possible to reference other types. For example, types can be loaded from ./schemas, registered from models, or registered from service connectors. Any registered schema can be referenced whenever a schema is required.

.parameter('greeting', {
	"$ref": "schema://model/appc.arrowdb/user"
})
.output('next', {
	schema: {
		"$ref": "schema://model/appc.arrowdb/user"
	}
})

Testing your flow-node module

The cli will automatically generate a unit test in ./test/test.js. The test will use mocknode to mock an API Builder flow-node.

mocknode(specs) : function

Mocks an API Builder flow-node using the spec generated with NodeBuilder.

Access: public

Param	Type	Description
specs	NodeBuilder	The NodeBuilder object.

Testing a successful output callback: cb.next(null, 'stuff')

This example uses mocha and promises to check that the spec is defined well enough to pass the argument foo to the method method. It also mocks the callback using the spec's defined output, and ensures that the method invokes the correct callback.

const specs = require('../src');
const { mocknode } = require('axway-flow-sdk');

it('describes a test', () => {
	const args = { foo: undefined };
	return mocknode(specs).node('example').invoke('method', args)
		.then((response) => {
			expect(response).to.deep.equal({
				next: [null, 'stuff']
			})
		});
})

Testing an error default callback: cb('invalid argument')

This example is similar to the previous example, save that the expectation is that the method will invoke cb('invalid argument') when given an undefined parameter.

const specs = require('../src');
const { mocknode } = require('axway-flow-sdk');

it('describes a test', () => {
	const args = { foo: undefined };
	return mocknode(specs).node('example').invoke('method', args)
		.then((response) => {
			expect(response).to.deep.equal(['invalid argument'])
		});
})

API Reference

axway-flow-sdk~NodeBuilder

Kind: inner class of axway-flow-sdk

• ~NodeBuilder
  • new NodeBuilder(srcModule)
  • .add(key, [options]) ⇒ NodeBuilder
  • .method(key, [options]) ⇒ NodeBuilder
  • .parameter(name, schema, [required]) ⇒ NodeBuilder
  • .output(key, options) ⇒ NodeBuilder
  • .action(handler) ⇒ NodeBuilder

new NodeBuilder(srcModule)

Param	Type	Description
srcModule	object	a node module

nodeBuilder.add(key, [options]) ⇒ NodeBuilder

Adds a new node spec and prepares the NodeBuilder to accept the following spec operations:

• .method(key, [options])
• .output(key, [options])

The key parameter is used to uniquely identify the spec and represents a distinct instance of a node for the flow editor. The key will be used as the name unless the name option is provided. The new node will appear under the "general" category by default, or under the provided category option.

The icon option can be bmp, jpeg, png, gif, tiff, or svg file. After, .method can be used to add method(s), and .output can be used to define an output. When done, .action can be used to define an action function and finish the spec.

Kind: instance method of NodeBuilder
Returns: NodeBuilder - The current object (this).
Access: public

Param	Type	Default	Description
key	string		A unique key identifier for the node.
[options]	object		Options for the node.
[options.name]	string		A friendly name for the node as it will appear in the UI.
[options.icon]	string		An icon file.
[options.description]	string		A description for the node.
[options.category]	string	"general"	A category under which the node will appear in the UI (defaults to "general").

Example

sdk.init(module).add('encodeURI', { icon: 'encode.svg' });

nodeBuilder.method(key, [options]) ⇒ NodeBuilder

Adds a new method to the current node spec and prepares the NodeBuilder to accept the following method operations:

• .parameter(name, schema, [required])
• .action(handler)

.add(key, [options]) must be called prior to adding a method.

The key uniquely identifies the method for the node and will be used as the name unless the name option is provided.

Kind: instance method of NodeBuilder
Returns: NodeBuilder - The current object (this).
Access: public

Param	Type	Description
key	string	A unique key identifier for the method.
[options]	object	Options for the method.
[]	string	A friendly name for the method as it will appear in the UI.
[options.description]	string	A description for the method.

Example

sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { name: 'Encode URI' });

nodeBuilder.parameter(name, schema, [required]) ⇒ NodeBuilder

Adds a new parameter to the current method. Any number of parameters can be added to a method.

.method(key, [options]) must be called prior to adding a parameter.

The name uniquely identifies the the parameter, and the schema is a valid JSON Schema definition (both draft-04 and draft-06 are supported).

Kind: instance method of NodeBuilder
Returns: NodeBuilder - The current object (this).
Access: public

Param	Type	Default	Description
name	string		A unique name for the parameter as it will appear in the UI.
schema	object		A schema used to validate the parameter.
[required]	boolean	true	A flag to indicate the parameter is required or optional.

Example

sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' });

nodeBuilder.output(key, options) ⇒ NodeBuilder

Adds a new output to the current method. Any number of outputs can be added to a method, but for usability-sake, you should limit this. The output represents one of the possible callback routes for your method. For example, if your method tested prime numbers, then one output might be prime, and the other not-prime.

.method(key, [options]) must be called prior to adding an output.

The key uniquely identifies the the output route. The schema is a valid JSON Schema definition (both draft-04 and draft-06 are supported). If schema is not provided, then the output type is effectively any type.

The context is a valid JSON Path and is used as the default by the flow editor. When the output is invoked, the configured context is where the output value will be written.

Kind: instance method of NodeBuilder
Returns: NodeBuilder - The current object (this).
Access: public

Param	Type	Description
key	string	A unique key for the output.
options	object	output options
[options.name]	string	A friendly name for the output as it will appear in the UI.
[options.description]	string	The output description.
[options.context]	string	The default context string.
[options.schema]	object	The expected JSON schema for the output value.

Example

sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' })
	.output('encoded', { context: '$.encodedURI', schema: { type: 'string' } });

nodeBuilder.action(handler) ⇒ NodeBuilder

Assigns an action handler to the current method. The method can only have one action handler. Assigning an action will terminate the current method definition.

Kind: instance method of NodeBuilder
Returns: NodeBuilder - The current object (this).
Access: public

Param	Type	Description
handler	handler	The action handler function.

Example

sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' })
	.output('encoded', { context: '$.encodedURI', schema: { type: 'string' } })
	.action((req, cb) => cb.encoded(null, encodeURI(req.params.uri));

axway-flow-sdk~init(module) ⇒ NodeBuilder

Axway API Builder SDK for creating custom nodes to work with flows.

Kind: inner method of axway-flow-sdk
Returns: NodeBuilder - A newly constructed NodeBuilder object

Param	Type	Description
module	object	The node module.

Example

const sdk = require('axway-flow-sdk');
exports = module.exports = sdk.init(module);

axway-flow-sdk~validate(nodes)

Validates the flow-node specs against the Axway Flow schema.

Kind: inner method of axway-flow-sdk
Throws:

• Error If nodes contains invalid specs.

Access: public

Param	Type	Description
nodes	NodeBuilder	nodes to validate

Example

const nodes = sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { name: 'Encode URI' })
	.parameter('uri', { type: 'string' })
	.output('encoded', { context: '$.encodedURI', schema: { type: 'string' } })
	.action((req, cb) => cb.encoded(null, encodeURI(req.params.uri));
sdk.validate(nodes);

axway-flow-sdk~handler : function

A handler function to perform the node method's action. The function will receive all of the provided parameters in req.params. If any parameters are not provided, or are of the wrong time, or some have defaults, your function will need to handle those situations. On success, your function should invoke one of the named output. On error, your function should invoke the callback with a non-null err value.

Kind: inner typedef of axway-flow-sdk
Access: public

Param	Type	Description
req	Request	The Request object.
cb	flowCallback	The output callback.

Example

cb.encoded(null, uncodeURI(req.params.uri));

Example

cb('error!');

axway-flow-sdk~flowCallback : function

A callback function that your method handler must invoke.

Kind: inner typedef of axway-flow-sdk
Access: public

Param	Type	Description
[err]	*	A non null value indicates a terminal error (flow processing will stop).
[value]	*	The output value to be written back to the flow processing context.

axway-flow-sdk~Request : object

The request object.

Kind: inner typedef of axway-flow-sdk
Properties

Name	Type	Description
env	object	The application configuration.
params	object	The method params, as supplied during runtime (see .parameter).

Author

Axway [e-mail] https://axway.com

License

This code is closed source and Confidential and Proprietary to Axway, Inc. All Rights Reserved. This code MUST not be modified, copied or otherwise redistributed without express written permission of Axway. This file is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement. Your right to use this software terminates when you terminate your Axway subscription.