valence-connect v1.1.4

CNX Corporation

Available for Valence ^5.2

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
}

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

Functions

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

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.

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

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

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.

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

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.

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

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

Example

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

getSessionStorage(key) ⇒ Promise.<*>

get session storage

Kind: global function

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

set the session storage

Kind: global function

Back To Top

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