Upgrading Zoomdata with Custom Applications

Because Zoomdata is installed software, your organization must decide whether and when to install any particular upgrade. The following considerations will help you understand what is 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.

Did You White Label Zoomdata with a Custom CSS?

The CSS in Zoomdata evolves with the client application. Differences in the CSS should be considered before you upgrade. You should examine all existing CSS and modify it accordingly.

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. iFrame-embedded dashboards have additional capabilities that 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 Zoomdata version 2.3 required a string. Starting in version 2.3, it 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 this version but may eventually be removed. We suggest you begin to transition to the new objects and methods.

Have You Created a Custom Connector?

Custom connectors built to work with previous Zoomdata versions continue to function as expected with this Zoomdata version.