Overview
Introduction
CoolCalc is a cloud based platform built on modern architecture that is used to deliver high-end technical tools in any application.
With CoolCalc you can:
- Deliver any tool
- To any client
- At any point in any workflow
The underlying data set is shared over the life cycle of the real-world work flow. No matter who needs to access, no matter what point in the flow or what application they're using, the CoolCalc API makes the relevant data available when and where they need it.
Distributed web application
Stand-alone, siloed web applications are in many ways a thing of the past and being replaced by distributed web applications much like the old “company towns” have been replaced by global supply chains.
| Old | New |
|---|---|
| Your proprietary data behind corporate firewalls. | Cloud based API shares data across organizational boundaries. |
| Fixed data formats that inhibit sharing or reusing data. | Organizational units overlay only their own proprietary data. |
| Custom built applications with rigid work flows and no flexibility to adapt to future needs. | Individual users view and modify only the information that is of interest to them, using their own preferred or existing applications and platforms. |
| Piece-meal information sharing via copying, exporting, printing, emailing, etc. | API architecture for flexible work flows. |
| Use multitude of “collaboration tools” only because the tools you use in your own work flow aren't built for collaboration. | Cloud based user interfaces for easy integration in any application or platform. |
Distributed web applications permit each of the relevant stakeholders to view and modify only the information that is of interest to them, using their own existing applications, without the traditional copying, exporting, printing, emailing of information.
Technical description
The CoolCalc architecture includes the following principal components:
- REST API
- CDN hosted libraries including JavaScipt, CSS and static HTML
- Server-side libraries to be implemented on your local server (*) (**)
- Static HTML element in any page on your site to render the CoolCalc UI (***)
- Lightweight JavaScript library installed on your local server to initialize the CoolCalc applications
- Local CSS for easy customization of visual appearance
- (*) Only if your server is an identity provider, typically OEMs or distributors.
- (**) If corporate IT policies prevent installation of third party libraries and alternate SSO based implementation is available.
- (***) For mobile apps we recommend embedding the CoolCalc user interface as a web view in your app.
The CoolCalc user interface is implemented as a static HTML element in any page on your site, with a few CSS and JavaScript links to CDN hosted libraries. A diminutive local JavaScript library contains configurations and code to initialize the CoolCalc user interface on page load.
The CoolCalc API is designed as a server-to-server web service to guarantee data privacy of our API customers and their end users. For OEM and distributor installations a small server side library is implemented on your server, essentially to forward the HTTP requests from the CoolCalc user interface to the CoolCalc API.
The "MJ lite" application is designed to be used by HVAC contractors and is deployed entirely client side using only HTML, JavaScript and CSS. No server side programming is required to deploy the "MJ lite" application. To guarantee data privacy, the "MJ lite" user interface communicates via XHR and CORS to a remote identity provider - typically an OEM, distributor or the coolcalc.com branded site for independent contractors – which then forwards the request to the CoolCalc API.
The CoolCalc API is designed as a so called "Level-3" REST API. As such, the CoolCalc API does not publish a list of end points but rather the entry points for each of its applications. From the published entry points, clients can navigate all of the exposed resources by following HATEOAS links provided by the API. All of the functionality available in the user interface is also exposed via the REST API.
The CoolCalc JavaScript library, static HTML and boilerplate CSS are hosted on the CoolCalc CDN. Clients who wish to do an extensive degree of customization may choose to host a modified version of the static HTML and CSS on their own servers.
Installing the libraries
To get started, clone or download our coolcalc-clients repository on Github (https://github.com/silverliningco/coolcalc-clients) which contains sample implementations in various languages.
Some configuration and implementation details are required on your side. The CoolCalc applications rely on the client's session/user management which is typically different in every installation. Additionally, visual appearance, branding and utility functions such as PDF conversion and email send functionality can be customized on your side.
Implementation required on your side:
We recommend familiarizing yourself with the complete documentation but for the purposes of quick reference the following is a list of configuration and implementation required on your side, with links to the relevant section(s) in the documentation:
- Install server-side library for your specific language or platform. (link)
- Enter your API credentials in the server-side library. (link)
- Implement the JSON output of the end user identification endpoint in the server-side library. (link)
- Implement verification of the user identification (account nr) URL segment in the main CoolCalc client endpoint in the server-side library. (link)
- Implement HTML to PDF endpoint in the server-side library. (link)(link)
- Implement MJ8 report email/share endpoint in the server-side library. (link)(link)
- Implement static HTML for the CoolCalc user interface on your site. (link)
- Enter valid Google maps API key in the static HTML for your CoolCalc user interface.
- Verify configuration attributes in local JavaScript library. (link)
- Edit local CSS for desired visual appearance (optional) (link)
- Edit static HTML for downloadable MJ8 report for visual appearance and branding (optional) (link)
- Implement JavaScript handler for CSRF protection (optional) (link)
The README files in each of the sample clients on our Github repository contain additional details relevant to the specific language/platform.
SSO implementation
If our standard implementation is not feasible in your existing platform, an alternate implementation is available where the CoolCalc applications are deployed on separate servers outside of your existing network, and users access the CoolCalc applications via a single sign-on.