Data Change Request API

Data change request is a collection of suggested changes for one or several objects.

Users without privileges to update objects, such as customer sales representatives, or users who want changes reviewed before being applied, can suggest changes. These suggested changes accumulate in the data change requests queue for review and approval by users with approval privileges.

Data changes may include any of the following activities:

Add/update/delete an attribute value
Create an entity or relationship
Delete a relationship
Change object fields like tags, roles, startDate, endDate, and so on.

Data Change Request Structure

Table 1. Top Level Fields
Property	Description	Type
`URI`	Unique URI of the data change request	String, URI
`type`	Type of the Data Change Request (only one type can be defined in the configuration)	URI
`createdBy`	Identifier of the user who created this data change request	String
`createdTime`	Time of creation of data change	UTC timestamp, ms
`updatedBy`	Identifier of the user who updated the data change request last time	String
`updatedTime`	Time of last update of the data change request	UTC timestamp, ms
`changes`	Change request items grouped by object URIs	JSON Object
`objectsInfo`	Information about objects participating in this data change request: `type`, `label`, `secondaryLabel`, `startObjectLabel`, `startObjectUri`, `endObjectLabel`, `endObjectUri`, `isExist`. This property exists only if `showObjectsInfo=true` request parameter was specified.	JSON Object
`state`	Current state of the data change request: `AWAITING_REVIEW`, `APPLIED`, `REJECTED`.	String
`externalInfo`	Any external information that can be used in custom Workflow API processes. Inside the `externalInfo` structure, customers can maintain any additional fields they need on DCR.	JSON Object

Table 2. Possible Object Change Item Fields
Property	Description	Type
`attributePath`	Path to an attribute inside the object.	String
`attributeType`	Attribute type URI from metadata.	String
`conflict`	Type of the conflict. This property is present only if the change item has conflicts.	String
`conflictDetails`	Additional details about conflicts.	String
`createdBy`	Identifier of a user created the Data Change Request item.	String
`createdTime`	Time of creation of the Data Change Request item.	UTC timestamp, ms
`crosswalk`	Crosswalk to which the attribute belongs.	JSON Object, Crosswalk
`id`	Unique ID of the change item.	String
`newPinOrIgnoreValue`	The value of "pin" or "ignored" property at the moment when this item was created.	Boolean
`newValue`	Suggested value of an attribute or JSON of an object which is requested to be created.	JSON Object, Attribute or Entity or Relation
`oldValue`	The value of an attribute at the moment when this item was created.	JSON Object, Attribute
`type`	Type of object change item.	String, Object Change Type (see below)
`refAttributeType`	Type of the attribute inside the reference attribute.	String
`refObjectURI`	URI of reference entity or relation which contains the attribute for which some changes are requested (exists only for attribute changes inside reference attributes).	URI

Possible Object Change Types

The following types are supported:

INSERT_ATTRIBUTE
UPDATE_ATTRIBUTE
DELETE_ATTRIBUTE
PIN_ATTRIBUTE
IGNORE_ATTRIBUTE
CREATE_ENTITY
CREATE_RELATIONSHIP
UPDATE_ROLES
UPDATE_TAGS
UPDATE_START_DATE
UPDATE_END_DATE
UPDATE_PROFILE_PIC_BY_URI
UPDATE_PROFILE_PIC_BY_URL
DELETE_RELATIONSHIP

Possible Object Change Types

{
  "uri": "changeRequests/0000Bij",
  "createdBy": "User",
  "createdTime": 1610521042883,
  "updatedBy": "User",
  "updatedTime": 1610521056387,
  "changes": {
    "entities/00005KL": [
      {
        "id": "0000fYX",
        "type": "INSERT_ATTRIBUTE",
        "createdTime": 1610521048011,
        "createdBy": "User",
        "attributePath": "ProductMetrics/2/ExternalID",
        "newValue": {
          "value": "NewId"
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "e1",
          "dataProvider": true
        },
        "attributeType": "configuration/entityTypes/Individual/attributes/ProductMetrics/attributes/ExternalID"
      },
      {
        "id": "0001Hur",
        "type": "UPDATE_ATTRIBUTE",
        "createdTime": 1610521052077,
        "createdBy": "User",
        "attributePath": "Identifiers/5",
        "oldValue": {
          "value": {
            "Type": [
              {
                "value": "Test"
              }
            ],
            "ID": [
              {
                "value": "1111"
              }
            ]
          }
        },
        "newValue": {
          "value": {
            "Type": [
              {
                "value": "NewType"
              }
            ],
            "ID": [
              {
                "value": "2222"
              }
            ]
          }
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "e1",
          "dataProvider": true
        },
        "attributeType": "configuration/entityTypes/Individual/attributes/Identifiers"
      },
      {
        "id": "0001hUP",
        "type": "PIN_ATTRIBUTE",
        "createdTime": 1610521054278,
        "createdBy": "User",
        "attributePath": "FirstName/0",
        "oldValue": {
          "value": "Test",
          "pin": true
        },
        "newPinOrIgnoreValue": false,
        "attributeType": "configuration/entityTypes/Individual/attributes/FirstName"
      },
      {
        "id": "0001585",
        "type": "DELETE_ATTRIBUTE",
        "createdTime": 1610521050933,
        "createdBy": "User",
        "attributePath": "ProductMetrics/2/NumberPatients/4",
        "oldValue": {
          "value": "1111"
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "e1",
          "dataProvider": true
        },
        "attributeType": "configuration/entityTypes/Individual/attributes/ProductMetrics/attributes/NumberPatients"
      },
      {
        "id": "0001uHB",
        "type": "IGNORE_ATTRIBUTE",
        "createdTime": 1610521055333,
        "createdBy": "User",
        "attributePath": "LastName/1",
        "oldValue": {
          "value": "Test",
          "ignored": true
        },
        "newPinOrIgnoreValue": false,
        "attributeType": "configuration/entityTypes/Individual/attributes/LastName"
      },
      {
        "id": "0000sLJ",
        "type": "UPDATE_ATTRIBUTE",
        "createdTime": 1610521049811,
        "createdBy": "User",
        "attributePath": "ProductMetrics/2/Name/3",
        "oldValue": {
          "value": "Initial"
        },
        "newValue": {
          "value": "Changed"
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "e1",
          "dataProvider": true
        },
        "attributeType": "configuration/entityTypes/Individual/attributes/ProductMetrics/attributes/Name"
      },
      {
        "id": "0001Uhd",
        "type": "UPDATE_ATTRIBUTE",
        "createdTime": 1610521053160,
        "createdBy": "User",
        "attributePath": "Address/00006OP",
        "oldValue": {
          "value": {
            "AddressRank": [
              {
                "value": "1"
              }
            ],
            "AddressLine1": [
              {
                "value": "Address1"
              }
            ]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/SomeSource",
                "value": "763127815f9f6ec9e2b9a399db8d18c7"
              }
            ],
            "objectURI": "entities/00009ab"
          },
          "refRelation": {
            "crosswalks": [
              {
                "type": "configuration/sources/SomeSource",
                "value": "r1"
              }
            ],
            "startRefPinned": false,
            "endRefPinned": false,
            "startRefIgnored": false,
            "endRefIgnored": false
          }
        },
        "newValue": {
          "value": {
            "AddressRank": [
              {
                "value": "222"
              }
            ],
            "AddressLine1": [
              {
                "value": "AddressNew"
              }
            ]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/SomeSource",
                "value": "Surrogate"
              }
            ],
            "objectURI": "entities/0006cEr"
          },
          "refRelation": {
            "crosswalks": [
              {
                "type": "configuration/sources/SomeSource",
                "value": "newRel"
              }
            ],
            "startRefPinned": false,
            "endRefPinned": false,
            "startRefIgnored": false,
            "endRefIgnored": false
          }
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "e1",
          "dataProvider": true
        },
        "attributeType": "configuration/entityTypes/Individual/attributes/Address"
      }
    ],
    "relations/00006OP": [
      {
        "id": "000273x",
        "type": "INSERT_ATTRIBUTE",
        "createdTime": 1610521056387,
        "createdBy": "User",
        "attributePath": "AddressRank",
        "newValue": {
          "value": "999"
        },
        "crosswalk": {
          "type": "configuration/sources/SomeSource",
          "value": "r1",
          "dataProvider": true
        },
        "attributeType": "configuration/relationTypes/HasAddress/attributes/AddressRank"
      }
    ]
  },
  "objectsInfo": {
    "entities/00009ab": {
      "type": "configuration/entityTypes/Location",
      "label": "Address1",
      "secondaryLabel": "",
      "isExist": true
    },
    "entities/00005KL": {
      "type": "configuration/entityTypes/Individual",
      "label": "Test",
      "secondaryLabel": "Address1",
      "isExist": true
    },
    "entities/0006cEr": {
      "type": "configuration/entityTypes/Location",
      "label": "AddressNew",
      "secondaryLabel": "",
      "isExist": false
    },
    "relations/00006OP": {
      "type": "configuration/relationTypes/HasAddress",
      "startObjectUri": "entities/00005KL",
      "startObjectLabel": "Test",
      "endObjectUri": "entities/00009ab",
      "endObjectLabel": "Address1",
      "isExist": true
    }
  },
  "type": "configuration/changeRequestTypes/default",
  "state": "AWAITING_REVIEW"
}

DCR Security

Not all users can create, review, apply or reject data change requests. To be able to create a data change request, users must have:

READ privilege for objects for which data change request will be created;
INITIATE_CHANGE_REQUEST privilege for the whole object or at least for its attributes for which change requests will be created.

All users can view their own data change requests, but in order to be able to view data change requests from other users, users must have ACCEPT_CHANGE_REQUEST privilege for all objects in data change requests.

For applying or rejecting a data change request, users must have ACCEPT_CHANGE_REQUEST privilege for all objects in the data change request.

Note: Users with ROLE_ADMIN or ROLE_ADMIN_TENANT_* don't need ACCEPT_CHANGE_REQUEST and/or INITIATE_CHANGE_REQUEST privileges. Such users have full control over DCRs.

In order to apply a change request the users must also have READ, CREATE, UPDATE, DELETE, and MERGE privileges on the changed objects and depending on the change type, or, if the applyDcrWithoutPermissions flag is set to true, just a READ privilege. For more details, see topic Permissions.

Unify and manage your data

Data Change Request API

Data Change Request Structure

Possible Object Change Types

Possible Object Change Types

DCR Security

Footer