node-omnibus v1.0.5

node-omnibus

node-omnibus is a client library for accessing the OMNIbus Objectserver database, from Node.js. It uses the Objectserver REST API and supports IBM Tivoli Netcool OMNIbus version 7.4 and above.

'IBM Tivoli Netcool OMNIbus provides near real-time service assurance for business infrastructure, applications, servers, network devices and protocols, internet protocols, storage and security devices' (from ibm.com)

• Installation
• OMNIbus REST configuration
• Usage
  • Creating the connection
  • Quick start
  • The response object
  • The error object
  • Querying the Objectserver (SELECT)
  • Deleting records (DELETE)
  • Updating records (UPDATE)
  • Inserting records (INSERT)
  • Working with the model
  • Working with the connection
• Javascript syntax
• Common Errors
• Contributing
• Changelog
• License
• Feedback
• Trademark information

Installation

npm install node-omnibus --save

OMNIbus REST configuration

Open the property-file for the Objectserver that should provide the REST interface

vi $OMNIHOME/etc/NCOMS.props

where NCOMS is the name of the Objectserver. Set the following parameters and restart the Objectserver

NRestOS.Enable: TRUE
NHttpd.EnableHTTP: TRUE
NHttpd.ListeningPort: 8080

Usage

Creating the connection

const omnibus = require('node-omnibus');

// set connection parameters
const connectionParameters = {
  host: 'omnihost', // Required - Objectserver to connect to
  port: '8080', // Required - NHttpd.ListeningPort
  user: 'root', // Required - Objectserver username
  password: 'password', // Required - Objectserver password
  SSLEnable: true, // Requests over https (default: false)
  SSLRejectUnauthorized: false, // Reject request if certificate is invalid (default: true)
};

// create the connection
const omnibusConnection = omnibus.createConnection(connectionParameters);

Quick start

Simple SQL request to the objectserver

omnibusConnection
  .sqlFactory('select * from alerts.status')
  .then(res => {
    // print the result from the query
    console.log(res);
  })
  .catch(err => {
    // console log any errors
    console.log(err);
  });

The response object

A successful request returns a response object in the following JSON structure:

{
  "rowset": {
    "osname": "NCOMS",
    "affectedrows": 10,
    "coldesc": [
      {
        "name": "Identifier",
        "type": "string",
        "size": 255
      },
      { ...more }
    ],
    "rows": [
      {
        "Identifier": "Switch01LinkDownPort1",
        "Serial": 12345,
        "Node": "Switch01",
        ...more
      },
      { ...more }
    ]
  }
}

Example loop on the response object

omnibusConnection.sqlFactory('select * from alerts.status').then(res => {
  // loop and console log Node and Summary
  res.rowset.rows.forEach((event, index) => {
    const { Node, Summary } = event;
    console.log('Node: ' + Node + ', Summary: ' + Summary);
  });
});

// Result:
// Node: Switch01, Summary: Port 01 Down
// ...

The error object

If the query was unsuccessful the promise will reject with a error object in the following JSON structure

{
  url: 'http://omnihost:8080/objectserver/restapi/sql/factory',
  status: 401,
  statusText: 'Authorization Required',
  explanation: 'Check username and password'
}

The example above is from an authentication failure. Code to replicate authentication error:

// Set the attribute 'password' to incorrect password
omnibusConnection.setAttributes({ password: 'wrongpassword' });

// Try the query
omnibusConnection
  .sqlFactory('select * from alerts.status')
  .then(res => {
    // Promise not resolved due to error
    console.log(res);
  })
  .catch(err => {
    // Catch promise error (reject)
    console.log(err);
  });

Querying the ObjectServer (SELECT)

.find(OmnibusQueryParams)

Performs a GET requst to the objectserver with optional query parameters.

omnibusConnection
  .find({
    filter: { Node: 'switch01' },
    collist: ['Node', 'Severity', 'Summary'],
    orderby: { Node: 'ASC' },
  })
  .then(res => console.log(res));

// Equals: select Node, Severity, Summary from alerts.status where Node='switch01' ORDER BY Node ASC

If no query parameters is sent with the request, the whole dataset will be returned.

omnibusConnection.find().then(res => console.log(res)); //equals select * from alerts.status

You can only use one filter expression. AND or OR is not supported. To use more complex queries, see .sqlFactory

.sqlFactory(sqlQuery)

Performs a get request to the objectserver with an arbitrary SQL command.

// create the query
const myQuery =
  "select Node, Severity, Summary from alerts.status where Node='switch01' ORDER BY Node ASC";

// send to objectserver and print result
omnibusConnection
  .sqlFactory(myQuery)
  .then(res => {
    console.log(res);
  })
});

Note: You do not need to set a query path for .sqlFactory method.

Deleting records (DELETE)

.destroy(OmnibusQueryParams)

Performs a DELETE request to the objectserver with required filter query params. The filter parameter is required to prevent accidental deletion of the entire table.

omnibusConnection
  .destroy({
    filter: { Node: 'switch01' },
  })
  .then(res => console.log(res));

// Equals: delete from alerts.status where Node='switch01'

To delete everything, just provide an empty filter.

// WARNING: THIS WILL DELETE EVERYTHING FROM THE TABLE
omnibusConnection
  .destroy({
    filter: {},
  })
  .then(res => console.log(res));

// Equals: delete from alerts.status

You can only use one filter expression. AND or OR is not supported. To use more complex queries, see .sqlFactory

Updating records (UPDATE)

.update(OmnibusQueryParams)

Performs a PATCH (UPDATE) request to the objectserver with required filter and uddate query parameters. The filter parameter is required to prevent accidental update of the entire table.

omnibusConnection
  .update({
    filter: { Node: 'omnihost' },
    update: { Node: 'new_omnihost' },
  })
  .then(res => console.log(res));

// Equals: update alerts.status (Node) values ('new_omnihost') where Node='omnihost'

To update every record, just provide an empty filter.

omnibusConnection
  .update({
    filter: {},
    update: { Node: 'new_omnihost' },
  })
  .then(res => console.log(res));

You can only use one filter expression. AND or OR is not supported. To use more complex queries, see .sqlFactory

Inserting records (INSERT)

.insert(Fields)

Preforms a POST (INSERT) request to the objectserver with required fields query parameter.

omnibusConnection
  .insert({
    Identifier: 'insertNewRowFromNode',
    Node: 'mynode',
    Summary: 'Insert from Node',
    Severity: 5,
  })
  .then(res => console.log(res));

Working with the model

When creating a connection, a data-model is always fetched from the objectserver. This model is used to create update and insert queries. The model contains all the fields and types in the objectserver.

// alerts.status model
{
  "Identifier": "string",
  "Serial": "integer",
  "Node": "string",
  "NodeAlias": "string",
  "Manager": "string",
  "Agent": "string",
  "AlertGroup": "string",
  ...mode fields
}

.syncModel()

If you during your program execution update the model in the objectserver, the local model must be synced.

// Sync model if changed during program execution
omnibusConnection.syncModel();

.getModel()

If you need to check the model you can fetch the local copy of the model.

omnibusConnection.getModel().then(model => {
  console.log(model);
});

Working with the connection

.setAttributes(Parameters)

If you during your program execution need to update any connection parameters.

// update the host parameter for the objectserver
omnibusConnection.setAttributes({ host: 'new_omnihost' });

// update the host and port parameter for the objectserver
omnibusConnection.setAttributes({ host: 'new_omnihost', port: '8081' });

Parameters user, password, host and port are required and cannot be empty

.getAttributes()

Returns the current set attributes for the connection.

// fetch the connection attributes
const myAttributes = omnibusConnection.getAttributes();

.setQueryPath(Endpoint)

The default query path (database/table) is set to alerts.status but can easily be changed by the setQueryPath method on the connection object.

// change querypath to alerts.details
omnibusConnection.setQueryPath('alerts.details');

You can also prepare many different connections with different query path when you create the connection.

const statusDb = omnibus.createConnection(connectionParameters).setQueryPath('alerts.status');
const detailsDb = omnibus.createConnection(connectionParameters).setQueryPath('alerts.details');
const journalDb = omnibus.createConnection(connectionParameters).setQueryPath('alerts.journal');

// print all events
statusDb.find().then(res => console.log(res));
// print all details
detailsDb.find().then(res => console.log(res));
// print all journals
journalDb.find().then(res => console.log(res));

.getUrl()

Returns the last used URL to communicate with the Objectserver

const myURL = omnibusConnection.getUrl();

Javascript Syntax

Arrow Functions

This manual uses the new ES6 Arrow functions but if you prefer to use the old style, use the example below

omnibusConnection
  .find()
  .then(res => console.log(res))
  .catch(err => console.log(err));

omnibusConnection
  .find()
  .then(function(res) {
    console.log(res);
  })
  .catch(function(err) {
    console.log(err);
  });

Async / Await

Allthough this manual use .then().catch() for some operations feel free to use async/await where appropriate.

// using .then()
function getAlertsStatus() {
  omnibusConnection.find().then(function(res) {
    console.log(res);
  });
}

getAlertsStatus();

// using ES8 async/await
async function getAlertsStatus() {
  console.log(await omnibusConnection.find());
}

getAlertsStatus();

Common Errors

UnhandledPromiseRejectionWarning

Example:

(node:90251) UnhandledPromiseRejectionWarning: #<Object>
(node:90251) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:90251) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

This error indicates that there is a Promise rejection but it is not handled correctly. Update your code to handle errors, example:

omnibusConnection
  .find()
  .then(res => {
    console.log(res);
  })
  .catch(error => {
    console.log(error);
  });

Contributing

See the Contributors Guide

Changelog

See the Changelog

License

This library is licensed under the MIT License

Feedback

If you encounter any bugs or other issues, please file them in the issue tracker

Trademark information

IBM Tivoli Netcool OMNIbus is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.