System Management API

The System Management API is used to manage different types of system settings. This API handles, for now, only management of storage retention periods and generating a signed url to upload a consent document.

There are two types of different retention periods that the system can handle. First is the storage retention periods which is the observation files that every Thing has sent. These are stored on an object storage as a backup and for some cases, direct access. These files are stored indefinitely and with this API you can define for how long (in months) you want to store these files.

The second type is the indexed observations. Every observation is stored in Elasticsearch and is indexed by month. Using this API you can define for how long you want to keep observations indexed (in months) before the system automatically deletes the indexed files. The deletion runs monthly at the start of each month and will always keep at least one month of historical data.

This API is only available for ReadWrite users on the Root domain and should be used very carefully, since this API actually will delete files from the filesystem. Files that has been deleted by these rules are manually retrievable for 180 days before being fully deleted. Please contact Telenor Connexion support if you feel like you have deleted files that shouldn’t have been deleted.

PUT_STORAGE_RETENTION

Required role: ReadWrite
Required privilege: StorageRetention.CREATE

Creates or updates a retention policy based that will delete observations older than the number of months specified in the policy. NOTE: This will permanently delete your data.

API Endpoint: [PUT]: /system-management/storage-retention

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • attributes
    • storageRetentionPeriod: The number of months before deleting observations from the storage. Minimum 2 months. required
    • observationRetentionPeriod: The number of months before deleting observations from the search index. Minimum 2 months but must be lower than the storageRetentionPeriod. required
    • status: The status of the retention, Enabled or Disabled required
    • userName: Your username, needed to authorize the request required
    • password: Your password, needed to authorize the request required

Example payload

{
  "storageRetentionPeriod": 90,
  "observationRetentionPeriod": 60,
  "status": "Enabled",
  "userName": "<userName>",
  "password": "<password>"
}

Response

  • storageRetentionPeriod: The configured number of months before deletion of stored files.
  • observationRetentionPeriod: The configured number of months before deletion of indexed observations.
  • status: The status of the rule.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domain Returned if the user is not on the root domain.
INVALID_RETENTION_PERIOD DaysBeforeDeletion Returned if the requested size was not a number or less than 30.
INVALID_ARGUMENTS Status Returned if the Status was not a Enabled or Disabled.

LIST_STORAGE_RETENTION

Required role: ReadWrite
Required privilege: StorageRetention.READ

Lists any current retention policy set on the storage of observations.

API Endpoint: [GET]: /system-management/storage-retention

Response

  • storageRetentionPeriod: The configured number of months before deletion of stored files.
  • observationRetentionPeriod: The configured number of months before deletion of indexed observations.
  • status: The status of the rule.

Note that if no retention policy is configured the response will be an empty object.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domain Returned if the user is not on the root domain.

DELETE_STORAGE_RETENTION

Required role: ReadWrite
Required privilege: StorageRetention.DELETE

Deletes any existing retention policy on observations.

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • userName: Your username, needed to authorize the request required
  • password: Your password, needed to authorize the request required

API Endpoint: [DELETE]: /system-management/storage-retention

Example payload

{
  "userName": "<userName>",
  "password": "<password>"
}

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domain Returned if the user is not on the root domain.

Required role: Root

Get a signed url to save a consent document as a pdf file.

API Endpoint: [PUT]: /system-management/generate-consent-upload-url

Request

Headers

  • x-api-key: The API Key to identify the request

Body

  • version: A custom version of the document. required

Example payload

{
    "version": 16
}

Response

  • url: The URL to use to put the file. This will give you temporary access to the file that you can use to upload the contents.
  • version: The custom version of the file.

In order to upload the file, your client needs to send a PUT request to this URL with the Content-Type header set to ‘application/pdf’ and the contents given in your file.

A sample upload request body with jquery using the previous payload looks like this:

$.ajax({
  type: 'PUT',
  beforeSend: function(request) {
      request.setRequestHeader('Content-Type', 'application/pdf');
  },
  url: response.url,
  data: 'data to upload into URL',
  success: function() { console.log('Uploaded data successfully.'); }
});

The URL given from the ‘PUT’ action is available for 15 minutes and then it expires. If it expires, you simply send a new ‘PUT’ action to get a new URL.

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domain Returned if the user is not on the root domain.
PROPERTY_REQUIRED version Returned if no version was provided.