netsapiens-charts-library

Netsapiens React data visualization library

Pre-requisites

nodejs >= 0.6.x

Installation

Yarn

$ yarn add git+https://github.com/netsapiens/netspiens-charts-library.git

Npm

$ npm install git+https://github.com/netsapiens/netspiens-charts-library.git

Download

Alternatively download from git and add the script locally as an asset. The files are found under the dist folder.

• dist/netsapiens-charts-{version}.js
• dist/netsapiens-charts-{version}.map.js

The library will be added to the window/global scope and can be accessed using window.nsCharts in the browser or global.nsCharts for CommonJs implementations.

Usage

To import the entire library

import * as nsCharts from 'netsapiens-charts-library';

To keep bundle sizes smaller the library can be cherry picked by importing parts of the library.

import { Bar } from 'netsapiens-charts-library';

Charts

The library exports all charts from the Nivo library and Netsapiens custom chart/data visual

ResponsiveTable

Displays a material design table. The behavior is partly controlled by props of the data. For example: Column sorting can be turned on by a flag called isSortable.

| Prop | PropType | | Description | | ------------------------- | -------- | ------------- | ----------- | | cellComponentsOverride | array | Optional | An array of cell components can be used to override the internal cell components | | data | object | Required | See data shape below | | order | string | Optional | Order direction: 'asc' or 'desc' | | orderBy | string | Optional | Name of the column to order by |

const data = {
  order: 'desc', // 'asc' or 'desc'
  orderBy: 'att', // Match header and cell data id to sort by
  hData: [ // header data
    {
      id: 'presence', // id used to keep the row unique
      numeric: false, // floats right if the value is numeric
      label: '', // Header column display label
    },
    {
      id: 'att',
      numeric: true,
      label: 'Avg. Talk Time',
      isSortable: true, // Makes the column sortable
    },
  ],
  rData: [ // row data
    {
      id: 1, // Unique row id, user/agent id
      data: [
        {
          id: 'presence',
          component: 'Presence', // Cell component, must match available cell components
          value: 'available'
        },
        { id: 'name', value: 'name' },
        { id: 'status', value: 'status' },
        { id: 'att', value: 1.4940 },
        { id: 'ch', value: 11 },
      ],
    },
    {
      id: 2,
      data: [
        { id: 'presence', value: 'presence' },
        { id: 'name', value: 'name' },
        { id: 'status', value: 'status' },
        { id: 'att', value: 2.4940 },
        { id: 'ch', value: 12 },
      ],
    },
  ],
};

import { ApiConnector, ResponsiveTable, SocketConnector } from 'netsapiens-charts-library';

<ApiConnector {...props}> // Get initial data from api
  <SocketConnector {...props}> // Subscribe to socket updates
    <ResponsiveTable {...props} /> // required
  </SocketConnector>
</ApiConnector>

Add-ons

Add-ons are used to give Nivo charts additional functionality

Wrapper

Wrapper component that can be used for any chart.
Internally there is a <div> container for applying styles and className around the chart.

This wrapper component should always be used on the most outer part of the composition.

| Prop | PropType | | Description | | -------------- | -------- | ------------- | ----------- | | children | element | Required | Nivo chart component or Wrapper containing Nivo chart | | containerClass | string | Optional | Container class name/s | | containerStyle | object | Optional | Container style/s |

import { Wrapper, ResponsiveLine } from 'netsapiens-charts-library';

<Wrapper
  containerClass={'animated fadeIn'}  // optional
  containerStyle={{display: 'block'}} // optional
>
  <ResponsiveLine {...props} /> // required
</Wrapper>

ApiConnector

Wrapper component for fetching data from the api. The data will be passed as a prop to the Nivo chart.

A loading component is required so it can be displayed while the data is fetched.

An optional fetch function can be passed to override the internal fetch function. This may be useful for aggregating data.

If a fetch function is not provided, authToken, params and url are required.

| Prop | PropType | | Description | | ----------- | -------- | ------------- | ----------- | | authToken | string | Required | Jwt token | | children | element | Required | Nivo chart component or wrapper containing a Nivo chart | | interval | integer | Optional | How often the data should be fetched | | loader | element | Required | Loading component | | requests | array | Required | Array of request objects { params: Required, adapter: Optional, adapterParams: Required } | | url | string | Optional | Full api url path |

import { Wrapper, ApiConnector, ResponsiveLine } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <ApiConnector {...props}>
        <ResponsiveLine {...props} /> // required
    </ApiConnector>
</Wrapper>

SocketConnector

Wrapper component for providing data from a socket. The data will be passed as a prop to the Nivo chart.

A loading component is required so it can be displayed while the data is fetched.

Optional initial data can be provided and is recommended in the cases where the socket connection only emits data when BE/DB changes occur. Note: the component doesn't have a mechanism fot aggregating event data at this time. If needed, an additional prop can be made to provide an aggregation function.

| Prop | PropType | | Description | | -------------- | -------- | ------------- | ----------- | | children | element | Required | Nivo chart component | | data | object | Optional | Provides initial data while the connection is being made, bridges the gap for socket network latency | | events | array | Required | Array of { name: 'event name', adapter: function, adapterParams: object } | | socket | object | Required | socket.io client connection |

import { Wrapper, SocketConnector, ResponsiveLine } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <SocketConnector {...props}>
        <ResponsiveLine {...props} /> // required
    </SocketConnector>
</Wrapper>

This can also be used in conjunction with ApiConnector to provide the initial data.

To avoid race conditions, the SocketConnector won't be called until the ApiConnector has provided the initial data.

import { Wrapper, ApiConnector, ApiConnector, ResponsiveLine } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <ApiConnector {...props}> // optional ApiConnector
        <SocketConnector {...props}>
            <ResponsiveLine {...props} /> // required
        </SocketConnector>
    </ApiConnector>
</Wrapper>

Data Adapters

Data adapters are used to transform data from a a given dataset into Nivo compatible formats.

callQueueToLineAdapter

This adapter will only work with data from the Netsapiens api (see Api call example below) and adapts data to be used in Nivo line charts.

Api call example

See: https://corp.netsapiens.com/ns-api/webroot/apidoc/#api-Call_Queue-Report

| Param | value | | -------------- | --------------- | | object | callqueuereport | | action | read | | domain | netsapiens.com | | type | queue_name | | logic | count(*) | | range_interval | UTC offset | | value_offset | UTC offset | | start_date | 2018-07-19 00:00:00 | | end_date | 2018-07-23 23:59:59 | | stat | VOL | | format | json |

Function params

| Param | type | Description | | -------------- | --------------- | ----------- | | data | array | Api response | | dateTimeRange | optional object | This is used to specify the expected date/time range. Default: { startDateTime: 'moment -24 hours "YYYY-MM-DD HH:mm"', endDateTime: 'moment "YYYY-MM-DD HH:mm"' } | dateTimeFormatPattern | string | Moment.js format string. Default: 'YYYY-MM-DD HH:mm' |

The adapter can be used in multiple ways, it can be called as a standalone function or as a prop.

Standalone

import moment from 'moment';
import nsSDK from '@netsapiens/netsapiens-js';
import { callQueueToLineAdapter } from 'netsapiens-charts-library';

nsSDK.api.get({
  object: 'callqueuereport',
  action: 'read',
  domain: '...',
  type: 'queue_name',
  logic: 'count(*)',
  // moment needs any date with time 00:00:00 to get the correct UTC offset
  // its best to use the current date, different times of the year might hav ea different offset
  range_interval: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  value_offset: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  start_date: '2018-07-19 00:00:00',
  end_date: '2018-07-23 23:59:59',
  stat: 'VOC',
  format: 'json',
}).then(res => {
  console.log(callQueueSumToLineAdapterToLineAdapter({ data: res }));
});

As a prop

import { Wrapper, ApiConnector, ResponsiveLine, callQueueToLineAdapter } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <ApiConnector {...props} adapter={callQueueToLineAdapter}>
        <ResponsiveLine {...props} /> // required
    </ApiConnector>
</Wrapper>

callQueueSumToLineAdapter

This adapter will only work with data from the Netsapiens api (see Api call example below) and adapts data to be used in Nivo line charts.

Api call example

See: https://corp.netsapiens.com/ns-api/webroot/apidoc/#api-Call_Queue-Report

| Param | value | | -------------- | --------------- | | object | callqueuereport | | action | read | | domain | netsapiens.com | | type | queue_name | | logic | count(*) | | range_interval | UTC offset | | value_offset | UTC offset | | start_date | 2018-07-19 00:00:00 | | end_date | 2018-07-23 23:59:59 | | stat | VOL | | format | json |

Function params

| Param | type | Description | | -------------- | --------------- | ----------- | | data | array | Api response | | dateTimeRange | optional object | This is used to specify the expected date/time range. Default: { startDateTime: 'moment -24 hours "YYYY-MM-DD HH:mm"', endDateTime: 'moment "YYYY-MM-DD HH:mm"' } | dateTimeFormatPattern | string | Moment.js format string. Default: 'YYYY-MM-DD HH:mm' |

The adapter can be used in multiple ways, it can be called as a standalone function or as a prop.

Standalone

import moment from 'moment';
import nsSDK from '@netsapiens/netsapiens-js';
import { callQueueSumToLineAdapter } from 'netsapiens-charts-library';

nsSDK.api.get({
  object: 'callqueuereport',
  action: 'read',
  domain: '...',
  type: 'queue_name',
  logic: 'count(*)',
  // moment needs any date with time 00:00:00 to get the correct UTC offset
  // its best to use the current date, different times of the year might hav ea different offset
  range_interval: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  value_offset: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  start_date: '2018-07-19 00:00:00',
  end_date: '2018-07-23 23:59:59',
  stat: 'VOC',
  format: 'json',
}).then(res => {
  console.log(callQueueSumToLineAdapter({ data: res }));
});

As a prop

import { Wrapper, ApiConnector, ResponsiveLine, callQueueSumToLineAdapter } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <ApiConnector {...props} adapter={callQueueSumToLineAdapter}>
        <ResponsiveLine {...props} /> // required
    </ApiConnector>
</Wrapper>

callQueueSumPercentToLineAdapter

This adapter will only work with data from the Netsapiens api (see Api call example below) and adapts data to be used in Nivo line charts.

Api call example

See: https://corp.netsapiens.com/ns-api/webroot/apidoc/#api-Call_Queue-Report

| Param | value | | -------------- | --------------- | | object | callqueuereport | | action | read | | domain | netsapiens.com | | type | queue_name | | logic | count(*) | | range_interval | UTC offset | | value_offset | UTC offset | | start_date | 2018-07-19 00:00:00 | | end_date | 2018-07-23 23:59:59 | | stat | SL | | format | json |

Function params

| Param | type | Description | | -------------- | --------------- | ----------- | | data | array | Api response | | dateTimeRange | optional object | This is used to specify the expected date/time range. Default: { startDateTime: 'moment -24 hours "YYYY-MM-DD HH:mm"', endDateTime: 'moment "YYYY-MM-DD HH:mm"' } | dateTimeFormatPattern | string | Moment.js format string. Default: 'YYYY-MM-DD HH:mm' |

The adapter can be used in multiple ways, it can be called as a standalone function or as a prop.

Standalone

import moment from 'moment';
import nsSDK from '@netsapiens/netsapiens-js';
import { callQueueSumPercentToLineAdapter } from 'netsapiens-charts-library';

nsSDK.api.get({
  object: 'callqueuereport',
  action: 'read',
  domain: '...',
  type: 'queue_name',
  logic: 'count(*)',
  // moment needs any date with time 00:00:00 to get the correct UTC offset
  // its best to use the current date, different times of the year might hav ea different offset
  range_interval: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  value_offset: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  start_date: '2018-07-19 00:00:00',
  end_date: '2018-07-23 23:59:59',
  stat: 'SL',
  format: 'json',
}).then(res => {
  console.log(callQueueSumPercentToLineAdapter({ data: res }));
});

As a prop

import { Wrapper, ApiConnector, ResponsiveLine, callQueueSumPercentToLineAdapter } from 'netsapiens-charts-library';

// optional Wrapper
<Wrapper
  containerClass={'animated fadeIn'}
  containerStyle={{display: 'block'}}
>
    <ApiConnector {...props} adapter={callQueueSumPercentToLineAdapter}>
        <ResponsiveLine {...props} /> // required
    </ApiConnector>
</Wrapper>

agentsStatusToTableAdapter

This adapter will only work with data from the Netsapiens api (see Api call example below) and adapts data to be used in Netsapiens custom Table chart.

Api call example

See: https://corp.netsapiens.com/ns-api/webroot/apidoc/# todo

| Param | value | | -------------- | --------------- | | object | agent | | action | read | | domain | netsapiens.com | | range_interval | UTC offset | | start_date | 2018-07-24 | | end_date | 2018-07-24 | | stats | CH, ATT | | queue_name | * | | format | json |

Function params

| Param | type | Description | | -------------- | --------------- | ----------- | | data | array | Api response |

The adapter can be used in multiple ways, it can be called as a standalone function or as a prop.

Standalone

import moment from 'moment';
import nsSDK from '@netsapiens/netsapiens-js';
import { agentsStatusToTableAdapter } from 'netsapiens-charts-library';

nsSDK.api.get({
  object: 'agent',
  action: 'read',
  domain: 'netsapiens.com',
  start_date: '2018-07-24',
  end_date: '2018-07-24',
  range_interval: `${moment(moment().format('MM/DD/YYYY 00:00:00')).utc().hours()} HOUR`,
  stats: 'CH,ATT',
  queue_name: '*',
  format: 'json',
}).then(res => {
  console.log(agentsStatusToTableAdapter({ data: res }));
});

As a prop

import { ApiConnector, ResponsiveTable, agentsStatusToTableAdapter } from 'netsapiens-charts-library';

// optional Wrapper
<ApiConnector {...props} adapter={agentsStatusToTableAdapter}>
    <ResponsiveTable {...props} /> // required
</ApiConnector>

agentPresenceSocketToTableAdapter

This adapter will only work with data from the Netsapiens socket server.

Socket subscription example

socket.emit('subscribe', { type: 'agent', domain: decoded.domain, user: decoded.user, bearer: token, });

Function params

| Param | type | Description | | -------------- | --------------- | ----------- | | data | array | Existing data | | socketData | object | Socket data |

Standalone

import moment from 'moment';
import nsSDK from '@netsapiens/netsapiens-js';
import { agentPresenceSocketToTableAdapter } from 'netsapiens-charts-library';

socket.emit('subscribe', {
    type: 'agent',
    domain: decoded.domain,
    user: decoded.user,
    bearer: token,
});

socket.on('agent', (socketData) => {
  const updatedData = agentPresenceSocketToTableAdapter({
    data: existingData,
    socketData,
  });
});

As a prop

import {
  ApiConnector,
  ResponsiveTable,
  agentsStatusToTableAdapter,
  agentPresenceSocketToTableAdapter,
} from 'netsapiens-charts-library';

// optional Wrapper
<ApiConnector {...props}>
    <SocketConnector
      socket={socket}
      events={[{ name: 'agent', adapter: agentPresenceSocketToTableAdapter }]}
    >
        <ResponsiveTable {...props} /> // required
    </SocketConnector>
</ApiConnector>

Testing

Unit tests are run using Jest.

TODO - links and further explanation

Unit testing

A test coverage report is generated in coverage/*. You can view the coverage report bu opening coverage/lcov-report/index.html in a browser.

> npm run test:unit

Dev testing

Copy the dev-testing.config.sample.js file and rename to dev-testing.config.js then enter your username and password you would like to use.

The library/dev-testing bundle needs to be run in order for this to work.

If you haven't already built the library after cloning the project, it needs to be run first.

> npm install
> npm run build

Then the dev-testing bundle. What this does is build all the dev-testing source files so the page can be run in the browser.

> npm run build:dev

During automation bundle development an additional flag can be used to watch the files.

> npm run build:dev:watch

Now that the bundle is built make sure Apache is pointing to automation/build/

> sudo ln -s <path to project>/dev-testing/build charts-dev

Then restart Apache

After restarting Apache the automation setup is ready.

You can now open up the browser manually by navigating to https://local.netsapiens.com/charts-dev