Updating a Control Implementation

The Update Control Implementation API allows you to update any control implementation in the OneTrust application. The API is able to update the base and custom information. This API is used when updating a control implementation within OneTrust from another system using an integration.

What parameters are required to update a control implementation?

The control implementation's unique ID is represented by GUID

Step 1: Obtaining the control implementation's unique ID

The POST /control-implementations/pages endpoint can be used to retrieve the list of all control implementations in the application. The list can be filtered to return specific control implementations.

Example Request:

POST /control-implementations/pages
Content-Type: application/json
Authorization: Bearer {OAuth Access Token})

Request Body:

{
  "description": "Defines filters and text used for search.",
  "title": "SearchCriteriaInformation",
  "properties": {
    "fullText": {
      "description": "Full text search terms",
      "type": "string"
    },
    "filters": {
      "description": "Filters for search",
      "type": "array",
      "items": {
        "description": "Defines the information for a single Filter.",
        "title": "FilterInformation",
        "required": [
          "field",
          "value"
        ],
        "type": "object",
        "properties": {
          "value": {
            "description": "Search value",
            "type": "object"
          },
          "operator": {
            "enum": [
              "EQUAL_TO",
              "NOT_EQUAL_TO"
            ],
            "description": "Operator for search",
            "type": "string"
          },
          "field": {
            "description": "Field to search on",
            "type": "string"
          }
        }
      }
    }
  },
  "type": "object"
}

Response Body

{
  "type": "object",
  "required": [
    "control",
    "id",
    "number",
    "organizationId",
    "primaryEntity",
    "status"
  ],
  "properties": {
    "attributes": {
      "type": "object",
      "description": "Implemented Custom Attributes",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object",
          "title": "ControlAttributeValueInformation",
          "description": "Defines the control attribute value details composed of unique identifier, control attribute value and identifier of value used for translation",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid",
              "description": "Attribute option GUID"
            },
            "value": {
              "type": "string",
              "description": "Attribute option value"
            },
            "valueKey": {
              "type": "string",
              "description": "Identifier used for translation of an attribute's option value"
            }
          }
        }
      }
    },
    "control": {
      "type": "object",
      "required": [
        "id",
        "identifier",
        "name",
        "orgGroupId"
      ],
      "title": "ControlExtInformation",
      "description": "Defines the Control information along with Framework information, and Category information",
      "properties": {
        "attributes": {
          "type": "object",
          "description": "Custom attributes for the control. These attributes are custom to the tenant.",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "object",
              "title": "ControlAttributeValueInformation",
              "description": "Defines the control attribute value details composed of unique identifier, control attribute value and identifier of value used for translation",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Attribute option GUID"
                },
                "value": {
                  "type": "string",
                  "description": "Attribute option value"
                },
                "valueKey": {
                  "type": "string",
                  "description": "Identifier used for translation of an attribute's option value"
                }
              }
            }
          }
        },
        "categoryId": {
          "type": "string",
          "format": "uuid",
          "example": "1a2b3c4e-5f6g-7h8i-9j0k-1l2m3n4o5p6q",
          "description": "Identifier (GUID) of the category on the control."
        },
        "categoryName": {
          "type": "string",
          "example": "Privacy",
          "description": "Name of the category on the control."
        },
        "categoryNameKey": {
          "type": "string",
          "example": "ControlName",
          "description": "Identifier used for translation of Category Name"
        },
        "description": {
          "type": "string",
          "example": "Test Controls for Privacy",
          "description": "Control description."
        },
        "frameworkId": {
          "type": "string",
          "format": "uuid",
          "example": "1a2b3c4e-5f6g-7h8i-9j0k-1l2m3n4o5p6q",
          "description": "Identifier (GUID) of the framework on the control."
        },
        "frameworkName": {
          "type": "string",
          "example": "Framework 123",
          "description": "Name of the framework of the control"
        },
        "id": {
          "type": "string",
          "format": "uuid",
          "example": "1a2b3c4e-5f6g-7h8i-9j0k-1l2m3n4o5p6q",
          "description": "The identifier of the control."
        },
        "identifier": {
          "type": "string",
          "example": 123,
          "description": "The identifier of the control."
        },
        "name": {
          "type": "string",
          "example": "Control Name",
          "description": "The name of the control."
        },
        "orgGroupId": {
          "type": "string",
          "format": "uuid",
          "example": "1a2b3c4e-5f6g-7h8i-9j0k-1l2m3n4o5p6q",
          "description": "The identifier of the organization the master control is linked to. In general, this is the top organization in the organization hierarchy."
        }
      }
    },
    "createDt": {
      "type": "string",
      "format": "date-time",
      "example": "2020-11-05T22:01:21.200+00:00",
      "description": "The date the control implementation was created"
    },
    "createdBy": {
      "type": "string",
      "format": "uuid",
      "example": "1a2b3c4e-5f6g-7h8i-9j0k-1l2m3n4o5p6q",
      "description": "The user or operation the control was created by."
    },
    "deadline": {
      "type": "string",
      "format": "date",
      "example": "2020-11-05",
      "description": "The deadline for the control."
    },
    "effectiveness": {
      "type": "string",
      "description": "The effectiveness of the control",
      "enum": [
        "Effective",
        "Ineffective",
        "Planned"
      ]
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "GUID of Control Implementation"
    },
    "lastModifiedBy": {
      "type": "string",
      "format": "uuid",
      "example": "123e4567-e89b-12d3-a456-426614174001",
      "description": "The user or process the control was last modified by (GUID)."
    },
    "lastModifiedDate": {
      "type": "string",
      "format": "date-time",
      "example": "2020-11-05T22:01:21.200+00:0",
      "description": "The date the control was last modified."
    },
    "maturity": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "title": "BasicEntityReference",
      "description": "Defines the UUID, identifier, and name of any Entity",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "example": "123e4567-e89b-12d3-a456-426614174000",
          "description": "Identifier(UUID) of the entity"
        },
        "name": {
          "type": "string",
          "example": "Asset 1234",
          "description": "The name of the entity"
        },
        "nameKey": {
          "type": "string",
          "example": "AssetName",
          "description": "Name of the entity used for translation"
        }
      }
    },
    "note": {
      "type": "string",
      "example": "Testing control value",
      "description": "Notes used for the control. This is free text to contain any additional details which may be needed."
    },
    "number": {
      "type": "integer",
      "format": "int64",
      "example": 123,
      "description": "Numeric identifier for Control Implementation"
    },
    "organizationId": {
      "type": "string",
      "format": "uuid",
      "example": "123e4567-e89b-12d3-a456-426614174000",
      "description": "The identifier (GUID) of the organization implementation"
    },
    "owner": {
      "type": "object",
      "required": [
        "id",
        "name"
      ],
      "title": "BasicEntityReference",
      "description": "Defines the UUID, identifier, and name of any Entity",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "example": "123e4567-e89b-12d3-a456-426614174000",
          "description": "Identifier(UUID) of the entity"
        },
        "name": {
          "type": "string",
          "example": "Asset 1234",
          "description": "The name of the entity"
        },
        "nameKey": {
          "type": "string",
          "example": "AssetName",
          "description": "Name of the entity used for translation"
        }
      }
    },
    "primaryEntity": {
      "type": "object",
      "required": [
        "id",
        "name",
        "type"
      ],
      "title": "ControlEntityInformation",
      "description": "Defines the related Entity information for specific Control Implementation",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "example": "1ab2fff0-cb80-b560-99a1-4a3b527f61f5",
          "description": "The identifier (GUID) of the related entity"
        },
        "name": {
          "type": "string",
          "example": "Asset 305",
          "description": "The name of the entity"
        },
        "organizationId": {
          "type": "string",
          "format": "uuid",
          "example": "1ab2fff0-cb80-b560-99a1-4a3b527f61f5",
          "description": "The identifier (GUID) of the organization which contains the entity"
        },
        "softInherited": {
          "type": "boolean",
          "description": "Indicates if this control is soft-inherited : true or false."
        },
        "type": {
          "type": "string",
          "example": "Risks",
          "description": "The type of the related entity",
          "enum": [
            "Risks",
            "Assets",
            "ProcessingActivities",
            "Vendors",
            "Entities"
          ]
        }
      }
    },
    "status": {
      "type": "string",
      "description": "The status of the control",
      "enum": [
        "Pending",
        "Implemented",
        "NotDoing",
        "Suggested"
      ]
    },
    "suggestion": {
      "type": "string",
      "example": "Suggested",
      "description": "The suggestion status of the control. Used by Athena",
      "enum": [
        "Suggested",
        "Accepted",
        "Rejected"
      ]
    }
  },
  "title": "ControlImplementationDto",
  "description": "Defines the Control Implementation details"
}

Note that a 404 error will return if the user is unauthorized to get the control records or if the GUID is not found. Ensure you have the correct information for the control.

Step 2: Updating the Control Implementation

When all needed changes have been identified, the PUT /control-implementations/{guid} endpoint can be used to update a control implementation in the application.