The SolarUser Datum Expire API provides methods to manage datum expiration policies and submit ad hoc datum delete tasks. Expiration policies are applied continuously by SolarNetwork, for all active configurations. Ad-hoc delete tasks are executed just once, after submitting one.

All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

Many endpoints return localized messages. The locale of the response is determined by the Accept-Language HTTP header passed on the request. If not provided, the default locale of the SolarNetwork service will be used.

A data configuration object represents the criteria for what data should be deleted. Each object contains the following properties:

An example expiration data object looks like the following:

{
  "id": 6,
  "created": "2018-07-11 04:01:41.859Z",
  "userId": 1,
  "name": "Raw power after 2y",
  "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
  "active": false,
  "expireDays": 730,
  "datumFilter": {
    "aggregation": "None",
    "nodeIds": 123,
    "sourceIds": ["/power/*"]
  }
}

This object represents the criteria to choose from which datum streams to delete. Each object contains the following properties:

An example expiration data object looks like the following:

{
  "aggregationKey": "0",
  "nodeIds": 123,
  "sourceIds": ["/power/*"]
}

List the available aggregation types for configuring in an expiration datum filter object.

The response is a list of aggregation localized service objects. An example looks like this:

{
  "success": true,
  "data": [
    {
      "id": "0",
      "locale": "en-NZ",
      "localizedDescription": "None",
      "localizedName": "None"
    },
    {
      "id": "h",
      "locale": "en-NZ",
      "localizedDescription": "Hour",
      "localizedName": "Hour"
    },
    {
      "id": "d",
      "locale": "en-NZ",
      "localizedDescription": "Day",
      "localizedName": "Day"
    },
    {
      "id": "M",
      "locale": "en-NZ",
      "localizedDescription": "Month",
      "localizedName": "Month"
    }
  ]
}

List all available expire configurations.

The response contains a list of expire configuration objects. Each configuration has the following properties:

An example response looks like:

{
  "success": true,
  "data": {
    "dataConfigs": [
      {
        "id": 6,
        "created": "2018-07-11 04:01:41.859Z",
        "userId": 1,
        "name": "All raw after 2y",
        "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
        "active": false,
        "expireDays": 730,
        "datumFilter": {
          "aggregation": "None"
        }
      },
      {
        "id": 5,
        "created": "2018-07-11 01:49:11.335Z",
        "userId": 1,
        "name": "Fleeting",
        "serviceIdentifier": "net.solarnetwork.central.user.expire.standard.DefaultUserExpireDataFilterService",
        "active": false,
        "expireDays": 7,
        "datumFilter": {
          "sourceIds": [
            "/power/switch/*"
          ],
          "aggregation": "Month"
        }
      }
    ]
  }
}

Create or update an expiration data configuration to define a datum expiration policy. The request body must be a full JSON expiration data configuration object.

Delete an expiration data configuration.

Preview the effects of applying an expiration data configuration. This will show you a summary of how many datum would be deleted if the configuration were applied.

The response is a summary object with the following properties:

An example response looks like:

{
  "success": true,
  "data": {
    "date": "2022-03-21 11:00:00Z",
    "datumTotalCount": 1071,
    "datumCount": 819,
    "datumHourlyCount": 188,
    "datumDailyCount": 52,
    "datumMonthlyCount": 12
  }
}

This method allows you to find out how many datum would be deleted if datum matching the submitted criteria were deleted.

The response is the same as in the preview expire data response method. An example response looks like this:

{
  "success": true,
  "data": {
    "date": "2022-03-21 11:00:00Z",
    "datumTotalCount": 1071,
    "datumCount": 819,
    "datumHourlyCount": 188,
    "datumDailyCount": 52,
    "datumMonthlyCount": 12
  }
}

This method allows you to deleted a range of datum matching the submitted criteria. The request takes the same parameters as the Delete datum preview method. The data is not deleted immediately. Instead, a delete job is scheduled and will be performed at some point in the future. You can view the status of jobs using the Delete datum jobs list method.

The response object is a delete datum job object, with the following properties:

An example response looks like this:

{
  "success": true,
  "data": {
    "id": "7d8a3ad7-0c2c-44ab-b708-6555296f4af3"
    "jobState": "Queued",
    "userId": 147,
    "configuration": {
      "nodeIds": [1,2,3]
      "sourceIds": ["/power/1","/power/2"],
      "aggregation": "None",
      "localStartDate": "2019-01-22 00:50:00",
      "localEndDate": "2020-01-25 04:00:00"
    },
    "percentComplete": 0.0,
    "submitDate": 1648002593507,
    "startedDate": 0,
    "completionDate": 0,
    "resultCount": 0,
    "success": false,
    "jobDuration": 0,
  }
}

This method allows you to deleted a range of datum matching the submitted criteria. The request takes the same parameters as the Delete datum preview method. The data is not deleted immediately. Instead, a delete job is scheduled and will be performed at some point in the future. You can view the status of jobs using the Delete datum jobs list method.

The response contains a list of delete datum job objects. See the Delete datum response for more information.

This method allows you to view the status of a specific job.

The response will be a delete datum job object. See the Delete datum response for more information.

This method allows you to delete a small set of specific datum, based on unique identifiers.

The request body must be a JSON array of identifier objects representing the specific datum you would like to delete.

⚠️ At most 100 identifiers can be submitted in a single request. In addition, only node datum may be deleted.

Each datum identifier must uniquely identify a single datum, using one of two styles: node and source ID or stream ID. These are detailed in the following sections.

💡 Note that the response will include identifiers with all identifying properties (node, source, and stream IDs).

This style uses node and source IDs to identify the datum. Each identifier object must include the following properties:

An example request using node and source IDs as identifiers looks like this:

[
  {
    "objectId": 1,
    "sourceId": "meter/1",
    "timestamp": "2024-03-04 00:47:00Z"
  },
  {
    "objectId": 1,
    "sourceId": "meter/1",
    "timestamp": "2024-03-03 23:47:00Z"
  }
]

This style uses stream IDs to identify the datum. Each identifier object must include the following properties:

⚠️ If an identifier object provides a streamId then any objectId and sourceId property values will be ignored.

An example request using stream IDs as identifiers looks like this:

[
  {
    "streamId": "f59d583e-f5a9-48e4-9b00-f837ca87b5b7",
    "timestamp": "2024-03-04 00:47:00Z"
  },
  {
    "streamId": "f59d583e-f5a9-48e4-9b00-f837ca87b5b7",
    "timestamp": "2024-03-03 23:47:00Z"
  }
]

The response is a list of all datum IDs actually deleted. There could be fewer IDs in the response than were submitted if some ID did not match an actual datum.

An example response looks like this:

{
  "success": true,
  "data": [
    {
      "kind": "n",
      "streamId": "f59d583e-f5a9-48e4-9b00-f837ca87b5b7",
      "objectId": 1,
      "sourceId": "meter/1",
      "timestamp": "2024-03-04 00:47:00Z",
      "aggregation": "None"
    },
    {
      "kind": "n",
      "streamId": "f59d583e-f5a9-48e4-9b00-f837ca87b5b7",
      "objectId": 1,
      "sourceId": "meter/1",
      "timestamp": "2024-03-03 23:47:00Z",
      "aggregation": "None"
    }
  ]
}

☝️ Note that the identifier objects in the response will include all identifying properties (node, source, and stream IDs), regardles of which style was used in the request.