Define a collection

🟢 Beginner

collection

osp-collections osp-web

This example shows how to define a basic collection using a schema.ospp file for the data structure and a schema.collections file for indexes, filters, and auto-increment.

  • Define the JSON Schema for a device collection with five typed properties.

  • Configure collection-level filters based on a status field in schema.ospp.

  • Set up indexes, filter queries, and auto-increment in schema.collections.

git checkout origin/osp-collections-configuration .
git checkout origin/osp-web-configuration .
git checkout origin/example-collections-defined-from-schema .

Configuration structure

  • schema.ospp: defines the data schema for the MongoDB entries, using JSON Schema.

    • schema.collections: defines the collection properties for the OnSphere module

This collection will be used to store devices with the following properties:

  • no: automatically generated number (auto-incremented)

  • description: description of the device

  • serial: serial of the device

  • ip_address: IP address of the device

  • status: connection state of the device

Steps

1. Define the data schema

Create a schema.ospp file and define the schema as following:

 2    "schema": {
 3        "type": "object",
 4        "properties": {
 5            "no": { "type": "integer" },
 6            "description": { "type": "string" },
 7            "serial": { "type": "string" },
 8            "ip_address": { "type": "string" },
 9            "status": {
10                "type": "string",
11                "enum": [
12                    "Connected",
13                    "Disconnect"
14                ]
15            }
16        },
17        "required": ["serial", "ip_address", "status"]
18    },

Warning

In addition to the schema definition, we define two filters based on the status property. The actual queries behind the filters are defined in the schema.collections file.

19    "filters": [
20        {
21            "id": "filter_status_connected",
22            "name": "Device is connected"
23        },
24        {
25            "id": "filter_status_disconnected",
26            "name": "Device is disconnected"
27        }
28    ]

Your entire file should look like this:

 1{
 2    "schema": {
 3        "type": "object",
 4        "properties": {
 5            "no": { "type": "integer" },
 6            "description": { "type": "string" },
 7            "serial": { "type": "string" },
 8            "ip_address": { "type": "string" },
 9            "status": {
10                "type": "string",
11                "enum": [
12                    "Connected",
13                    "Disconnect"
14                ]
15            }
16        },
17        "required": ["serial", "ip_address", "status"]
18    },
19    "filters": [
20        {
21            "id": "filter_status_connected",
22            "name": "Device is connected"
23        },
24        {
25            "id": "filter_status_disconnected",
26            "name": "Device is disconnected"
27        }
28    ]
29}

2. Define the collection based on this schema

Create a file named schema.collections in the same folder as the schema.ospp. In this file, we define :

  • the collection name

  • indexes to improve requests response time

  • filter queries (IDs have to match with filters defined in schema.ospp)

  • auto-increment for the no field

Your file should look like this:

{
    "moduleId": "modules.collections.collections-1",
    "collectionName": "ip_devices",
    "indexes": [
        {
            "name": "no",
            "index": "{'no': 1}"
        },
        {
            "name": "serial",
            "index": "{'serial': 1}"
        },
        {
            "name": "ip_address",
            "index": "{'ip_address': 1}"
        },
        {
            "name": "status",
            "index": "{'status': 1}"
        }
    ],
    "filters": [
        {
            "id": "filter_status_connected",
            "query": "{status: 'Connected'}"
        },
        {
            "id": "filter_status_disconnected",
            "query": "{status: 'Disconnect'}"
        }
    ],
    "autoIncrementFields": ["no"]
}

Warning

Now you can create/update the collection with a script or from a CollectionTable/Form widget. You can follow this example to create a dashboard containing a CollectionTable.