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 plugin
• SDK for building custom flow-node plugins for API Builder flows

Install

npm install -g axway-flow-sdk

Generating a new flow-node plugin

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

axway-flow -n mynode
cd api-builder-plugin-fn-mynode
npm install --no-optional
npm run build (optional)

encodeURI example

const sdk = require('axway-flow-sdk');

function getFlowNodes() {
	const flownodes = 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));
		});
	return Promise.resolve(flownodes);
}

exports = module.exports = getFlowNodes;

Notice that this encodeURI example is returning a function, getFlowNodes, that returns a promise. This allows for the generation of the flow-node to be asynchronous, for example, to allow the loading of content from a remote source. In this example it is used for demostration purposes only, flownodes could have been returned from getFlowNodes instead.

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(flownodes) : function

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

Access: public

Param	Type	Description
flownodes	NodeBuilder	The NodeBuilder object.

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

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

Note if the flow-node is asynchronous, i.e. returns a promise, the promise must be resolved to get the flow-nodes defined in the plugin. This can simply be done using a before block that waits for the resolved promise.

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

let flownodes;
before(() => {
	return flownodesPromise.then((resolvedFlownodes) => {
		flownodes = resolvedFlownodes;
	});
});

it('describes a test', () => {
	const args = { foo: undefined };
	return mocknode(flownodes).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 flownodes = require('../src');
const { mocknode } = require('axway-flow-sdk');

it('describes a test', () => {
	const args = { foo: undefined };
	return mocknode(flownodes).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, [options])
  • .add(key, [options]) ⇒ NodeBuilder
  • .method(key, [options]) ⇒ NodeBuilder
  • .group(name) ⇒ NodeBuilder
  • .parameter(name, schema, [required]) ⇒ NodeBuilder
  • .output(key, [options]) ⇒ NodeBuilder
  • .action(handler) ⇒ NodeBuilder

new NodeBuilder(srcModule, [options])

Param	Type	Default	Description
srcModule	object		a node module
[options]	object		The options for the builder.
[options.validate]	object	true	The enables parameter validation. Disable if you need to use refs.

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

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

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

The key parameter is used to uniquely identify the flownode 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 flownode.

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 flownode 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.
[options.name]	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' });

Example (Disable validation)

sdk.init(module, { validation: false }).add('encodeURI', { icon: 'encode.svg' })
	.method('encode', { $ref: '#/definitions/foo' });

nodeBuilder.group(name) ⇒ NodeBuilder

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

Param	Type	Description
name	string	A unique name for the parameter group as it will appear in the UI.

Example

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

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, [options]) ⇒ 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	Default	Description
module	object		The node module.
[options]	object		The options for the builder.
[options.validate]	object	true	The enables parameter validation. Disable if you need to use refs.

Example

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

axway-flow-sdk~validate(nodes)

Validates the flownodes against the Axway Flow schema.

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

• Error If nodes contains invalid flownodes.

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);

Author

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

Changes

3.1.5

• #5708: Updated mocha configuration

3.1.4

• #5709: Internal changes to update eslint rules.

3.1.3

• #5707: Internal cleanup to code coverage during build process.

3.1.2

• #5742: Internal change to replace dot dependency with ejs when generating new flow-node plugins.

3.1.0

• #5600: Support schema references by disabling validation when building flow-nodes.

3.0.0

• #5436: Breaking Change: Minimum supported version of API Builder is now Jakarta
• #5436: Moves advanced HTTP options into a new group, "Advanced HTTP Options"

axway-flow-sdk@2.0.9

• #4757: Changed SCM repository and associated internal cleanup.

License

This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: https://support.axway.com/en/auth/general-conditions; EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.