Login if you already have an account



Create a new account. join us!



Need some help? Check out our forum.


FYI – Datagraph with Objects and Collections

As a developer, I want to have complete control of my objects and collections on the backend.

There are so many terms being thrown around these days that it is often difficult to separate the truth from the marketing hype. So – at FatFractal, when we talk about our Datagraph capabilities, we mean a real graph, not marketing hype. To illustrate, let me show you a couple of simple examples.

You can see working code for everything below (here).
You can access the source code for the sample application (here).

Most of the time, you will define an object and map it to a identical collection.

Let’s start with couple of simple object definitions:

function Movie() {
this.title = null;
this.description = null;
this.year = null;
function Actor() {
this.firstName = null;
this.lastName = null;

Then, we add the following to our FFDL (what’s this?), to define these object types and collections on the backend as follows:

CREATE OBJECTTYPE Movie (title STRING, description STRING, year NUMERIC)

Note – that the two collections are typed to an object type (Movie and Actor), which means that attempting to store a Movie in the Actors collection or vice-a-versa will generate a validation error.

But, let’s say that you want to create a collection of favorites and allow it to hold different object types, while also still being able to distinguish them from each other. No problem, to do that, let’s add a new collection called Favs that is not typed:



First, let’s store an object in a collection typed to a Movie object type:

var m = new Movie();
m.title = "Argo";
m.description = "Argo is a 2012 historical drama thriller film directed by Ben Affleck.";
m.year = 2012;
ff.createObjAtUri(m, "/Movies");

Now – let’s try saving a Movie to the Favs collection…

ff.createObjAtUri(m, "/Favs");

Similarly, you can store an Actor in the Actors collection or in the Favs collection…

var a = new Actor();
a.firstName = "Ben";
a.lastName = "Affleck"
FatFractal.createObjAtUri(a, "/Actors");
FatFractal.createObjAtUri(a, "/Favs");

But, if you try to store a Movie in the Actors (or vice-a-versa) collection, you will get an error…

FatFractal.createObjAtUri(m, "/Actors");

Now – let’s see how you can retrieve objects of a particular class from a collection that holds more than one object type.

Get all the Movie objects from the Favs collection…

ff.getArrayFromUri("/ff/resources/Favs/(clazz eq 'Movie')", function(r) {
// handle success
}, function(code,message){
// handle error

Get all the Actor objects from the Favs collection…

ff.getArrayFromUri("/ff/resources/Favs/(clazz eq 'Actor')", function(r) {
// handle success
}, function(code, message){
// handle error

Get all the objects from the Favs collection…

ff.getArrayFromUri("/ff/resources/Favs/", function(r) {
// handle success
}, function(code, message){
// handle error

That’s it – we hope that you will agree that this is another example of FatFractal being the most flexible, robust and capable backend for your app – enjoy!


FYI – You can run batch routines (CRON) jobs on FatFractal

As a developer, I want to be able to schedule code to run periodically on my backend so that I can clean up my data, generate reports or any other function that is not generated by an event or API call.

In addition to Event Handlers which execute based on data events and Server Extensions that execute on an API call, FatFractal also supports running backend code on a periodic basis using our Schedule Code capability. Any number of functions can be defined that execute on defined schedules. This has many applications from data administration to reporting, there really is no limit to what you can do with this.

Scheduled Code is defined in the same manner as Event Handlers and Server Extensions in your FFDL (what’s this?). You can define as many scheduled code events to be executed as you wish very easily as follows:

SCHEDULE <task name> <schedule> AS <script type>:<script text>

Where schedule is given in CRON format:

<minute (0-59)> <hour (0-23)> <day of month (1-31)> <month (1-12)> <day of week (0-6)>

For example, if I want to send out a daily report that lists the number of users for my cool new app, I would create a function like this in a file (here called EventHandlers.js):

ff = require('ffef/FatFractal');
exports.userReport = function() {
var n = ff.getArrayFromUri("/FFUser").length;
var msgSubject = "Application user total daily report";
var msgString = "You now have " + n + " users loving your application";
host: "<mailserver>", port: "<port>",
auth: "<true|false>", authPort: "<port>",
username: "<username>", password: "<password>",
from: "<fromAddress>", to: "<toAddress>",
cc: null, bcc: null, // included for completeness
subject: msgSubject,
text: msgString,
html: null // included for completeness. When supplied, the HTML message is
// sent, the text is also included as fallback if HTML viewing
// is not enabled in the receiver's email client

And, then to schedule this be sent out daily at midnight, the FFDL would be:

SCHEDULE UserReport 0 0 * * * AS javascript:require(‘scripts/EventHandlers).userReport();

That’s it – an approach that is very consistent with everything else which allows you to easily schedule any code that you like to execute on a defined schedule.

For more details on FFDL, the docs are here.

For more details on Scheduled Code, the docs are here.

Have fun!


FYI – FatFractal Server Extensions lets you extend your API with any function that you want

As a developer, I want to be able to add any function without limitation to my API so that I can… do just about anything!

As Gary mentioned in his post about the origins and future of FatFractal’s NoServer -

The cloud should… Not prevent me from doing anything else that I want to do”

Server Extensions are, essentially, a means to extend your API with any kind of function that you desire. Server Extensions accept data as needed, execute any code that you want and return a broad set of return types (JSON, HTML) allowing virtually unlimited capabilities for your backend. They are easy to create, and you can add as many as you wish.

What can I do with a Server Extension?

The uses for Server Extensions are very broad, but a few examples are:

  • Aggregate data on the fly without corrupting your data model.
  • Access other backend services (e.g. salesforce, sap, etc.), then transform/ return the results.
  • Data management/administrative functions.
  • Manipulate and return HTML, images, videos, documents or any other MIME type.

Extending your API

Accessing a server extension is as simple as naming it in your FFDL (what’s this?), which will provide URI access to this particular function.

CREATE EXTENSION /extension_name AS javascript:require (‘scripts/MyExtensions.js’).function_to_be_executed();

This will add a new URI endpoint to your application that looks like:


When that URI is called, the function function_to_be_executed that is in the file MyExtensions.js in the ff-scripts directory will be called. Any provided parameters or data are made available to the function as well. You also have the option to declare the function to be secured (default) or add UNSECURED which allows a non-authenticated user to call the function as desired.

Passing in Data

There is a wealth of data from a request that is made available to a Server Extension, including:

httpMethod: the HTTP method (eg. GET, POST, PUT, DELETE, HEAD)
httpRequestUri: the request URI, relative to your application’s base URL
httpParameters: A map of the request parameters
httpHeaders: A map of the request headers
httpCookies: For convenience, a map of the cookies from the Cookie request header
httpContent: A map corresponding to the JSON content supplied in the request body, if any
ffUser: the guid of the logged-in user

This means that you can process according to the httpMethod used, pass in data as httpContent or as URL parameters and authenticate based on the user making the request – in short, you have a lot of flexibility on getting what you want into a Server Extension.

Return Types

You also have control over what gets returned by the extension, including the following:

result: the data or content that you wish to return
responseCode: the appropriate http response code
statusMessage: an informational status message useful for debugging
mimeType: the MIME type of the response content

One of the most useful abilities that Server Extensions provide is the additional return MIME types that are supported. For example, you could create an image resizing service and set the MIME type of the return (e.g. “image/jpeg” or “image/png”). Or, you could read an html template file, replace elements to personalize it and return a web page (“text/html”). And, of course, you can always return data as well (“application/json”), which is the default.

You can also implement as much error handling as you want based on what data is received as well as the result of the operation itself. For example, checking for required information and returning an appropriate error code with a message that you want.

The following example of an extension that validates a user registration from a link shows a number of these features in use:

exports.verifyRegistration = function() {
var data = ff.getExtensionRequestData();
var hc = require('ringo/httpclient');
var r = ff.response();
// check if user guid provided
var guid = data.httpParameters['guid'];
if (! guid) {r.result = null;
r.responseCode = "400";
r.statusMessage = "ActivationRequest guid not supplied";
r.mimeType = "text/html";
// check if activationRequest exists
var activationRequest = ff.getObjFromUri("/ff/resources/ActivationRequest/" + guid);
if (! activationRequest) {
var htmlContent = hc.get(ff.getHttpAppAddress() + '/validateuser.html').content;
htmlContent = htmlContent.replace("___SUBJECT___", "ERROR");
htmlContent = htmlContent.replace("___MESSAGE___", "The validation request for this account no longer exists. ";
htmlContent = '' + htmlContent;
r.result = htmlContent;
r.responseCode = "404";
r.statusMessage = "ActivationRequest could not be found";
r.mimeType = "text/html";
// check if user exists
var user = ff.getUser(activationRequest.userGuid);
if (! user) {
r.result = null;
r.responseCode = "404";
r.statusMessage = "User could not be found";
r.mimeType = "text/html";
// checks passed - now create the welcome html from a template and return
user.active = true;
r.responseCode = "200";
var htmlContent = hc.get(ff.getHttpAppAddress() + '/validateuser.html').content;
    htmlContent = htmlContent.replace("___SUBJECT___", "Thank You!");
htmlContent = htmlContent.replace("___MESSAGE___", "Your account has been activated.";
htmlContent = '' + htmlContent;
r.result = htmlContent;
r.statusMessage = "User now activated";
r.mimeType = "text/html";

Hope you find this useful…


For more information about Server Extensions, see the docs here.

For more information about FFDL, see here.

FYI – FatFractal provides an amazingly flexible event model for your business logic (when foo changes, do bar)

As a developer, I want to be able to create business logic for my backend using a language that I am familiar with so that I can quickly implement my solution without having to learn something new.

I must confess that this is one of my favorite things about the FatFractal platform. Essentially this involves an amazingly simple method for creating business logic on your backend and I hope that you will find the freedom and flexibility as convenient and useful as I do.

Business Logic

I am used to creating object classes on my backend, and then writing lots of inline business logic to manage my objects (data). I would create actions like createOrder within which I would do all kinds of things like validation, notification, etc. within each one. All fine, but requires lots and lots of code, a lot of discipline to ensure consistency as well as to avoid overloading any particular function with too much cruft.

So now, Backend as a Service provides good CRUD methods making it easy to persist your data to the backend, but most leave a * huge * amount to be desired in terms of implementing business logic on the backend, relegating the developer to dealing with in the client code causing bloat, poor performance and data reliability concerns.

Maybe there is a better way…

As Gary writes in his blog about the origins of NoServer -

“The cloud should:

  • Store and retrieve my objects.
  • Securely – permissions and security should be robust and at a fundamental level.
  • Efficiently – with easy to create queries that get me what I want.
  • Execute code on the backend when my data changes (events).
  • Not prevent me from doing anything else that I want to do.”

Event Handlers/ User Stories

With FatFractal’s Event model, I am now free to define discrete pieces of functionality that are bound to events generated as my data “changes”. All together, they define my business logic for my application backend much easier than ever before.

This means that I need to think about things differently in terms of how I architect my code. The good news is that, if you are a fan of user stories as I am, then this you will find it interesting that this maps really well for those that can be implemented on the backend. You can literally implement one-for-one against user stories. It also means that I can implement my business logic with amazingly little code – very cool!

For example:

As the administrator of foo, I want to make sure that all requisite info is present before I store an Order so that I do not have a lot of zombie orders in my data.

exports.validateOrder = function() {
var order = ff.getEventHandlerData();
if (!order.amount || (order.amount <= 0) {
throw {statusCode:400, statusMessage:'An order amount greater than zero is required'};

As a vendor, I want to be alerted via email when an Order greater than $5000 is received so that I can be glad that I started this business afterall.

exports.alertBigOrder = function() {
var order = ff.getEventHandlerData();
if (order.amount >= 5000) {
var user = ff.getObjFromUri("ff/resources/FFUser/" + order.createdBy);
var name = user.firstName + " " + user.lastName;
var msgSubject = "Woo Hoo - you got an order for " + order.amount;
var msgString = "Order " + order.amount + " was created by " + name;
        ff.sendEmail ({
            host: "<mailserver>", port: "<port>",
            auth: "<true|false>", authPort: "<port>",
            username: "<username>", password: "<password>",
            from: "<fromAddress>", to: "<toAddress>",
cc: null, bcc: null, // included for completeness
            subject: msgSubject,
            text: msgString,
html: null // included for completeness. When supplied, the HTML message is
// sent, the text is also included as fallback if HTML viewing
// is not enabled in the receiver's email client

Controlling your Event Handlers with FFDL

You have complete control over how these events are handled (SYNC (PRE or POST), ASYNC) as well as the order in which things are executed using FFDL (what’s this?). So to define the two functions above in your FFDL, you just add the following:

CREATE HANDLER validateOrder PRE ON /Order CREATE AS javascript:require (‘scripts/MyEventHandlers.js’).validateOrder();
This means that the validateOrder() function will be called when a new order is Created, but before the Order is actually stored (PRE). This ensures that the order has all the requisite info and prevents storing zombie orders.
CREATE HANDLER alertBigOrder ASYNC ON /Order CREATE AS javascript:require(‘scripts/MyEventHandlers.js’).alertBigOrder();
This means that when a new order is Created, an alert will be sent via email Asynchronously, but only after the PRE event is cleared.

So – there you have it! Events makes it really simple to visualize and implement your business logic with simple functions that are easy to create and maintain. While this makes it really easy to do many, many things – there are some things that need even more, and that is where Server Extensions come to bear. Will post about those soon.

Happy coding!


For more information about Event Handlers, see here.

For more information about FFDL, see here.

See Gary’s blog post about the origins of NoServer here.

FYI – FatFractal supports many many to many many relationships (huh?)!

As a developer, I want to easily add many to many relationships between my objects without join tables so that I get a rich data model without getting data-model nightmares

With FatFractal, you can create amazing relationships between your objects. One of the things that makes this particularly useful is the ability to add multiple kinds of relationships from any particular object:

Example: If in your application.ffdl file that was created when you scaffolded your app, you include the following

CREATE OBJECTTYPE Comment (profile REFERENCE /Profile, comment STRING, relatedTo REFERENCE)

This provides a ubiquitous “Comment” object that has two references and a “Comment” Collection typed to contain only “Comment” objects.

First, you will see a reference to the author public profile:

profile REFERENCE /Profile

This defines a relationship for the profile member which is bound to the /Profile Collection (which happens to contain only Profile objects thus “typing” the reference).

It also includes a reference called relatedTo:


This relationship is unique in that there is no Collection specifed, and thus no Objecttype implied. This means that the relationship for the relatedTo member can be to any object in any Collection of any Objecttype – i.e. is not “typed” and not bound to any particular Collection.

So now I have a comment object that has a reference to any other object in any other collection – pretty nice! All comments can are accessible via a single collection (/Comment) which is also nice.

But – what makes this truly useful is that you can also access comments via BackReferences to an object. For example, to see all comments (of Objecttype Comment) that relates to any particular object at all (as example, supR – a SupportRequest instance):

ff.getArrayFromUri(supR.ffUrl + "/BackReferences.Comment",
function(anArrayOfComments) {
// This returns an array of "Comments" that relateTo supR!!
function(onError) {}

Where the SupportRequest object model is defined as:

function SupportRequest() {
this.clazz = "SupportRequest";
this.subject = null;
this.body = null;
this.relatedTo = null;
this.profile = null;
return this;

Note that the SupportRequest does not even include anything about “Comment” in its definition. This means that you add relationships easily and intuitively without the pain of onerous data models – in short without the nightmares.

Hope this spurs some ideas for your application…

For more on the background of this, see Gary’s blog here.

For more details about FFDL, see the documentation here.

For more details about Queries, see the documentation here.

For more details about References and BackReferences, see the documentation here.


FYI – Permissions can be inherited from other objects (pretty slick!)

As a Developer, I want to be able to implement access control policies that are inherited from another object so that I can easily propagate access control policies within my application.

If you want to set a default permission for objects in a collection that inherit permissions from another object, it is super easy using FFDL (what is FFDL?).


Say you have a Collection of JokeBook objects with permission defaults set and another Collection of Joke objects that have a reference to a JokeBook and you would like your Joke objects to inherit their default permissions from JokeBook objects. OK – short version is that I want the permissions for a Joke to be the same as the JokeBook they refer to.

The FFDL would look something like:

# JokeBook
CREATE OBJECTTYPE JokeBook (title STRING, writers REFERENCE /FFUserGroup, readers REFERENCE /FFUserGroup)
PERMIT read:object.readers write:object.writers ON /JokeBooks

This defines a JokeBooks Collection that contains Jokebook Objects that have a title, a reference to an author, a reference to a group of users with write access named writers and a group of users with read access named readers.

# Joke
CREATE OBJECTTYPE Joke (setup STRING, punchline STRING, book REFERENCE /JokeBook)
PERMIT read:object.book.readers write:object.book.writers ON /Jokes

This defines a Jokes Collection that contains Joke Objects which have a a reference called “book” from the JokeBooks Collection:

book REFERENCE /JokeBooks
So, you will notice that read and write permissions for a Joke object are set to refer to the read and write permissions (respectively) that are defined for the JokeBook object referred to by the “book” member.

PERMIT read:object.book.readers, write:object.book.writers ON /Jokes

Voila! Now the Joke object has the same permissions as the JokeBook object – as easy as that!

Of course, this is the default setting and you can always change the access to any particular object programmatically in your application code.

Hope you find this useful!!

For more details, see the FFDL documentation here.

To see the other things you can do with permissions see here.