Retention rules

Rules are used to removing retention data from data base once a day. Which data will be deleted shows directly retention rules. For example retention rule with dataType=EVENT and maximumAge=30 removes from system all events older than 30 days.
The Retention rules interface consists of parts:

The retention rule collection resource retrieves retention rules, accesible by url /retention/retentions
The retention rule resource represents individual retention rule that can be view, accesible by url /retention/retentions/{retentionRuleId}

Retention rule collection

RetentionRuleCollection [application/vnd.com.nsn.cumulocity.retentionRuleCollection+json]

Name	Type	Occurs	Description
self	URI	1	Link to this resource.
retentionRules	RetentionRule	0..n	List of Retention rule, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	URI	0..1	Link to a potential previous page of tenants.
next	URI	0..1	Link to a potential next page of tenants.

GET a representation of a RetentionRuleCollection.

Response body: RetentionRuleCollection

Required role: ROLE_RETENTION_RULE_READ

Example Request: Get retentionRules as sample_tenant.

GET ...
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.retentionRuleCollection+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.retentionRuleCollection+json;ver=...
Content-Length: ...
{
"statistics": {
    "currentPage": 1,
    "pageSize": 5,
    "totalPages": 1
},
"retentionRules": [
    {
        "dataType": "ALARM",
        "fragmentType": "fragmentType",
        "id": 1,
        "maximumAge": 12,
        "self": "<<URL of retentionRule>>",
        "source": "source",
        "type": "type"
    },
    {
        "dataType": "ALARM",
        "fragmentType": "fragmentType",
        "id": 2,
        "maximumAge": 12,
        "self": "<<URL of retentionRule>>",
        "source": "source",
        "type": "type"
    },
    {
        "dataType": "*",
        "fragmentType": "*",
        "id": 5,
        "maximumAge": 12,
        "self": "<<URL of retentionRule>>",
        "source": "*",
        "type": "*"
    },
    {
        "dataType": "ALARM",
        "fragmentType": "fragmentTypeUpdated",
        "id": 3,
        "maximumAge": 24,
        "self": "<<URL of retentionRule>>",
        "source": "source",
        "type": "type"
    }
],
"self": "<<URL of current page>>"
}

POST - Create a new RetentionRule

Request body: RetentionRule

Response body: RetentionRule

Required role: ROLE_RETENTION_RULE_ADMIN

Example request (full POST):

POST ...
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver...

{
    "dataType":"ALARM",
    "fragmentType":"fragmentType",
    "type":"type",
    "source":"source",
    "maximumAge":"12"
}

Example Response (full POST):

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...
Content-Length: ...
Location: <<URL of new retentionRule>>

{
    "id" : "<<ID of new retetionRule>>",
    "self" : "<<URL of new retetionRule>>",
    "dataType":"ALARM",
    "fragmentType":"fragmentType",
    "type":"type",
    "source":"source",
    "maximumAge":"12",
    "editable":"true"
}

Example request (partial POST):

POST ...
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver...

{
    "dataType":"ALARM",
    "maximumAge":"12"
}

Example Response (partial POST):

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...
Content-Length: ...
Location: <<URL of new retentionRule>>

{
    "id" : "<<ID of new retetionRule>>",
    "self" : "<<URL of new retetionRule>>",
    "dataType":"ALARM",
    "fragmentType":"*",
    "type":"*",
    "source":"*",
    "maximumAge":"12",
    "editable":"true"
}

RetentionRule

RetentionRule [application/vnd.com.nsn.cumulocity.retentionRule+json]

Name	Type	Occurs	Description	Visibility
self	URI	0..1	Link to this resource.	Public
id	Long	1	RetentionRulle id.	Public
dataType	String	0..1	RetentionRule will be applied to this type of documents, possible values [ALARM, AUDIT, EVENT, MEASUREMENT, OPERATION, *].	Public
fragmentType	String	0..1	RetentionRule will be applied to documents with fragmentType.	Public
type	String	0..1	RetentionRule will be applied to documents with type.	Public
source	String	0..1	RetentionRule will be applied to documnets with source.	Public
maximumAge	Long	1	Maximum age of document in days.	Public
editable	boolean	1	Whether the rule is editable. Can be updated only by management tenant.	Public

Fields in RetentionRule are joined by way of the logical operation AND.
For fields: dataType, fragmentType, type, source can be set value “”. Field with value “” during matching fits to all.

GET a representation of a RetentionRule.

Response body: RetentionRule

Required role: ROLE_RETENTION_RULE_READ

Example Request: Get single retentionRule.

GET ...
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...
Content-Length: ...
{
    "dataType": "EVENT",
    "fragmentType": "*",
    "id" : "<<ID of new retetionRule>>",
    "maximumAge": 12,
    "self" : "<<URL of new retetionRule>>",
    "source": "source",
    "type": "*",
    "editable":"true"

}

PUT - Update an existing retentionRule.

Request body: RetentionRule

Response body: RetentionRule

Required role: ROLE_RETENTION_RULE_ADMIN

Example Request :

PUT ...
Host: ...
Authorization: Basic ...
Content-Length: ...
Accept: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...
Content-Type: application/vnd.com.nsn.cumulocity.retentionRule+json;ver=...

{
    "fragmentType":"fragmentTypeUpdated"
}

Example Response :

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.tenant+json;ver=...
Content-Length: ...
{
    "dataType": "EVENT",
    "fragmentType": "fragmentTypeUpdated",
    "id" : "<<ID of new retetionRule>>",
    "maximumAge": 12,
    "self" : "<<URL of new retetionRule>>",
    "source": "source",
    "type": "*",
    "editable":"true"
}

DELETE a representation of a RetentionRule.

Response body: N/A

Required role: ROLE_RETENTION_RULE_ADMIN

Example request:

DELETE [URL to the resource]
Host: [hostname]
Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example response:

HTTP/1.1  204 NO CONTENT