Enhanced time series support

General configuration

The Cumulocity IoT Operational Store provides an enhanced time series support (so-called time series collections) for measurements data. The following section summarizes how to enable/disable this feature.

To configure time series support

The enhanced time series support can be configured via a REST API as a tenant configuration. The following example illustrates how to enable time series collections for a subtenant:

POST {sub-tenant-url}/tenant/options
Content-Type: application/json
{
    "category": "configuration",
    "key": "timeseries.mongodb.collections.mode",
    "value": "ENABLED"
}

The following example illustrates how to disable time series collections for a subtenant:

POST {sub-tenant-url}/tenant/options
Content-Type: application/json
{
    "category": "configuration",
    "key": "timeseries.mongodb.collections.mode",
    "value": "DISABLED"
}

Implications of the configuration

The configuration affects the collection that stores measurement data. By enabling or disabling the property, the system switches collections in the background. This might lead to a situation where data resides in multiple collections. To prevent such situations, configure the property only at the beginning of a tenant setup, ideally when no measurement data is stored yet. Migration and seamless configuration will be part of future releases.

Unsupported APIs

The following APIs are not supported and do not have a replacement:

• GET /measurement/measurements/{id}
• DEL /measurements/measurement/{id}

The following API is partially supported:

• DEL /measurements/measurement/

The parameters dateFrom and dateTo are supported and must be truncated to full hours (for example, 2022-08-19T14:00:00.000Z), otherwise an error is returned.

To check whether time series collections are enabled

With the following request, you can check the value of the time series collections property:

GET /tenant/options/configuration/timeseries.mongodb.collections.mode
Content-Type: application/json

An example response if the configuration is enabled:

{
"category": "configuration",
"key": "timeseries.mongodb.collections.mode",
"value": "ENABLED"
}

If the configuration is not set for the tenant at all, you will get a 404 response code for the request above.

Migration process description

Tenant administrators can schedule their tenant or any subtenant for time series collection migration. The time series format of measurements brings the following benefits:

• better performance for measurements queries,
• less storage consumption.

Note that certain limitations are induced in the API which are described in General configuration.

To trigger time series migration

To start the tenant migration follow the steps below:

1. Navigate to Migration > Time series in the application where the plugin is installed. By default this is the Administration application.

2. Select the tenant you want to trigger the migration for from the list of available tenants.

3. Hover over the row of the tenant in the tenant list, then click Add to queue and confirm the operation. The tenant migration status should be updated to Queued, which means that tenant is added into the migration queue.

   Important

   You can add more than one tenant into the migration queue, but the migration is executed only for one tenant at a time. The migration of the next tenant in the queue will not start until you approve the previously migrated tenant.

4. When the migration process is triggered its status for the tenant changes from Queued to In progress. After the data is processed, verified and migrated to the new collection the status of the migration changes to Verified and the Approve and finish migration button is visible in the Ongoing migration section and in the tenant list on hovering over the tenant row. Click Approve and finish migration to confirm the process.

5. A confirmation pop-up shows up providing the following information:

• The new format for time series measurements, which is used after confirming the data migration process.
• That after seven days the legacy collection is removed.
• That the action of approval is irreversible. Click Confirm. This will change the status of the migration to Approved.

6. After seven days the legacy measurements collection is deleted and the migration status changes to Completed.

Migration states

Description and progress monitoring

The Time series migration page is divided into 2 sections. The top one is called Ongoing migration and displays the current state of the ongoing migration for the respective tenant. This section provides control over the active process. The information is displayed only after the migration has started and is in one of the progressing states (In progress, Migrated, Verifying, Verified).

Here you can see the following information:

• Tenant - Tenant name of the tenant the migration process is triggered for.
• Requested by - Name of the user that started the migration.
• Migration range - Date range. Start date is the date of the oldest measurement to be migrated and end date is the date of the newest measurement. This is also the point in time when the migration has started. Migration status - This bar displayed at the right has various functions. Depending on the state it provides either visual information on the current state of the ongoing process or allows to control certain process states. For details of states, see Migration states.

The second section shows the List of tenants with the following infomation for each tenant:

• Tenant - Tenant name.
• ID - Tenant ID.
• Domain - Tenant domain.
• Parent tenant ID - Parent tenant ID.
• Status - Current migration state for the given tenant.
• Requested date - Date when the tenant was added to the queue for migration.
• Requested by - Tenant ID and name of the user who requested the migration.
• Approved date - Date when the migration was approved by the administrator.
• Approved by - Tenant ID and name of the user who approved the migration.

On hovering over a tenant row, you can see one of the following buttons according to the migration state:

• Add to queue - To assign the tenant to the migration queue when it is in Legacy measurements state.
• Cancel migration - To remove the tenant from the migration queue when it is in Queued state. Note that if the progress has already started, it is not possible to resign from migration.
• Approve and finish migration - To approve the migration when it is in Verified state. Note that no other migration will start if there is a tenant pending acceptance.