Controls
Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full lifecycle of a control, including its query, notification settings, and execution schedule.
Returns a paginated list of controls, including the full details of each control.
By default, results are sorted alphabetically by name. Filtering is not currently supported.
This API requires Basic HTTP authentication.
The number of items to skip before returning results. Used for pagination. The default value is 0.
0Example: 0The maximum number of items to return. The default value is 50. The maximum value is 1000.
50Example: 10Response for listing controls.
A list of controls.
The request is not valid.
GET /rest/controlManagement/v1/controls HTTP/1.1
Authorization: Basic username:password
Accept: */*
{
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Data Encryption Control",
"description": "This control ensures that data is encrypted at rest.",
"domainId": "123e4567-e89b-12d3-a456-426614174001",
"severity": "Medium",
"controlType": "Preventative",
"owners": [
"123e4567-e89b-12d3-a456-426614174002"
],
"enabled": true
}
]
}Creates a new control with the specified properties. The control is disabled by default and must be enabled separately once a valid query has been configured.
Requires Activate and Run or Add Asset on the target domain. A caller who cannot view the domain, or holds neither right on it, receives 403 Forbidden.
This API requires Basic HTTP authentication.
Schema for creating a new control.
The name of the control.
Data Encryption ControlA brief description of the control.
This control ensures that data is encrypted at rest.The category of the control.
Data QualityThe ID of the domain to which the control belongs.
123e4567-e89b-12d3-a456-426614174000The owners of the control. Can be users or user groups. Send an empty array to clear all owners.
123e4567-e89b-12d3-a456-426614174000The severity level of the control.
Possible values are Low, Medium, and High.
MediumThe type of control.
Possible values are Preventative, Detective, Corrective, and Directive.
PreventativeDetails the specific actions or steps required to address and resolve a control failure.
Ensure all data is encrypted using AES-256.Confirm the control was created successfully.
The request is not valid.
When the control query is the reason, the query field carries it back with the issues found.
The user is forbidden to execute the requested action.
POST /rest/controlManagement/v1/controls HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 688
{
"name": "Data Encryption Control",
"description": "This control ensures that data is encrypted at rest.",
"category": "Data Quality",
"domainId": "123e4567-e89b-12d3-a456-426614174000",
"owners": [
"123e4567-e89b-12d3-a456-426614174000"
],
"severity": "Medium",
"controlType": "Preventative",
"resolution": "Ensure all data is encrypted using AES-256.",
"executionSchedule": {
"frequency": "Daily",
"timeOfDay": "12:00:00Z",
"daysOfWeek": [
"Monday",
"Tuesday"
]
},
"query": {
"version": 1,
"assetSelector": {
"targetType": {
"publicId": "Column",
"type": "AssetType"
}
}
},
"notificationSettings": {
"message": "Message rich text example.",
"recipients": [
{
"type": "User",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe"
}
]
}
}{
"id": "123e4567-e89b-12d3-a456-426614174000"
}Returns the full details of the control with the specified ID.
This API requires Basic HTTP authentication.
The unique identifier of the control.
Response for retrieving a control.
Schema for a control.
The ID of the control asset.
123e4567-e89b-12d3-a456-426614174000The name of the control.
Data Encryption ControlA brief description of the control.
This control ensures that data is encrypted at rest.The category of the control.
Data QualityThe ID of the domain to which the control belongs.
123e4567-e89b-12d3-a456-426614174000The severity level of the control.
Possible values are Low, Medium, and High.
MediumThe type of control.
Possible values are Preventative, Detective, Corrective, and Directive.
PreventativeThe owners of the control. Can be users or user groups. Send an empty array to clear all owners.
123e4567-e89b-12d3-a456-426614174000If the control is enabled or not.
Details the specific actions or steps required to address and resolve a control failure.
Ensure all data is encrypted using AES-256.Whether the control's query is currently invalid.
This value is read-only: it reflects the last determination made for this control and cannot be set directly through this resource.
falseThe resource was not found.
GET /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Data Encryption Control",
"description": "This control ensures that data is encrypted at rest.",
"category": "Data Quality",
"domainId": "123e4567-e89b-12d3-a456-426614174000",
"severity": "Medium",
"controlType": "Preventative",
"owners": [
"123e4567-e89b-12d3-a456-426614174000"
],
"enabled": true,
"resolution": "Ensure all data is encrypted using AES-256.",
"query": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"queryInvalid": false,
"executionSchedule": {
"frequency": "Daily",
"timeOfDay": "12:00:00Z",
"daysOfWeek": [
"Monday",
"Tuesday"
]
},
"notificationSettings": {
"message": "Message rich text example.",
"recipients": [
{
"type": "User",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe"
}
]
}
}Deletes the control with the specified ID. If the control does not exist, the response is still 204 No Content.
This API requires Basic HTTP authentication.
The unique identifier of the control.
The control was either deleted successfully or does not exist.
No content
The user is forbidden to execute the requested action.
DELETE /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Accept: */*
No content
Updates a control. This method allows you to override specified fields of a control. All null values will be ignored.
Requires Activate and Run on the control. Supplying a domainId that differs from the control's current domain moves the control, and additionally requires Activate and Run or Add Asset on the target domain. A caller missing either right receives 403 Forbidden.
This API requires Basic HTTP authentication.
The unique identifier of the control.
Schema for updating a control
The name of the control.
Data Encryption ControlA brief description of the control.
This control ensures that data is encrypted at rest.The category of the control.
Data QualityThe ID of the domain to which the control belongs.
123e4567-e89b-12d3-a456-426614174000The severity level of the control.
Possible values are Low, Medium, and High.
MediumThe type of control.
Possible values are Preventative, Detective, Corrective, and Directive.
PreventativeThe owners of the control. Can be users or user groups. Send an empty array to clear all owners.
123e4567-e89b-12d3-a456-426614174000Details the specific actions or steps required to address and resolve a control failure.
Ensure all data is encrypted using AES-256.Response for retrieving a control.
Schema for a control.
The ID of the control asset.
123e4567-e89b-12d3-a456-426614174000The name of the control.
Data Encryption ControlA brief description of the control.
This control ensures that data is encrypted at rest.The category of the control.
Data QualityThe ID of the domain to which the control belongs.
123e4567-e89b-12d3-a456-426614174000The severity level of the control.
Possible values are Low, Medium, and High.
MediumThe type of control.
Possible values are Preventative, Detective, Corrective, and Directive.
PreventativeThe owners of the control. Can be users or user groups. Send an empty array to clear all owners.
123e4567-e89b-12d3-a456-426614174000If the control is enabled or not.
Details the specific actions or steps required to address and resolve a control failure.
Ensure all data is encrypted using AES-256.Whether the control's query is currently invalid.
This value is read-only: it reflects the last determination made for this control and cannot be set directly through this resource.
falseThe request is not valid.
When the control query is the reason, the query field carries it back with the issues found.
The user is forbidden to execute the requested action.
The resource was not found.
PATCH /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 688
{
"name": "Data Encryption Control",
"description": "This control ensures that data is encrypted at rest.",
"category": "Data Quality",
"domainId": "123e4567-e89b-12d3-a456-426614174000",
"severity": "Medium",
"controlType": "Preventative",
"owners": [
"123e4567-e89b-12d3-a456-426614174000"
],
"resolution": "Ensure all data is encrypted using AES-256.",
"query": {
"version": 1,
"assetSelector": {
"targetType": {
"publicId": "Column",
"type": "AssetType"
}
}
},
"executionSchedule": {
"frequency": "Daily",
"timeOfDay": "12:00:00Z",
"daysOfWeek": [
"Monday",
"Tuesday"
]
},
"notificationSettings": {
"message": "Message rich text example.",
"recipients": [
{
"type": "User",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe"
}
]
}
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Data Encryption Control",
"description": "This control ensures that data is encrypted at rest.",
"category": "Data Quality",
"domainId": "123e4567-e89b-12d3-a456-426614174000",
"severity": "Medium",
"controlType": "Preventative",
"owners": [
"123e4567-e89b-12d3-a456-426614174000"
],
"enabled": true,
"resolution": "Ensure all data is encrypted using AES-256.",
"query": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"queryInvalid": false,
"executionSchedule": {
"frequency": "Daily",
"timeOfDay": "12:00:00Z",
"daysOfWeek": [
"Monday",
"Tuesday"
]
},
"notificationSettings": {
"message": "Message rich text example.",
"recipients": [
{
"type": "User",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe"
}
]
}
}Returns the requirements (if any) defined for a given Control.
The requirements of a Control are AssetFilter objects defined in the query of the Control and that define isRequirement as true.
This API requires Basic HTTP authentication.
The unique identifier of the control.
The requirements of a control.
An array of requirements.
The ID of a requirement is a 17 characters string that combines the versionHash of the parent ControlQuery
with the versionHash of the AssetFilter marked as a requirement.
The 2 hashes are separated by a - character.
For example:
- If the
versionHashof theControlQueryisba7816bf - If the
versionHashof theFilteriscd294a01 - The identifier of the requirement is
ba7816bf-cd294a01
ba7816bf-cd294a01The resource was not found.
GET /rest/controlManagement/v1/controls/{controlId}/requirements HTTP/1.1
Authorization: Basic username:password
Accept: */*
[
{
"id": "ba7816bf-cd294a01",
"targetType": {
"type": "AssetType",
"publicId": "Column",
"name": "Column",
"symbolData": {
"acronymCode": "COL",
"color": "#0072BC",
"iconCode": "uf-additional-icon-document_newspaper",
"symbolType": "ICON_CODE"
}
},
"filter": {
"predicates": [
{
"operandType": "status",
"operator": "equals",
"value": [
{
"id": "1360b0a7-9497-479f-8079-09358c259b8a",
"name": "Approved",
"type": "Status"
}
]
}
]
}
},
{
"id": "ba7816bf-cd294a02",
"targetType": {
"type": "AssetType",
"publicId": "Table",
"name": "Table",
"symbolData": {
"acronymCode": "TAB",
"color": "#0072BC",
"iconCode": "uf-additional-icon-document_newspaper",
"symbolType": "ICON_CODE"
}
},
"filter": {
"predicates": [
{
"operandType": "status",
"operator": "equals",
"value": [
{
"id": "1360b0a7-9497-479f-8079-09358c259b8a",
"name": "Approved",
"type": "Status"
}
]
}
]
}
}
]Enables a control by setting its enabled status to true.
Before you can enable a control, the following conditions must be met:
The control must have a control query defined.
The control query must be valid.
All the mandatory properties of the control have been defined, such as
nameandseverity.
This API requires Basic HTTP authentication.
The unique identifier of the control.
The control was enabled successfully.
No content
The request is not valid.
The user is forbidden to execute the requested action.
The resource was not found.
POST /rest/controlManagement/v1/controls/{controlId}/enable HTTP/1.1
Authorization: Basic username:password
Accept: */*
No content
Disables a control by setting its enabled status to false.
This API requires Basic HTTP authentication.
The unique identifier of the control.
The control was disabled successfully.
No content
The request is not valid.
The user is forbidden to execute the requested action.
The resource was not found.
POST /rest/controlManagement/v1/controls/{controlId}/disable HTTP/1.1
Authorization: Basic username:password
Accept: */*
No content
Last updated
Was this helpful?