Zoomdata Version

Upgrading Zoomdata with Custom Applications

Because Zoomdata is installed software, your organization must decide whether and when to install any particular upgrade. This topic will help you understand considerations involved in upgrading to any version of Zoomdata based on the SDK or API functionality that you used so you can plan accordingly. This topic does not address all API changes, but only those that could adversely affect your work if you upgrade without planning for them.

Have you created or imported a custom chart in Chart Studio?

Migrating to Zoomdata version 2.5 from earlier versions requires an additional process because chart export and import is intended to share charts with other Zoomdata users and not to migrate custom charts from one Zoomdata version to another. The process requires you to copy your code from Chart Studio in your existing installation to Chart Studio in your upgraded installation. After that, use the Chart Studio UI to configure chart controls, variables, and libraries.

The controller object, which integrates custom charts with Zoomdata, has not changed from Zoomdata 2.2 to Zoomdata 2.5.

Did you white label Zoomdata with custom CSS?

The CSS in Zoomdata evolves with the client application.

Versions 2.2, 2.3, and 2.4: Changes between these have been relatively minor. Still, before you go to production with a new version of Zoomdata, you should test any custom CSS previous versions.

Version 2.5: Changes to the CSS in the Zoomdata client application are substantial from version 2.4 to version 2.5. You need to examine all existing CSS and probably need to modify much of it.

Does your application use REST APIs?

Zoomdata’s REST API offerings have increased significantly between 2.2 and 2.5. Two major considerations should put you at ease:

  • No deprecations: We’ve taken pains to add functionality without removing anything. Newer API versions have added endpoints and some endpoints return more data in their responses, but in this process, nothing has been removed from an existing API version.

  • Continuity of usage: If you wish to continue using the APIs from a previous release for any reason, you can do so by using the relevant API. The API version is specified by using Content-Type in the request header.

    • API version 1.0 becomes available in Zoomdata 2.2. Use Content-Type: application/vnd.zoomdata.v1+json.
    • API version 1.1 becomes available in Zoomdata 2.4. Use Content-Type: application/vnd.zoomdata.v1_1+json.
    • API version 2.0 becomes available in Zoomdata 2.5. Use Content-Type: application/vnd.zoomdata.v2+json.

    To use the latest version, whatever that may be, use Content-Type: application/vnd.zoomdata+json.

    Calls available in later versions, such as v2 (introduced in Zoomdata 2.5) may not be available with earlier versions of Zoomdata, once introduced, an API call is maintained in later versions.

    If your current code uses Content-Type: application/vnd.zoomdata+json, that is, the latest version on your Zoomdata server, and you wish to continue using an earlier version after upgrading, rewrite your REST calls to use the specific version that you need.

     

Does your application use an iFrame-embedded dashboard?

Any dashboard already embedded in a custom application using an iFrame will continue to work as-is with newer versions of Zoomdata. Starting with Zoomdata 2.4, iFrame-embedded dashboards have additional capabilities. These capabilities are invoked using parameters included with the embedding code.

Does your application use the Javascript client library?

The Javascript client library is used to embed charts or data directly into a web application without using an iFrame. Before upgrading Zoomdata, consider the following topics.

Chart variables

To standardize and stabilize the Zoomdata SDK, we have gradually evolved how we encode chart variables. The unfortunate side effect is that later versions of Zoomdata do not support the encoding used by earlier versions. The good news is that the evolution is complete and the new encoding is intuitive and stable.

  • In 2.2, chart variables are not written in standard JSON.
  • In 2.3, chart variables are written in standard JSON that is then stringified.
  • In 2.4 and later, chart variables are written in standard JSON and left unstringified.

JSON modifications

Some key-value pairs are now wrapped in objects. Specifically:

  • Data source name: the name of a data source, used for creating a query, before version 2.3 had the syntax
    {
    source: "Real Time Sales",
    ...
    }
    Starting in 2.3, the syntax is now:
    {
    source: {name: "Real Time Sales"},
    ...
    }
  • The same change applies to certain other values, which used to be simple strings and are now objects. Affected values include:
    • filter.path, which before version 2.3 required a string, starting in v2.3 requires {name: "string"}.

Deprecated objects and methods

We have deprecated some child objects and methods of the query child objects in favor of new, more robust offerings. Deprecated methods will still work in v2.5 but may eventually be removed. We suggest you begin to transition to the new objects and methods.

Getters and setters for query objects

In versions prior to 2.4, query's children, query.filters, query.metrics, query.fields, and query.groups each provide the following methods:

  • add()
  • change()
  • get()
  • remove()
  • reset()
  • set()

Starting in 2.4, new methods are offered directly from query: query.addMetrics(), query.changeMetric(), query.getMetrics(), query.removeMetrics(), query.resetMetrics(), and query.setMetric(), as well as like methods for filters and fields.

For several reasons, groups and its methods are still used as in query.groups.add().

Have you created a custom connector?

Custom connectors built to work with Zoomdata versions prior 2.5 continue to function as expected with Zoomdata version 2.5.