Data Retention Policy REST API

By making an HTTP GET request to the following URL relative to IQ Server's base URL the data retention policies for a given organization can be retrieved:

GET /api/v2/dataRetentionPolicies/organizations/{organizationId}

You use the Organizations REST API to locate the organizationId for an organization.

Assuming a local installation of IQ Server with its default configuration, the following example using the cURL tool queries the retention policies for the root organization:

curl -u admin:admin123 http://localhost:8070/api/v2/dataRetentionPolicies/organizations/ROOT_ORGANIZATION_ID

Again, assuming the default configuration, the above request would yield this JSON response payload (formatted here for readability):

{
  "applicationReports": {
    "stages": {
      "develop": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "build": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "stage-release": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      },
      "release": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "10 years"
      },
      "operate": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "10 years"
      },
      "continuous-monitoring": {
        "inheritPolicy": false,
        "enablePurging": true,
        "maxAge": "3 months"
      }
    }
  },
  "successMetrics": {
    "inheritPolicy": false,
    "enablePurging": true,
    "maxAge": "1 year"
  }
}

For application reports, each stage in the application lifecycle (develop, build, etc.) has its own retention policy. A notable exception are application reports that were created by continuous monitoring: They are not subject to the retention policy of whatever stage is being monitored but have their own retention policy under the key continuous-monitoring.

Note that the response lists only those stages that the installed product license enables. So you might see fewer entries with your IQ Server than shown in the above example.

A single retention policy for the application reports consists of these fields:

The retention policy for Success Metrics consists mostly of the same fields as those for application reports:

A HTTP PUT request to the same URL when reading the current configuration is used to change the retention policies:

PUT /api/v2/dataRetentionPolicies/organizations/{organizationId}

The request needs to be accompanied by a JSON payload that has generally the same format as described above. It is however allowed to omit all but one stage from the stages map to selectively update only the retention policy for a few stages or to only specify successMetrics to update the retention policy for Success Metrics and not application reports.

The next example would update the retention policy of the root organization regarding application reports for the build stage:

curl -u admin:admin123 -H "Content-Type: application/json" -X PUT -d '{"applicationReports": {"stages": {"build": {"enablePurging": true, "maxAge": "2 weeks", "maxCount": 100}}}}' http://localhost:8070/api/v2/dataRetentionPolicies/organizations/ROOT_ORGANIZATION_ID

Note that when enablePurging is true, at least one purge criteria, maxAge or maxCount, needs to be specified.

If the request body is malformed, no changes to the retention policies are carried out and the status code 400 ("Bad Request") is sent back.

To optimize resource usage for this REST API, IQ Server has a preset limit of purging 5000 reports in one call. If your reports to be purged exceed 5000, and were not purged before, you will have to issue multiple calls to this REST API, to reduce the reports below or equal to the maxCount field setting.

IQ Server will automatically apply the maxCount field setting for subsequent purges.