v8 (v7 Rails v1 Django)
Serializing your records
To be interpreted correctly by the ForestAdmin UI, the data must be sent from your admin backend using a particular structure.
This structure needs to comply to the JSON API standard. The JSON API standard is used to ensure a standardized way to format JSON responses returned to clients. You can find some more information directly from their website.
Most of the time, your admin backend will handle this for you, and you will not have to play with serialization. However you might encounter specific use cases that will require you to serialize data yourself, such as smart collections for example.
In order to help you do so, the helper
RecordSerializer is made available through the packages built-in your admin panel.Initializing the record serializer
SQL
MongoDB
1
const { RecordSerializer } = require('forest-express-sequelize');
2
3
const recordSerializer = new RecordSerializer({ name: 'customer_stats' });
Copied!
1
const { RecordSerializer } = require('forest-express-mongoose');
2
3
const recordsSerializer = new RecordSerializer({ modelName: 'customer_stats' });
Copied!
To make use of the serializer, simply get it from your agent package, and initialize it with a collection of yours. The serializer will retrieve the structure of the collection, and thus, will know which attributes it needs to take in to perform the serialization.1
Example 1 - Smart collection with simple fields
SQL
MongoDB
/forest/customer_stats.js
1
const { collection } = require('forest-express-sequelize');
2
3
collection('customer_stats', {
4
isSearchable: true,
5
fields: [{
6
field: 'email',
7
type: 'String',
8
}, {
9
field: 'orders_count',
10
type: 'Number',
11
}, {
12
field: 'total_amount',
13
type: 'Number',
14
}],
15
});
Copied!
/forest/customer_stats.js
1
const { collection } = require('forest-express-mongoose');
2
3
collection('customer_stats', {
4
isSearchable: true,
5
fields: [{
6
field: 'email',
7
type: 'String',
8
}, {
9
field: 'orders_count',
10
type: 'Number',
11
}, {
12
field: 'total_amount',
13
type: 'Number',
14
}],
15
});
Copied!
The serializer exposes a
.serialize() method that takes as an argument an array of objects (or a single object). In the smart collection example, this array would be as such:SQL
MongoDB
1
const records = [
2
{
3
id: 67427,
4
email: '[email protected]',
5
orders_count: '4',
6
total_amount: 93800,
7
created_at: 2018-03-19T14:59:59.440Z,
8
updated_at: 2018-03-19T15:00:00.443Z
9
},
10
{
11
id: 67429,
12
email: '[email protected]',
13
orders_count: '3',
14
total_amount: 106700,
15
created_at: 2018-03-19T15:00:08.430Z,
16
updated_at: 2018-03-19T15:00:09.134Z
17
},
18
...
19
]
Copied!
1
const records = [
2
{
3
_id: 5eebcb6bb9faba06df0cd7a9,
4
email: '[email protected]',
5
orders_count: '4',
6
total_amount: 93800,
7
created_at: 2018-03-19T14:59:59.440Z,
8
updated_at: 2018-03-19T15:00:00.443Z
9
},
10
{
11
_id: 5eec5c30b9faba06df0cd917,
12
email: '[email protected]',
13
orders_count: '3',
14
total_amount: 106700,
15
created_at: 2018-03-19T15:00:08.430Z,
16
updated_at: 2018-03-19T15:00:09.134Z
17
}
18
...
19
]
Copied!
To perform the serialization just use the
.serialize() method like this:1
const serializedRecords = recordSerializer.serialize(records)
Copied!
The serialized records are formatted as follows:
SQL
MongoDB
1
{
2
data: [
3
{
4
type: 'customer_stats',
5
id: '67427',
6
attributes: {
7
email: '[email protected]',
8
orders_count: '4',
9
total_amount: 93800
10
}
11
},
12
{
13
type: 'customer_stats',
14
id: '67429',
15
attributes: {
16
email: '[email protected]',
17
orders_count: '3',
18
total_amount: 106700
19
},
20
},
21
...
22
]
23
}
Copied!
1
{
2
data: [
3
{
4
type: 'customer_stats',
5
id: '5eebcb6bb9faba06df0cd7a9',
6
attributes: {
7
email: '[email protected]',
8
orders_count: '4',
9
total_amount: 93800
10
}
11
},
12
{
13
type: 'customer_stats',
14
id: '5eec5c30b9faba06df0cd917',
15
attributes: {
16
email: '[email protected]',
17
orders_count: '3',
18
total_amount: 106700
19
},
20
},
21
...
22
]
23
}
Copied!
This is the proper format expected by the UI to correctly display the records.
Example 2 - Smart collection example with an added belongsTo relationship
Now let's say we want to reference the customer related to a stat instead of just displaying its
email. We would then adapt the smart collection definition to include a field customer referencing the customers collection:SQL
MongoDB
/forest/customer_stats.js
1
const { collection } = require('forest-express-sequelize');
2
3
collection('customer_stats', {
4
isSearchable: true,
5
fields: [{
6
field: 'orders_count',
7
type: 'Number',
8
}, {
9
field: 'total_amount',
10
type: 'Number',
11
}, {
12
field: 'customer',
13
type: 'String',
14
reference: 'customers.id',
15
}],
16
});
Copied!
/forest/customer_stats.js
1
const { collection } = require('forest-express-mongoose');
2
3
collection('customer_stats', {
4
isSearchable: true,
5
fields: [{
6
field: 'orders_count',
7
type: 'Number',
8
}, {
9
field: 'total_amount',
10
type: 'Number',
11
}, {
12
field: 'customer',
13
type: 'String',
14
reference: 'customers._id',
15
}],
16
});
Copied!
For the belongsTo relationship to be properly serialized, the records passed on to the serializer should include the related object (here
customer), following this structure:SQL
MongoDB
1
const records = [
2
{
3
id: 67427,
4
customer: {
5
id: 27048
6
},
7
orders_count: '4',
8
total_amount: 93800,
9
created_at: 2018-03-19T14:59:59.440Z,
10
updated_at: 2018-03-19T15:00:00.443Z
11
},
12
{
13
id: 67429,
14
customer: {
15
id: 27049
16
},
17
orders_count: '3',
18
total_amount: 106700,
19
created_at: 2018-03-19T15:00:08.430Z,
20
updated_at: 2018-03-19T15:00:09.134Z
21
},
22
...
23
]
Copied!
1
const records = [
2
{
3
id: 5eebcb6bb9faba06df0cd7a9,
4
customer: {
5
id: 5eebcb6bb9faba06df0cd7a9
6
},
7
orders_count: '4',
8
total_amount: 93800,
9
created_at: 2018-03-19T14:59:59.440Z,
10
updated_at: 2018-03-19T15:00:00.443Z
11
},
12
...
13
]
Copied!
Now if we try to serialize this data, the serializer will automatically detect that the records to be serialized include another record (customer in this case), based on the collection definition.
The included records will then be picked up and wrapped to comply to the JSON API relationships format.
1
const serializedRecords = recordsSerializer.serialize(records)
Copied!
The serialized records are formatted as follows:
SQL
MongoDB
1
{
2
data: [
3
{
4
type: 'customer_stats',
5
id: '67427',
6
attributes: {
7
orders_count: '4',
8
total_amount: 93800
9
},
10
relationships: {
11
customer: {
12
data: {type: "customers", id: "27048"}
13
links: {related: {href: "/forest/customer_stats/67427/relationships/customer"}}
14
}
15
}
16
},
17
...
18
],
19
included: [
20
{
21
type: "customers"
22
id: "27048"
23
attributes: {
24
id: 27048
25
}
26
},
27
...
28
]
29
}
Copied!
1
{
2
data: [
3
{
4
type: 'customer_stats',
5
id: '5eebcb6bb9faba06df0cd7a9',
6
attributes: {
7
orders_count: '4',
8
total_amount: 93800
9
},
10
relationships: {
11
customer: {
12
data: {type: "customers", id: "5eebcb6bb9faba06df0cd7a9"}
13
links: {related: {href: "/forest/customer_stats/5eebcb6bb9faba06df0cd7a9/relationships/customer"}}
14
}
15
}
16
},
17
...
18
],
19
included: [
20
{
21
type: "customers"
22
id: "5eebcb6bb9faba06df0cd7a9"
23
attributes: {
24
id: "5eebcb6bb9faba06df0cd7a9"
25
}
26
},
27
...
28
]
29
}
Copied!
Note that the
customer relationship is clearly indicated under the relationships attribute. Also note that the customer is automatically wrapped in the included section, with its attributes if you specified some (only id in this case).