zoomdata-client/README.md

Zoomdata Standalone Web Client (SDK)

# Zoomdata Javascript SDK

# [DEPRECATED]
This package is deprecated since Composer 7.10 release and will not be maintained starting 8.0. It is recommended to use Embed Manager as a replacement.

---

## Trusted Access Tokens

The Zoomdata Javascript SDK requires a user's trusted access token to connect to a Zoomdata Server. For information on Trusted Access, its prerequisites, and generating user based tokens, please visit the [Trusted Access Documentation](https://devnet.logianalytics.com/hc/en-us/articles/4407303174807-Trusted-Access#Generate)

## Install the library

```ssh
npm install zoomdata-client
```

`zoomdata-client` comes built as an UMD. You are able to use it both in a browser from `node_modules`:

```html
<script src="node_modules/zoomdata-client/sdk/zoomdata-client.js" type="text/javascript"></script>
```

or in a browser served from your Zoomdata server (update the URL accordingly):

```html
<script src="https://localhost:8443/composer/sdk/zoomdata-client.js" type="text/javascript"></script>
```

or as a commonJS module:

```javascript
var ZoomdataSDK = require('zoomdata-client');
```

## Create a Client

When instantiating a Zoomdata JS client, you need to supply connection properties as well as an authentication trusted access token. The `.createClient` function returns a [Javascript Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to the client.

```javascript
var credentials = {
    access_token: TRUSTED_ACCESS_TOKEN,
};

var application = {
    secure: false,
    host: 'localhost',
    port: 8080,
    path: '/composer',
};

ZoomdataSDK.createClient({
    credentials: credentials,
    application: application,
}).then(function (client) {
    console.log('Validated:', client);
});
```

## Create a Query

When creating a Query, you need to supply a Data Source name as well as a query configuration.

The `.createQuery` function returns a [Javascript Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to the validated Query.

```javascript
client.createQuery(
    { id: 'source_id' },
    {
        filters: [],
        groups: [
            {
                name: 'userincome',
                limit: 10,
                sort: {
                    dir: 'asc',
                    name: 'userincome',
                },
            },
        ],
        metrics: [],
    },
);
```

### Query Configuration Details

A Query can be Grouped or Ungrouped.

An Ungrouped Query only requires an array of fields. _This configuration will return all records with just the **userincome** and **usergender** fields._

```javascript
{
    fields: ['userincome, usergender'];
}
```

A Grouped Query requires an array of Groupings. Optionally, you can include an array of Metrics. _This configuration will group by the **userincome** field and calculate the **average** of the **usersentiment** field._

```javascript
{
    groups: [{
        name: 'userincome',
        limit: 10,
        sort: {
            dir: 'asc',
            name: 'usergender'
        }
    }],
    metrics: [{
        name: 'usersentiment',
        func: 'avg'
    }]
}
```

All Queries can include an optional array of filters. _This configuration will filter only results with a **usersentiment** between **-0.5** and **0.5**_.

```javascript
{
    filters: [
        {
            path: 'usersentiment',
            operation: 'BETWEEN',
            value: [-0.5, 0.5],
        },
    ];
}
```

## Run a Query

When running a Query, you must provide a callback that receives new data as it arrives from the Zoomdata Server.

```javascript
client.runQuery(query, function (data) {
    console.log(data);
});
```

## Embed a Chart

When embedding a Chart, you must provide an HTML element to embed the chart into, a query to run for the chart, the name of the visualization, and an object for overriding Chart Variables.

**Note:** You can find variable names and values in your Zoomdata Server's Source Configuration Page.

```javascript
var variables = {
    Size: 'count',
};

client.visualize({
    element: document.body,
    query: query,
    visualization: 'Donut',
    variables: variables,
});
```

## Example

```javascript
var credentials = {
    access_token: TRUSTED_ACCESS_TOKEN,
};

var application = {
    secure: false,
    host: 'localhost',
    port: 8080,
    path: '/zoomdata',
};

var variables = {
    Size: [{ name: 'count' }],
};

ZoomdataSDK.createClient({
    credentials: credentials,
    application: application,
})
    .then(function (client) {
        client
            .createQuery(
                { name: 'Real Time Sales' },
                {
                    filters: [],
                    groupBy: [
                        {
                            name: 'userincome',
                            limit: 10,
                        },
                    ],
                    metrics: [],
                },
            )
            .then(function (query) {
                client.runQuery(query, function (data) {
                    console.log(data);
                });

                client
                    .visualize({
                        element: document.body,
                        query: query,
                        visualization: 'Donut',
                        variables: variables,
                    })
                    .catch(onError);
            })
            .catch(onError);
    })
    .catch(onError);

function onError(reason) {
    console.error(reason.stack || reason.statusText || reason);
}
```

## Licensing

Zoomdata Javascript SDK is licensed under the terms of the
[Zoomdata EULA](https://zoomdata.com/eula).

See the [LICENSE](./LICENSE) file for further information.