@nchannel/endpoint-sdk v1.0.16

nChannel Endpoint SDK

An SDK for developing software to integrate the nChannel platform with third-party endpoint systems.

Contents

• Quick Start Guide
• Overview
• Channel Development
• Testing
• Certification

Quick Start Guide

Setup a project directory

$ mkdir myProject
$ cd myProject
$ git init
$ npm init

Install the SDK

$ npm install @nchannel/endpoint-sdk

Initialize the SDK project

$ npx nchannel-sdk init

Happy Coding!

Overview

The nChannel Endpoint SDK exposes an API which allows third-party systems to interact with the nChannel system. The software which bridges the gap between the nChannel system and the endpoint system is referred to as a Channel.

The nChannel system operates on a set of GET, PUT and REFRESH actions -- one for each entity in the system. Channels may support one or more of these actions and can further define their support through a set of capabilities. Each action is associated with a set of functions which are responsible for interacting with the endpoint system and returning a result to the nChannel system.

By identifying the capabilities which your system supports, you'll be able to determine which actions your Channel will support and which functions will need to be implemented.

Channel Development

Channels are developed as a node module, published on behalf of nChannel, and installed in the nChannel system via the standard node module installation process. Modules may define their own dependencies and may be structured according to the preferences of the development team. The only restrictions are:

1. The module must export a class which implements one of the SDK interfaces.
2. The module must have a config directory at the root level containing the following files:

• channel-settings.json
• docs.json

See the npm documentation for more information regarding building a node module.

channel-settings.json

This file contains your ChannelRegistry definition. The ChannelRegistry object describes all aspects of a Channel -- authentication, configurable properties, supported actions, and capabilities. See the ChannelRegistry type definition in the SDK documentation for detailed information.

docs.json

Configures the standard test suite. See the testing section for more details.

Implementing an Interface

You have a choice of implementing functions using one of two interfaces -- a Promise based interface or a Callback based interface. At the heart of it there are four basic types of functions: get, insert, update and extract. While the first three are self-explanatory, the extract function is responsible for extracting one entity out of another. For example, extracting a customer out of a salesOrder.

If you've completed the nchannel-sdk init utility, the generated class and function templates will give you a great head start at implementing your fist Channel. If you haven't however, you'll need to create a class which extends one of the SDK interfaces and override certain functions based on your Channel capabilities. Use of the Promise based interface is encouraged, however, in some instances the Callback based interface is more appropriate.

Schemas

Schemas define the format for documents that are passed into and returned from your functions. Each entity which you are creating a function for must have a schema. Schemas operate at an action level -- so you may define different schemas for GET and PUT actions or share the same schema. REFRESH actions will always use the same schema as the GET action.

When making changes to a certified channel, schemas are never allowed to contain any breaking changes. A schema definition may never become more restrictive, but may become more lax. If you require a more restrictive change to a schema, you'll have to certify a new Channel.

Testing

The nChannel Endpoint SDK provides a standard suite of tests to help validate that your Channel correctly implements one of the SDK interfaces.

Configuring the Tests

Standard test suite configuration is accomplished via the docs.json file. You'll configure one test for each of the happy-path status codes (2xx) supported by each of the functions you've implemented. Test configuration entails defining the inputs to your function and mocking the requests your function will make.

Required Parameters

unitTestPackage - Name of the testing package used with the stub functions. Valid values are nock and soap.

packageName - (Required if unitTestPackage is soap) Name of the soap package used with the stub functions. Package used should derive from the base repository Soap.

channelProfile - Passed into the stub function. Contains the channelAuthValues object with any authorization values that are used by the stub function.

doc - An array of objects used by the unit tests. Each of the objects should contain the following:

• functionName - Name of the stub function this object is for. (i.e. getCustomerById)
• tests - An array of documents used to test the stub function. At least one document must be present for each 2xx status code supported by the function. - Example: getCustomerById must have at least one document for each of the status codes 200 and 204.

Required Parameters for tests array

Each test object in the array must contain the following:

statusCode - The status code that the test will return.

payload - Payload used for the stub function in the unit tests. Can contain a doc object holding the document data to be sent to the endpoint system.

When unitTestingPackage is soap:

• wsdlUri - wsdl URI used with the endpoint system.
• security - (Optional) Security model used within the soap client (i.e. BasicAuthSecurity)
• service - (Optional) wsdl service name used for the unit test.
• servicePort - (Optional) wsdl port name used for the unit test.

When unitTestingPackage is nock:

• baseUri - Base URI of the endpoint system
• baseUriType - (Optional) specify 'regexp' to indicate baseUri is a regular expression
• defaultHeaders - Default headers used with baseUri to be passed with the document

links - An array of objects containing each of the calls to the endpoint system. Each link should contain the following:

• When unitTestingPackage is soap: - function - Function that is invoked when communicating with the endpoint system.

• When unitTestingPackage is nock: - uri - Endpoint of the API. - method - HTTP Method used. Valid values are GET, POST, PUT, and DELETE. - replyHeaders - Reply headers used with the response of the request. - statusCode - Status code to be returned from the API

• All testing packages: - responsePayload - Expected payload returned from the endpoint system

channelProfile - Object that will contain parameters to be used by the stub function. (i.e. channelSettingsValues.endpointUri)

Executing the Test Suite

Run the following command:

$ npx nchannel-sdk test

Certification

When you're ready to have your Channel certified for use in production, submit a pull request to nChannel. Your Channel will be reviewed and then merged once the certification process is complete.

For more information visit help.nchannel.com.