Skip to main content

App Data

buildfire.appData#

appData is a framework provided in buildfire.js that allows the app user and app owner to save and retrieve simple and complex data. The framework facilitates CRUD operations common to all data operations as well as searching, sorting and paging complex data.

App Data differs from publicData, userData, and datastore in that it allows plugins within the same app to share data in a clean, consistent, and reliable way.

This service also takes care of all server side infrastructure to unburden the developer and app owner for developing the server side components and the costs of running a server. This service is provided out of the box at no additional charge.

The appData service also handles caching of data and other performance enhancements.

The use of the appData is completely optional. The developer may choose to communicate with his own custom api.

important

appData has read/write permissions on widget and control side. appData is data that is saved from the widget or control and it's accessable to all users on all plugins.

note

If you want to work with Geospatial data check GeoData Wiki

tip

To support high performance search and sort query check Indexed Fields

Methods#

get()
#

buildfire.appData.get(tag, callback)

Calls the appData to retrieve plugin data objects in JSON format.

note

If there are many objects with the same id, only one random record will be returned

buildfire.appData.get("main record", (err, result) => {
if (err) return console.error("Error while retrieving your data", err);
console.log("Main record", result.data);
});

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after something is done

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag and data
result#
NameTypeDescription
dataobjectObject saved in appData under the selected tag
tagstringObject tag

More Examples#

If your appData has only one object and does not use tags, you can skip the tag argument

buildfire.appData.get((err, result) => {
if (err) return console.error(err);
console.log("Data: ", result.data);
});

getById()
#

buildfire.appData.getById(id, tag, callback)

Calls the appData to retrieve plugin data object by id in JSON format.

buildfire.appData.getById(
"55bfa813032868a0115c5f98",
"main record",
(err, result) => {
if (err) return console.error("Error while retrieving your data", err);
console.log("Object: ", result.data);
}
);

id#

NameTypeRequiredDescriptionDefault
idstringyesDatastore object id

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after something is done

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag and data
result#
NameTypeDescription
dataobjectObject saved in appData under the selected id
tagstringObject appData tag

save()
#

buildfire.appData.save(obj, tag, callback)

This method calls the appData to update all plugin data objects that have that tag. if no object is found it will create one, and does not check for duplicates

note

Data objects saved using save() method will not get assigned ids. Data will be saved in the same format as provided.

buildfire.appData.save(
{ name: "John Doe", tel: "555-111-1111" },
"contactInfo",
(err, result) => {
if (err) return console.error("Error while saving your data", err);
console.log("Data saved successfully", result);
}
);

obj#

NameTypeRequiredDescriptionDefault
objobjectyesObject to be stored in appData

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after something is done

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag and data
result#
NameTypeDescription
dataobjectObject saved in appData
tagstringObject appData tag

insert()
#

buildfire.appData.insert(obj, tag, checkDuplicate, callback)

Calls the appData to insert a data object. If an object already exists with this tag and checkDuplicate is false it will create another record otherwise it will return a duplicate entry error. Use this method to save multiple records under the same tag. Every inserted item will get unique id. You can use this id later in getById

buildfire.appData.insert(
{ name: "John Doe", tel: "555-111-1111" },
"contactInfo",
false,
(err, result) => {
if (err) return console.error("Error while inserting your data", err);
console.log("Insert successfull", result);
}
);

obj#

NameTypeRequiredDescriptionDefault
objobjectyesObject to be stored in appData

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

checkDuplicate#

NameTypeRequiredDescriptionDefault
checkDuplicatebooleannoIf true it will prevent insertion of duplicate records, if false it will allow duplicatesfalse

callback(err, result)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag, data and id
result#
NameTypeDescription
dataobjectObject inserted in appData
tagstringObject appData tag
idstringObject unique id

bulkInsert()
#

buildfire.appData.bulkInsert(obj, tag, callback)

Calls the appData to insert multiple data objects at once. If objects already exist with this tag it will create new records. Use this method to save multiple records with single API call.

note

Data objects inserted using bulkInsert() method will not get assigned ids.

buildfire.appData.bulkInsert(
[
{ name: "John Doe", tel: "555-111-1111" },
{ name: "Jane Doe", tel: "555-222-2222" },
],
"contactInfo",
(err, result) => {
if (err) return console.error("Error while inserting your data", err);
console.log("Insert successfull", result);
}
);

obj#

NameTypeRequiredDescriptionDefault
obj[object]yesArray of object to be inserted in appData

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag, data and id
result#
NameTypeDescription
dataobjectObject array inserted in appData
tagstringObject appData tag

update()
#

buildfire.appData.update(id, obj, tag, callback)

Calls the appData to update the data object that matches that tag and id. If an object doesn't exist this operation will fail. Use this method to update a single record.

buildfire.appData.update(
"55bfa813032868a0115c5f98", // Replace this with your object id
{ name: "John Doe", tel: "555-111-2222" },
"contactInfo",
(err, result) => {
if (err) return console.error("Error while inserting your data", err);
console.log("Update successfull", result);
}
);

id#

NameTypeRequiredDescriptionDefault
idstringyesDatastore object id

obj#

Can be one of two options:

  1. The JSON object you'd like saved.
NameTypeRequiredDescriptionDefault
objobjectyesObject to be updated in appData. Object must contain the original id of the object.
  1. A command object meant to pass data modifying operators to the appData to update certain properties only
NameTypeRequiredDescriptionDefault
objobjectyesData modifying object.

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
resultobjectResult object containing appData tag, data and id
result#
NameTypeDescription
dataobjectObject array inserted in appData
tagstringObject appData tag
idstringObject unique id

More Examples#

buildfire.appData.insert(
{ name: "John Doe", tel: "555-111-1111" },
"contactInfo",
false,
(err, result) => {
if (err) return console.error("Error while inserting your data", err);
console.log("Insert successfull", result);
let objectId = result.id;
buildfire.appData.update(
objectId,
{ name: "John Doe", tel: "555-111-2222" },
"contactInfo",
(err, updatedResult) => {
if (err) return console.error("Error while updating your data", err);
console.log("Update successfull", updatedResult);
}
);
}
);

searchAndUpdate()
#

buildfire.appData.searchAndUpdate(search, obj, tag, callback)

Calls the appData to search and update the data object that matches that tag and search query. Use this method to update a multiple records or to update spacific element on each record.

buildfire.appData.searchAndUpdate(
{ name: { $eq: "John Doe" } },
{ $set: { name: "John Doe Smith" } },
"contactInfo",
(err, result) => {
if (err) return console.error(err);
console.log(result.nModified + " records updated");
}
);

search#

JSON object that containing the filter (search query). See search operators

NameTypeRequiredDescriptionDefault
searchobjectyesObject containing data filters

obj#

Can be one of two options:

  1. The JSON object you'd like saved.
NameTypeRequiredDescriptionDefault
objobjectyesObject to be updated in appData. Object must contain the original id of the object.
  1. A command object meant to pass data modifying operators to the appData to update certain properties only
NameTypeRequiredDescriptionDefault
objobjectyesData modifying object.

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, status)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
statusobjectStatus object
result#
NameTypeDescription
dataobjectObject array inserted in appData
tagstringObject appData tag
idstringObject unique id

More Examples#

How to update and set values inside array of the data objects

buildfire.appData.bulkInsert(
[
{
name: "John Doe",
tel: "555-111-1111",
addresses: [{ city: "San Diego" }],
},
{ name: "Mike Rotch", tel: "555-222-2222" },
],
"contactInfo",
(err, data) => {
if (err) return console.error(err);
console.log("Data inserted successfully");
buildfire.appData.searchAndUpdate(
{ name: "John Doe", "addresses.city": "San Diego" },
{ $set: { "addresses.$.state": "CA" } },
"contactInfo",
(err, result) => {
if (err) return console.error(err);
console.log(result.nModified + " records updated");
}
);
}
);

delete()
#

buildfire.appData.delete(id, tag, callback)

Calls the appData to delete the data object that matches that tag and object id. If an object doesn't exists this operation will fail.

buildfire.appData.delete("YOUR_ID_HERE", "contactInfo", (err, result) => {
if (err) return console.error(err);
console.log("Record deleted");
});

id#

NameTypeRequiredDescriptionDefault
idstringyesObject id issued when inserting the data. Can be retrieved initially using get() method.

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
resultobject{"status": "deleted"}

More examples#

buildfire.appData.insert(
{ name: "John Doe", tel: "555-111-1111" },
"contactInfo",
false,
(err, result) => {
if (err) return console.error("Error while inserting your data", err);
console.log("Insert successfull", result);
buildfire.appData.delete(result.id, "contactInfo", (err, result) => {
if (err) return console.error("Error while deleting your data", err);
console.log("Record deleted");
});
}
);

search()
#

buildfire.appData.search(options, tag, callback)

Calls the appData to search through objects that matches that tag and options criteria. Use this method to search through many records to pull a matching subset. This method allows complex filtering as well as sorting and pagination

buildfire.appData.search(
{
filter: {
$or: [
{ "$json.rank": { $gt: "600", $lt: "900" } },
{ "$json.name": "Jane Doe" },
],
},
sort: { rank: 1, lastName: -1 },
fields: ["rank", "lastName"],
skip: 20,
limit: 10,
},
"contactInfo",
(err, result) => {
if (err) return console.error("there was a problem retrieving your data");
console.log("Records found: ", result);
}
);

options#

JSON object that contains the filter, sort column, pagination parameters and get total records count.

NameTypeRequiredDescriptionDefault
filterobjectnoThe format is inspired by MongoDB. While many features overlap they are not a direct match. You must add $json. as a prefix for any property you want to filter. See search operators
sortobjectnoObject with properties you'd like to sort on with 1 for ascending and -1 for descending
fields[string]noArray of fields that you'd like to get. If this option is not provided all fields will be returned
recordCountbooleannoIf true the result will return the object with totalRecord number and a result arrayfalse
pagenumbernoPage you want to retrieve. Should be used in combination with pageSize0
pageSizenumbernoNumber of records per page, the max value is 50.50
skipnumbernoNumber of record that you need to skip. Should be used with limit0
limitnumbernoNumber of records for this call, the max value is 50.50
note

For pagination you can either use page and pageSize or skip and limit, but not both at the same time

tag#

NameTypeRequiredDescriptionDefault
tagstringnoKey used to differentiate your content saved in appData. ex(settings or questions) etc.

callback(err, result)#

Callback function after data is inserted

NameTypeDescription
errstringerror string, null when operation is successfull
result[object] or objectIf recordCount flag is true, the result is object with totalRecord number and result array, otherwise it's array of fetched objects

More examples#

buildfire.appData.search(
{
filter: {
$or: [
{ "$json.rank": { $gt: "600", $lt: "900" } },
{ "$json.name": "Jane Doe" },
],
},
sort: { rank: 1, lastName: -1 },
fields: ["rank", "lastName"],
page: "0",
pageSize: "10",
},
"contactInfo",
(err, result) => {
if (err) return console.error("there was a problem retrieving your data");
console.log("Found " + result.length + " record(s)");
console.log(("Records": result));
}
);
buildfire.appData.search(
{
filter: {
$or: [
{ "$json.rank": { $gt: "600", $lt: "900" } },
{ "$json.name": "Jane Doe" },
],
},
sort: { rank: 1, lastName: -1 },
fields: ["rank", "lastName"],
skip: 20,
limit: 10,
recordCount: true,
},
"contactInfo",
(err, data) => {
if (err) return console.error("there was a problem retrieving your data");
console.log("Total records " + data.totalRecord + " record(s)");
console.log("Current records " + data.result.length + " record(s)");
}
);

onUpdate()
#

buildfire.appData.onUpdate(callback, allowMultipleHandlers)

Allows you to pass a callback function that is called whenever the control updates data in the appData. Use this method in the widget to be notified that the control made a change so you can reflect that change directly in the widget. Returns a cleanup function to clear the listener.

let onUpdate = buildfire.appData.onUpdate((event) => {
console.log("Data has been updated ", event);
});
// when you want to stop listening
// onUpdate.clear();

callback(event)#

Function you pass that gets called on each appData update

NameTypeDescription
eventobjectUpdated appData records

allowMultipleHandlers#

NameTypeRequiredDescriptionDefault
allowMultipleHandlersbooleannoTells the method to override all other handlers, or allow multiple handlers to exist at the same time.false