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	string	1	A URI linking to this resource.
retentionRules	array	0..n	List of Retention rule, see below.
statistics	PagingStatistics	1	Information about paging statistics.
prev	string	0..1	A URI linking to a potential previous page of tenants.
next	string	0..1	A URI linking 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
self	string	0..1	A URI linking to this resource.
id	string	1	RetentionRule ID.
dataType	string	0..1	RetentionRule will be applied to this type of documents. Possible values: ALARM, AUDIT, EVENT, MEASUREMENT, OPERATION, *
fragmentType	string	0..1	RetentionRule will be applied to documents with fragmentType.
type	string	0..1	RetentionRule will be applied to documents with type.
source	string	0..1	RetentionRule will be applied to documents with source.
maximumAge	long	1	Maximum age of document in days.
editable	boolean	1	Whether the rule is editable. Can be updated only by management tenant.

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 retentionRule>>",
    "maximumAge": 12,
    "self" : "<<URL of new retentionRule>>",
    "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 retentionRule>>",
    "maximumAge": 12,
    "self" : "<<URL of new retentionRule>>",
    "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