brainCloud supports the import and export of Global Entities via JSON files. This is useful for:
Backing up global entity data
Migrating entities from app to app
Integrating easily with external tools
There are four different JSON file formats supported. There are pros and cons to each of them:
Raw JSON Object format - highly recommended for backups and data migration. Not as clean for use with external tools.
Simplified JSON Object format - very good for integration with external tools.
Simplified JSON Line format - useful for integration with external tools that support JSON line format. Limited to a single entity type per file.
CSV format - can be accessed through a variety of applications, supported for the "Exporting" operation only.
Each of the file formats is described in more detail below.
Raw JSON Object Format:
Below is a raw JSON object file.
{
"hero": [
{
"entityIndexedId": "superman",
"timeToLive": null,
"createdAt": 1506914746453,
"data": {
"name": "Superman",
"alignment": "Lawful Good",
"cape": true,
"sex": "m",
"secretIdentity": { "firstName": "Clark", "lastName": "Kent" },
"attributes": {
"intelligence": 90,
"strength": 300,
"charisma": 95
},
"powers": [
"flight",
"xray vision",
"heat vision",
"super strength",
"invulnerable"
],
"skills": ["combat"],
"equipment": ["glasses"]
},
"entityType": "hero",
"appId": "22436",
"entityId": "2642b324-0c86-4779-817a-832c30884c81",
"acl": { "other": 1 },
"ownerId": null,
"version": 1,
"expiresAt": 9223372036854775807,
"updatedAt": 1506914746453
},
{
"entityIndexedId": "batman",
"timeToLive": null,
"createdAt": 1506914673444,
"data": {
"name": "Batman",
"alignment": "Neutral Good",
"cape": true,
"sex": "m",
"secretIdentity": { "firstName": "Bruce", "lastName": "Wayne" },
"attributes": {
"intelligence": 99,
"strength": 95,
"charisma": 90
},
"powers": [],
"skills": [
"martial arts",
"combat",
"detective",
"stealth",
"tactics"
],
"equipment": ["grapple gun", "batarangs", "utility belt"]
},
"entityType": "hero",
"appId": "22436",
"entityId": "9e73c19a-f82e-4385-8bce-320c249b2c9b",
"acl": { "other": 1 },
"ownerId": null,
"version": 1,
"expiresAt": 9223372036854775807,
"updatedAt": 1506914673444
},
{
"entityIndexedId": "wonder woman",
"timeToLive": null,
"createdAt": 1506914835429,
"data": {
"name": "Wonder Woman",
"alignment": "Neutral Good",
"cape": false,
"sex": "f",
"secretIdentity": {
"firstName": "Diana",
"lastName": "Prince"
},
"attributes": {
"intelligence": 90,
"strength": 250,
"charisma": 92
},
"powers": ["flight", "super strength", "invulnerability"],
"skills": ["combat"],
"equipment": ["lasso", "sword", "shield"]
},
"entityType": "hero",
"appId": "22436",
"entityId": "dce12974-d76d-4922-b011-ec596ec14d47",
"acl": { "other": 1 },
"ownerId": null,
"version": 1,
"expiresAt": 9223372036854775807,
"updatedAt": 1506914835429
}
]
}
File format specifics:
EntityTypes are enclosed in JSON arrays - and thus multiple entityTypes are supported.
brainCloud meta-data is preserved
entityId
entityIndexedId
timeToLive
expiresAt
createdAt
updatedAt
version
acl
ownerId ← only if the appId of the record matches the currently selected
appId
Note that although the example above only shows a single entity type, "hero", the file structure does allow multiple types of entities to be present in a single file.
Simplified JSON Object Format:
Simplified JSON is very readable and suitable for round-trip importing and exporting with tools like Google Sheets.
It minimizes the structure and overheads that brainCloud imposes - though that comes with limitations (record-level ACL, ownership, and entityIds are not preserved).
File format specifics:
EntityTypes are enclosed in JSON arrays - and thus multiple entityTypes are supported. ← Same as RAW
brainCloud meta-data is NOT preserved, other than
entityIndexedId(encoded as_eiid) andentityType(represented by the enclosing array)The lack of a "data" section makes the object easier to view and understand
{
"hero": [
{
"name": "Superman",
"alignment": "Lawful Good",
"cape": true,
"sex": "m",
"secretIdentity": { "firstName": "Clark", "lastName": "Kent" },
"attributes": {
"intelligence": 90,
"strength": 300,
"charisma": 95
},
"powers": [
"flight",
"xray vision",
"heat vision",
"super strength",
"invulnerable"
],
"skills": ["combat"],
"equipment": ["glasses"],
"_eiid": "superman"
},
{
"name": "Batman",
"alignment": "Neutral Good",
"cape": true,
"sex": "m",
"secretIdentity": { "firstName": "Bruce", "lastName": "Wayne" },
"attributes": {
"intelligence": 99,
"strength": 95,
"charisma": 90
},
"powers": [],
"skills": [
"martial arts",
"combat",
"detective",
"stealth",
"tactics"
],
"equipment": ["grapple gun", "batarangs", "utility belt"],
"_eiid": "batman"
},
{
"name": "Wonder Woman",
"alignment": "Neutral Good",
"cape": false,
"sex": "f",
"secretIdentity": { "firstName": "Diana", "lastName": "Prince" },
"attributes": {
"intelligence": 90,
"strength": 250,
"charisma": 92
},
"powers": ["flight", "super strength", "invulnerability"],
"skills": ["combat"],
"equipment": ["lasso", "sword", "shield"],
"_eiid": "wonder woman"
}
]
}NOTE - _eiid is not unique - it is simply a lookup index. This is one of the reasons that we delete all entities of a type before importing - so that each import doesn't create more and more entities!
Simplified JSON Lines Format:
JSON Lines files are a bit simpler in structure than JSON object files - in that they don't require the enclosing object array structure.
{"name":"Superman","alignment":"Lawful Good","cape":true,"sex":"m","secretIdentity":{"firstName":"Clark","lastName":"Kent"},"_eiid":"superman"}
{"name":"Batman","alignment":"Neutral Good","cape":true,"sex":"m","secretIdentity":{"firstName":"Bruce","lastName":"Wayne"},,"_eiid":"batman"}
{"name":"Wonder Woman","alignment":"Neutral Good","cape":false,"sex":"f","secretIdentity":{"firstName":"Diana","lastName":"Prince"},"_eiid":"wonder woman"}
Each line of the file is considered a separate JSON object.
Because of this, JSON Lines files can only support a single _entityType_ per file.
Note that we are using a simpler example for better readability. Also, note that the file above contains just 3 lines (it looks like more due to word-wrapping - notice the line numbers).
CSV Format:
In contrast to JSON, CSV requires less technical skill and can be accessed through a wide range of applications. Currently, this format is only supported for the "Exporting" operation.
name,alignment,cape,sex,_eiid,secretIdentity.firstName,secretIdentity.lastName
"Superman","Lawful Good",true,"m","superman","Clark","Kent"
"Batman","Neutral Good",true,"m","batman","Bruce","Wayne"
"Wonder Woman","Neutral Good",false,"f","wonder woman","Diana","Prince"
File format specifics:
Each line of the file is considered a separate record.
brainCloud meta-data is NOT preserved, other than
entityIndexedId(encoded as_eiid)