# 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
```js
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](https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/api_builder.html),
it is possible to reference other types. For example, types can be loaded from `./schemas`, registered
from [Models](https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/models.html), or registered
from service connectors. Any registered schema can be referenced whenever a `schema` is required.
```js
.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.
```js
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.
```js
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
](#module_axway-flow-sdk)
* [~NodeBuilder](#module_axway-flow-sdk..NodeBuilder)
* [new NodeBuilder(srcModule, [options])](#new_module_axway-flow-sdk..NodeBuilder_new)
* [.add(key, [options])](#module_axway-flow-sdk..NodeBuilder+add) ⇒ NodeBuilder
* [.method(key, [options])](#module_axway-flow-sdk..NodeBuilder+method) ⇒ NodeBuilder
* [.group(name)](#module_axway-flow-sdk..NodeBuilder+group) ⇒ NodeBuilder
* [.parameter(name, schema, options)](#module_axway-flow-sdk..NodeBuilder+parameter) ⇒ NodeBuilder
* [.output(key, [options])](#module_axway-flow-sdk..NodeBuilder+output) ⇒ NodeBuilder
* [.action(handler)](#module_axway-flow-sdk..NodeBuilder+action) ⇒ 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])](#module_axway-flow-sdk..NodeBuilder+method)
- [.output(key, [options])](#module_axway-flow-sdk..NodeBuilder+output)
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](#module_axway-flow-sdk..NodeBuilder+method)
can be used to add method(s), and
[.output](#module_axway-flow-sdk..NodeBuilder+output) can be used to
define an output. When done,
[.action](#module_axway-flow-sdk..NodeBuilder+action) can be used to
define an action function and finish the flownode.
**Kind**: instance method of [NodeBuilder
](#module_axway-flow-sdk..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**
```js
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])](#module_axway-flow-sdk..NodeBuilder+parameter)
- [.action(handler)](#module_axway-flow-sdk..NodeBuilder+action)
[.add(key, [options])](#module_axway-flow-sdk..NodeBuilder+add) 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
](#module_axway-flow-sdk..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**
```js
sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
.method('encode', { name: 'Encode URI' });
```
**Example** *(Disable validation)*
```js
sdk.init(module, { validation: false }).add('encodeURI', { icon: 'encode.svg' })
.method('encode', { $ref: '#/definitions/foo' });
```
#### nodeBuilder.group(name) ⇒ NodeBuilder
**Kind**: instance method of [NodeBuilder
](#module_axway-flow-sdk..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**
```js
sdk.init(module).add('encodeURI', { icon: 'encode.svg' })
.method('encode', { name: 'Encode URI' })
.group('Advanced')
.parameter('uri', { type: 'string' });
```
#### nodeBuilder.parameter(name, schema, options) ⇒ NodeBuilder
Adds a new parameter to the current method. Any number of parameters can be added
to a method.
[.method(key, [options])](#module_axway-flow-sdk..NodeBuilder+method) must be
called prior to adding a parameter.
The `name` uniquely identifies the the parameter, and the `schema` is a valid
[JSON Schema](http://json-schema.org) definition (both
[draft-04](http://json-schema.org/draft-04/schema) and
[draft-06](http://json-schema.org/draft-06/schema) are supported).
**Kind**: instance method of [NodeBuilder
](#module_axway-flow-sdk..NodeBuilder)
**Returns**: NodeBuilder
- The current object (this).
**Access**: public
| Param | Type | 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. |
| options | object
\| boolean
| As an object, specifies additional options to configure the parameter. As a boolean, specifies that the parameter is required. Parameters are required by default. |
| options.required | boolean
| specifies that the parameter is required. Parameters are required by default. |
| options.multilineWrapper | object
| describes the before and after parts that surrounds user provided value in the UI. |
| options.multilineWrapper.before | string
| read-only string that is placed before the user provided value in the UI. |
| options.multilineWrapper.after | string
| read-only string that is placed after the user provided value in the UI. |
| options.initialType | string
| The type to display by default in the UI for this parameter. Allowed values are object, array, string, selector, null, boolean and number. |
**Example**
```js
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])](#module_axway-flow-sdk..NodeBuilder+method)
must be called prior to adding an output.
The `key` uniquely identifies the the output route. The `schema` is a valid
[JSON Schema](http://json-schema.org) definition (both
[draft-04](http://json-schema.org/draft-04/schema) and
[draft-06](http://json-schema.org/draft-06/schema) are supported).
If `schema` is not provided, then the output type is effectively _any_ type.
The `context` is a valid [JSON Path](https://github.com/json-path/JsonPath) 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
](#module_axway-flow-sdk..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**
```js
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`](module:axway-flow-sdk~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
](#module_axway-flow-sdk..NodeBuilder)
**Returns**: NodeBuilder
- The current object (this).
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| handler | handler
| The action [`handler`](module:axway-flow-sdk~handler) function. |
**Example**
```js
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
](#module_axway-flow-sdk)
**Returns**: NodeBuilder
- A newly constructed
[`NodeBuilder`](#module_axway-flow-sdk..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**
```js
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
](#module_axway-flow-sdk)
**Throws**:
- Error
If nodes contains invalid flownodes.
**Access**: public
| Param | Type | Description |
| --- | --- | --- |
| nodes | NodeBuilder
| nodes to validate |
**Example**
```js
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);
```
# Changes
#### 3.4.3
- #6315: Internal chore.
#### 3.4.2
- #6116: Internal cleanup chore.
#### 3.4.1
- #6074: Internal CI chore
#### 3.4.0
- #5924: Added support for string parameters having a format of "mustache".
#### 3.3.0
- #5892: Added support for defining a type for parameters to display by default in the Flow editor. Previously parameters always started with `selector`. Now they will consider the type provided using `initialType` as an option:
```js
.parameter('myToggle', {
type: 'boolean'
}, {
initialType: 'boolean'
})
```
#### 3.2.0
- #5891: Added alternative way to define parameter options. Instead of `false` as a third argument to `.parameter()`, an object can be provided as `{ required: false }`.
- #5891: Added support for defining wrapper text for multiline and javascript format parameters. This wrapper text will be displayed in the parameter editor but will not be part of the value when saved in the flow.
This is useful for when context or comments are needed.
#### 3.1.11
- #5923: Fix issue where README.md was not published.
- #5923: Fix issue where README.md was generated with hardcoded docs.
#### 3.1.10
- #5914: Internal change to re-introduce readme generation from JSDoc.
#### 3.1.9
- #5887: Fix issue where the `axway-flow -n` command would throw an error
#### 3.1.8
- #5895: Fix issue where new Flow-Node projects would not get generated with a `test` directory.
#### 3.1.7
- #5711: Internal cleanup of npm scripts.
#### 3.1.6
- #5708: Internal changes removing readme autogeneration.
#### 3.1.5
- #5708: Internal changes to 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"
#### 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](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.