valence-connect

CNX Corporation

Use the valence-connect package when developing your Valence apps in Node.js. With valence-connect, your Node.js apps can participate in Valence role-based security, session management, logging and more. Writing Node.js apps for Valence using valence-connect also allows for maximum portability -- you can move your code between IBM i, Linux and Windows servers with little or no changes.

Documentation Examples Tests Versions

Clean Install

mkdir acme
cd acme
npm init --yes
npm install valence-connect --save

After completing a clean installation start the new node server. You can find more information on starting the server below.

Starting the Node Server

Development

npm start

Debug

$ DEBUG=acme:* npm start

On Windows

> set DEBUG=acme:* & npm start

On Windows: PowerShell

PS > $env:DEBUG="acme:*" ; npm start

Production

When running in production mode the server will be clustered and compress files to improve performance.

npm run start:production

On Windows: PowerShell

PS > npm run start:production_ps

Clustering

By default the server will be clustered when running in production mode and create workers based on the available CPU's. You can override the number of workers produced by setting the WEB_CONCURRENCY environment variable. Set WEB_CONCURRENCY to "0" if you don't want clustering turned on.

$ WEB_CONCURRENCY=3 npm run start:production

On Windows

> set WEB_CONCURRENCY=3 & npm run start:production

On Windows: PowerShell

PS > $env:WEB_CONCURRENCY="3" ; npm run start:production_ps

Examples

After performing a clean install and answering yes to "Automatically create application skeleton?" You will have one example application that displays a list of customers from our example table DEMOCMAST. Be sure the new server is running before attempting to launch the example application.

Try the example by creating a new Valence app in Portal Admin with an application type of "Valence Application". The Path will be the full URL consisting of this server and the route to the example.

http://YOUR_SERVER:PORT/apps/customers/index.html

Example :

http://acme.com:7152/apps/customers/index.html

Structure after a clean install

acme
│
└───bin
│       www.js
│
└───node_modules
│       valence-connect
│       *other modules
│
└───public
│   │
│   └───apps
│   │   │
│   │   └───customers "example"
│   │
│   └───images
│   │       valence_logo.png
│   │
│   └───stylesheets
│           style.css
│
└───routes
│   │   index.js
│   │   valence.js
│   │
│   └───api
│           customers.js "example"
│
└───services
│       Readme.md
│       customers.js "example"
│
└───tests
│       Readme.md
│       services.js "example"
│
└───views
│       error.pug
│       index.pug
│       layout.pug
│
│   .gitignore
│   app.js
│   package.json
│   Readme.md
│   valence.json

valence.json

{
  "url": "http://acme.com:7052/service/connect?key=CD5678F68804D0123112TA0B8C93D1E58",
  "IBMi": true,
  "logging": false
}

Property	Type	Description
url	`string`	Valence Connect Web Service URL "Located in Valence Portal Admin/Web Services"
IBMi	`boolean`	Running Valence for IBM i. Pass false if connecting to Valence Universal on Windows, Linux or OS X. Defaults to true if not passed.
logging	`boolean`	When `true` will capture statistical information which can be viewed in Portal Admin-->Logs.

Valence Connect init

routes/valence.js

/**
 * Valence Router
 */
const express        = require('express'),
      cors           = require('cors'),
      corsWhiteList  = ['http://acme.com:7052'],
      corsOptions    = {
          origin : (origin, callback) => {
              if (typeof origin === 'undefined'
                  || corsWhiteList.indexOf(origin) !== -1) {
                  callback(null, true);
              } else {
                  callback(new Error('Not allowed by CORS'));
              }
          }
      },
      router         = express.Router(),
      valenceConnect = require('valence-connect'),
      customers      = require(global.__services + 'customers/customers');

// Initialize Valence Connect
//
valenceConnect.init();

// Allow Cross Origin
//
router.all('*', cors(corsOptions));

/**
 * Check if the request session is authenticated
 * @param {IncomingMessage} req http request
 * @param {ServerResponse} res http response
 * @param {callback} next continue
*/
let valenceCheck = (req, res, next) => {
    valenceConnect.isAuthenticated(req, res)
        .then(() => {
            next();
        });
};

// Always check before proceeding that the session is valid for all Valence requests
//
router.use(valenceCheck);

// Routes
//

// Example Valence Route "query customers"
//
router.all('/customers/queryAll', customers.queryAll.bind(customers));

module.exports = router;

Tests

After performing a clean install and answering yes to "Automatically create application skeleton?" you will have an example test for the customer service using node-tap.

To run the example services test issue the below command passing a valid session id. You can get a valid session id by logging into the Valence Portal and launching developer tools. Once developer tools is launched go to the console and run Valence.util.Helper.getSid(). That will return your current session id.

$ session=CURRENTSESSIONID npm test

On Windows

> set session=CURRENTSESSIONID & npm test

On Windows: PowerShell

PS > $env:session="CURRENTSESSIONID" ; npm test

Classes

ValenceConnect: Documentation: Security, session management, logging and utilities

Functions

getSessionStorage(key) ⇒ Promise.<*>: get session storage
setSessionStorage(key, info) ⇒ Promise.<void>: set the session storage

ValenceConnect

Documentation: Security, session management, logging and utilities

Kind: global class

ValenceConnect
- new ValenceConnect()
- .baseInit() ⇒ Promise.<void>
- .init([options]) ⇒ InitPromise
- .dbQuery(req, [res], statement) ⇒ DbQueryPromise
- .decodeUTF16(inStr) ⇒ string
- .getParams(req, [param]) ⇒ Object | string | number | date | array | boolean | *
- .getSessionInformation(sid) ⇒ SessionInformationPromise
- .getSettings(sid, [names], [cacheBuster]) ⇒ SettingsPromise
- .getUserInformation(sid, [cacheBuster]) ⇒ UserInformationPromise
- .isAuthenticated(req, res) ⇒ IsAuthenticatedPromise
- .isEmpty(value) ⇒ boolean

new ValenceConnect()

Constructor

Example

const valenceConnect = require('valence-connect');

valenceConnect.baseInit() ⇒ `Promise.<void>`

init session storage

Kind: instance method of ValenceConnect

valenceConnect.init([options]) ⇒ `InitPromise`

Initialize valence connect for communication with Valence for IBM i or Valence Universal. By default, valenceConnect.init will look for a valence.json configuration file at the root of the project for the required properties. You may override those properties by passing in an options object.

Kind: instance method of ValenceConnect

Param	Type	Description
[options]	`object`	Configuration Options
options.url	`string`	Valence Connect Web Service URL "Located in Valence Portal Admin/Web Services"
options.IBMi	`boolean`	Running Valence for IBM i. Pass false if connecting to Valence Universal on Windows, Linux or OS X. Defaults to true if not passed.
options.logging	`boolean`	When `true` will capture statistical information which can be viewed in Portal Admin-->Logs.

Example

// Using valence.json
//
valenceConnect.init();

Example

// Passing options
//
valenceConnect.init({
    url     : 'http://acme.com:7052/service/connect?key=AZE678F68804D0123112TD0B8D93C1E38',
    IBMi    : true,
    logging : false,
});

valenceConnect.dbQuery(req, [res], statement) ⇒ `DbQueryPromise`

Run an SQL SELECT statement and get the results.

Kind: instance method of ValenceConnect
Returns: DbQueryPromise - when fulfilled will contain an object with the results.

Param	Type	Description
req	`IncomingMessage` \| `object`	http request or object containing parameters to send off to process the query. Parameters: `rootName`, `maxResults`, `startFrom`.
[res]	`ServerResponse`	http response
statement	`string`	SQL statement to run. Only SELECT statements are allowed

Example

router.all('/customers', (req, res) => {
    let statement     = 'select cusno as NUMBER, cname as NAME,' +
        ' ccity as CITY, cstate as STATE from DEMOCMAST',
        queryResponse = (response) => {
            res.json(response);
        },
        queryError    = (err) => {
            res.json(err);
        };

    valenceConnect.dbQuery(req, res, statement)
        .then(queryResponse)
        .catch(queryError);
});

valenceConnect.decodeUTF16(inStr) ⇒ `string`

Decode UTF16 hex-encoded strings

Kind: instance method of ValenceConnect
Returns: string - decoded string

Param	Type	Description
inStr	`string`	string to decode

Example

let decodedValue = valenceConnect.decodeUTF16(encodedValue);

valenceConnect.getParams(req, [param]) ⇒ `Object` | `string` | `number` | `date` | `array` | `boolean` | `*`

Get a single request parameter or all request parameters from both the body and query string.

Kind: instance method of ValenceConnect

Param	Type	Description
req	`IncomingMessage`	http request
[param]	`string`	parameter id

Example

// All Parameters
// The variable params would be an object containing all the query string
//   and body parameters combined.
//
router.all('/processInventory', (req, res) => {
    let params = valenceConnect.getParams(req);

    if (params.inventoryId) {
      // process inventory
      //
    }
});

Example

// Single Parameter
// The inventoryId variable would be a number since the front-end passed a numeric
//   value.
//
router.all('/processInventory', (req, res) => {
    let inventoryId = valenceConnect.getParams(req, 'inventoryId');

    if (inventoryId) {
      // process inventory
      //
    }
});

valenceConnect.getSessionInformation(sid) ⇒ `SessionInformationPromise`

Get the session information from the passed in session id

Kind: instance method of ValenceConnect
Returns: SessionInformationPromise - when fulfilled will contain the session information. Environment Id, Mode, Session Variables, etc.

Param	Type	Description
sid	`string`	session id

Example

router.all('/transferOrder', (req, res) => {
    let sessionId       = valenceConnect.getParams(req, 'sid'),
        sessionError    = (err) => {
            res.json(err);
        },
        sessionResponse = (info) => {
            if (info.envId === 1) {
                // process default
                //
            } else {
                //process other environment
                //
            }
        };

    valenceConnect.getSessionInformation(sessionId)
        .then(sessionResponse)
        .catch(sessionError);
});

valenceConnect.getSettings(sid, [names], [cacheBuster]) ⇒ `SettingsPromise`

Get Valence Settings

Kind: instance method of ValenceConnect
Returns: SettingsPromise - when fulfilled will be a name/value array of Valence settings

Param	Type	Description
sid	`string`	session id
[names]	`array`	optional array of setting names to get
[cacheBuster]	`boolean`	If `true` force pull of latest settings from Valence.

Example

router.all('/settings', (req, res) => {
    let sessionId        = valenceConnect.getParams(req, 'sid'),
        settingsError    = (err) => {
            res.json(err);
        },
        settingsResponse = (settings) => {
            res.json({
                settings : settings
            });
        };

    valenceConnect.getSettings(sessionId)
        .then(settingsResponse)
        .catch(settingsError);
});

valenceConnect.getUserInformation(sid, [cacheBuster]) ⇒ `UserInformationPromise`

Get the current user information from the passed in session id

Kind: instance method of ValenceConnect
Returns: UserInformationPromise - when fulfilled will contain the user information. Id, First, Last Name, Email, etc.

Param	Type	Description
sid	`string`	session id
[cacheBuster]	`boolean`	If `true` force pull of latest users information from Valence.

Example

router.all('/userInformation', (req, res) => {
    let sessionId    = valenceConnect.getParams(req, 'sid'),
        userError    = (err) => {
            res.json(err);
        },
        userResponse = (info) => {
            res.json({
                user : info
            });
        };

    valenceConnect.getUserInformation(sessionId)
        .then(userResponse)
        .catch(userError);
});

valenceConnect.isAuthenticated(req, res) ⇒ `IsAuthenticatedPromise`

Is the session authenticated based off the current session id on the request object.

Kind: instance method of ValenceConnect

Param	Type	Description
req	`IncomingMessage`	http request
res	`ServerResponse`	http response

Example

valenceConnect.isAuthenticated(req, res)
    .then(() => {
        // authenticated so continue...
        //
        next();
    });

valenceConnect.isEmpty(value) ⇒ `boolean`

Check to see if a value is empty

Kind: instance method of ValenceConnect

Param	Type	Description
value	`*` \| `string`	value to test if empty

Example

if (valenceConnect.isEmpty(value)) {
    //value is empty
    //
} else {
    //value is not empty
    //
}

getSessionStorage(key) ⇒ `Promise.<*>`

get session storage

Kind: global function

Param	Type
key	`string`

setSessionStorage(key, info) ⇒ `Promise.<void>`

set the session storage

Kind: global function

Param	Type
key	`string`
info	`string`

Community

Forums

Versions

Prior to 1.1.1

beta

1.1.1 - 2018-05-18

General Availability

1.1.2 - 2018-09-12

When calling getParams with a specific parameter value return null if not found instead of an empty object.

1.1.3 - 2018-12-27

Update the required package url-parse minimum version to 1.4.3.

1.1.4 - 2020-12-21

Update package dependencies to the latest ver
Update core to handle dependency changes

valence-connect

CNX Corporation

Clean Install

Starting the Node Server

Development

Debug

Production

Clustering

Examples

Structure after a clean install

valence.json

routes/valence.js

Tests

Classes

Functions

ValenceConnect

new ValenceConnect()

valenceConnect.baseInit() ⇒ Promise.<void>

valenceConnect.init([options]) ⇒ InitPromise

valenceConnect.dbQuery(req, [res], statement) ⇒ DbQueryPromise

valenceConnect.decodeUTF16(inStr) ⇒ string

valenceConnect.getParams(req, [param]) ⇒ Object | string | number | date | array | boolean | *

valenceConnect.getSessionInformation(sid) ⇒ SessionInformationPromise

valenceConnect.getSettings(sid, [names], [cacheBuster]) ⇒ SettingsPromise

valenceConnect.getUserInformation(sid, [cacheBuster]) ⇒ UserInformationPromise

valenceConnect.isAuthenticated(req, res) ⇒ IsAuthenticatedPromise

valenceConnect.isEmpty(value) ⇒ boolean

getSessionStorage(key) ⇒ Promise.<*>

setSessionStorage(key, info) ⇒ Promise.<void>

Community

Versions

Prior to 1.1.1

1.1.1 - 2018-05-18

1.1.2 - 2018-09-12

1.1.3 - 2018-12-27

1.1.4 - 2020-12-21

Dependencies (19)

Dev Dependencies (5)

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

valenceConnect.baseInit() ⇒ `Promise.<void>`

valenceConnect.init([options]) ⇒ `InitPromise`

valenceConnect.dbQuery(req, [res], statement) ⇒ `DbQueryPromise`

valenceConnect.decodeUTF16(inStr) ⇒ `string`

valenceConnect.getParams(req, [param]) ⇒ `Object` | `string` | `number` | `date` | `array` | `boolean` | `*`

valenceConnect.getSessionInformation(sid) ⇒ `SessionInformationPromise`

valenceConnect.getSettings(sid, [names], [cacheBuster]) ⇒ `SettingsPromise`

valenceConnect.getUserInformation(sid, [cacheBuster]) ⇒ `UserInformationPromise`

valenceConnect.isAuthenticated(req, res) ⇒ `IsAuthenticatedPromise`

valenceConnect.isEmpty(value) ⇒ `boolean`

getSessionStorage(key) ⇒ `Promise.<*>`

setSessionStorage(key, info) ⇒ `Promise.<void>`

Weekly Downloads