It’s easy to get started developing with ClearFactr. No matter what you are building, you will first need to sign up for a developer ClearFactr account (please contact us to start your free trial).
The simplest implementation of ClearFactr involves embedding a view-only spreadsheet, or an interactive spreadsheet that doesn’t need to be saved, within an IFRAME of your browser-based application. This can be accomplished without integrating with our API at all. For all other implementations, some use of our REST API is required.
Both ClearFactr’s API and customizable spreadsheet widget offer a large degree of flexibility. Here are some common forms of implementation to get you started:
Share your spreadsheet-based work product with an audience (of one or more users):
Allow your users to create their own spreadsheet-based work product within your app or website
Our API can be used to populate any existing or new spreadsheet hosted in ClearFactr with data from your own databases or third parties. Say for example that you have your own data calculated from a myriad of sources and proprietary IP. You want to make interactive models that:
Here's how you'd do it:
Now anytime the ClearFactr audience views this model, they will see whatever data your program(s) wrote to it.
Our API can be used to extract any cell's contents (values or text) within a spreadsheet hosted in ClearFactr. There are a variety of ways to do this, depending on your requirements and the design and behavior of the spreadsheet itself.
A very important consideration: ClearFactr's API has a variety of ways of "querying" a model's structure, but this all assumes that what you're looking for can actually be found -- sounds obvious(!), but you'll need to consider if your user can change row or column names, for example, if your code is going to look for things by name. Or if your code is going to look for things by row/column index, and the user can move rows and columns around, you'll likely run into problems, too.
Ideally, you can take advantage of ClearFactr's GUID-based design. Once you have the GUID for the data model item you're looking for, you can use that GUID in the query directly, without regard to the naming or location information. Just make sure in this case that users can't delete these items.
If the structure of the spreadsheet might change (for example, rows and columns may be moved around by the user):
If the cells you're interested in will not physically move around, you can query them by defining a cell range in row/column index coordinates by specifying the locations of the upper left and lower right cells of that range.
Lastly, (and this approach yields the highest performance), you can query cells directly by their GUIDs. This approach also allows you to query cells that are physically scattered around anywhere in the model.
As of this writing, we only support the assignment of new input values to cells, using the GUIDs of those cells. The ability to link cells to each other formulaically will be forthcoming. In the meantime, using the capabilities of the ClearFactr GUI will provide you with the full suite of editing capabilities.
If you require quasi-realtime interaction between your browser-based application, and ClearFactr running within another browser window, tab, or IFRAME, there are some special considerations. By design, for security reasons, browser windows, tabs and IFRAMEs are separate entities and can not communicate with each other (although there are new efforts under way to remove these limitations).
Therefore, any required communication must take place via a shared service. ClearFactr supports this capability by making use of a message queue, to which either application can write to, and read from, and then act upon. There are a number of configuration capabilities here. Please contact us to discuss your needs.
Our customizable spreadsheet widget provides you with many options on how to customize the amount of functionality, access, and control you grant to your users or audience.
Control a user’s ability to make changes based on cell type:
Sometimes you would want to limit what parts of the model are visible, and what operations can be peformed. For example:
The ability to save the spreadsheet, and/or generate new versions, can be configured.
Show/hide certain standard functionality available in ClearFactr depending on your user’s needs:
ClearFactr provides a number of different metrics that can be extremely helping in gauging the amount and type of engagement you're having with your audience. For example:
All of this data is available via ClearFactr's dashboard. Having it available via the API will be forthcoming shortly.
By default, scenarios created, and simulations run, by others are only seen by the owner of the model and not by others that have access to the model. This ensures privacy between various parties, for example, if model is being exposed to ten different clients where you want them to see your work, and you want to see theirs, but you don't want each of the ten to see each others work.
In a team situation, it might be the case that you want all team members to see each other's work. The option for this behavior will be forthcoming shortly.
"The only bad question is the one that's never asked."
Please drop us a line so we can answer any others you may have.
What types of code can my application or website be written in?
Any language/environment in which you're able to formulate and perform GET and POST requests, and process JSON results, will work.
Note that we currently consider our API a "server-side" offering in that we will assign you a unique API "key" and security key that you will use for authentication. You can manage the security key yourself. This can easily be kept 100% secure and private on your side, and will remain so by ensuring that all communications are performed via SSL/HTTPS.
What data do I store on my end and what is stored at ClearFactr?
Other than the API/Security keys, the only other data you may want to store on your side would be various GUIDs used by your applications. For example, you may want to "bind" certain ClearFactr GUIDs to certain pieces of data (or other IDs) of your own data model. Any plans/models that you interact with via the SDK/API will be fully visible and maintainable by you via the full ClearFactr application -- all of that data will be stored on ClearFactr's infrastructure. Further important notes on this are below.
Where does ClearFactr store the data and what are the security specs?
ClearFactr takes security with the utmost importance. As such, ClearFactr is built upon Amazon Web Services. Very few organizations in the world can replicate the security and scalability specifications offered by AWS. This is a great thing, as it's a very hard problem to solve and something that probably isn't core to your business -- relying on AWS affords you the ability to focus on things that are. All of your ClearFactr models' data is stored in a manner that is only accessible via ClearFactr's own infrastructure.
You will be responsible for keeping your authentication details private and secure.
What if I want to store all data in my own environment?
As each situation is different, we can discuss the requirements for doing this. Please contact us.
How often can I ping the API?
Our API is designed to be very high performance -- indeed, the endpoint parameters are what they are for that reason. Any given endpoint should only be called as often as the result is likely to change. This will yield the best response time within your app, and the best end-user experience.
Extra care and consideration should be taken with these situations:
How much downtime do you have?
Because of our reliance on AWS, and because of their architectural redundancies, we have not seen any systemic downtime to date. However, we will occassionally have maintenance windows that we use to make major upgrades to our product(s). The duration of these will typically be in low numbers of minutes and will be announced as far in advance as possible.
"We're not successful if you're not successful. Don't get stuck."
ClearFactr’s world-class team provides phone and email support for all developer clients. If you have additional requirements, we may be able to accommodate. Please just let us know.