C Appendix: Data Privacy Installation
The services that are part of data privacy command line tool are executable though a command line executable JAR file RetailAppsDataPrivTool.jar
Setting up the Java Development Kit (JDK)
Java 1.8 is a prerequisite to install and test the data privacy command line tool. This section contains instructions on how to set up the Java Development Kit (JDK).
Download and Install Java 8
Download the latest 64-bit version of Java SE Development Kit 8. Install in a location on your machine. Ensure that the installation folder name does not contain any whitespaces (example: Program Files)
Define Environment Variables for JDK
To effectively use the JDK on your workstation you need to define environment variables on your system.
Testing Your JDK Installation
-
Start a new command line window by selecting Start ->Run -> Open -> type
cmd.exe. -
Go to the root directory by typing:
cd c:\ <enter>
-
Run the Java compiler and query its version by typing:
javac -version
The command should return with the Java version information similar to shown below. Make sure it matches with the JDK version you just installed.
Data Privacy Command Line Tool
Download the following RA/RI files:
-
RetailAppsDataPrivTool.jar
-
ContextOverride.properties
-
DATAPRIV-Global.xml
-
DATAPRIV-ValidateForget.xml
-
DATAPRIV-Get.xml
-
DATAPRIV-Forget.xml
-
Create a folder DataPrivacy and copy the RetailAppsDataPrivTool.jar into this folder.
-
Create a folder RIDataPrivConfig under the DataPrivacy folder and copy DATAPRIV-Global.xml, DATAPRIV-ValidateForget.xml, DATAPRIV-Get.xml and DATAPRIV-Forget.xml into this folder.
Configure the Configuration Files
Perform the following changes to the specified configuration files:
-
ContextOverride.properties - Contains details of the connection string to be used in case of using oracle wallet. This needs to be modified to enter the correct database information.
-
The JDBC URL must comply with the following format to reference Oracle Wallet credentials at runtime:
-
A forward slash "/" must be specified BEFORE the "@" character. This instructs the Oracle database driver to be aware of Oracle Wallet aliases.
-
The identifiers following the "@" character must be registered as an alias in the Oracle Wallet. The wallet creation and configuration steps is explained in the next section.
-
Datasoure string format - datasource-url=jdbc:oracle:thin:/@hostname:port/SID e.g. - datasource-url=jdbc:oracle:thin:/@myhost:1521/mydb
-
-
DATAPRIV-Global.xml - Contains DB connection details as well as details of customer-id-format. No changes necessary for this file.
-
DATAPRIV-Get.xml - Contains the SQL query or function to perform the right to access. No changes necessary for this file.
-
DATAPRIV-Forget.xml - Contains the SQL query or function to perform the right to forget. No changes necessary for this file.
-
DATAPRIV-ValidateForget.xml - Contains validations to perform prior to right to forget. No changes necessary for this file.
Creating and Configuring Oracle Wallet
Data privacy command line tool uses oracle wallet to securely store the database credentials. The wallet can be created using the RetailAppsDataPrivTool.jar.
Perform the following steps to create and configure the Oracle wallet for the data privacy command line tool.
-
Create an empty wallet file in a DataPrivacy directory by running the below command in a command prompt (cmd) in DataPrivacy folder.
java -classpath RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl <wallet directory> -create
For example:
java -classpath ./RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl ./tmp_wallet -create
You are prompted for a password. This will be the password to manage the contents of the wallet files. Note this password as it will be needed in succeeding commands against the wallet files.
-
Add the database credentials into the wallet by running the below command in the command prompt (cmd) in the DataPrivacy folder. This will prompt to enter the password you created in step 1.
java -classpath RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl <wallet directory> -createCredential <db connect string> <db user> <db password><db connect string> - is the database connection string included in a JDBC connection url in the ContextOverride.properties.xml. It is the part of the JDBC url after the "@" character.
It is specified using the format: <hostname>:<port>/<SID>
Example:
myhost:1521/mydb <db user> - DB user to connect to the RI DB. <db password> - password to connect to the RI DB.
For example:
java -classpath ./RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl ./tmp_wallet -createCredential myhost:1521/mydb rmsuser password
-
Verify the database credentials in the wallet by running the following command in the command prompt (cmd).
java -classpath RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl <wallet directory> -listCredentialFor example:
java -classpath ./RetailAppsDataPrivTool.jar oracle.security.pki.OracleSecretStoreTextUI -wrl ./tmp_wallet -listCredential
Make sure the credential information shown by the command is as expected.
Using the Data Privacy Command Line Tool
The Private Data Services command line tool is an executable JAR file that uses the "java -jar" option:
java -DContextOverride.properties=<Context Override Properties file>
-Duse.jdbc.oracle.wallet=true
-Doracle.net.wallet_location=<Oracle wallet directory>
-Dconfig.xml.dir=<configration files directory>
-Ddatapriv.action=<action>
-Dcustomer.id=<query parameters for the tool>
-Did.type=<table_used>
-Dinvoked.by=<user ID>
-Doutput.file.dir=<output file directory>
-jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
The parameters are given to the command line via system property JVM arguments (-D options).
Understanding the Command Line Parameters
Table C-1 Command Line Parameters
| System Property/Parameter | Required | Description |
|---|---|---|
|
ContextOverride.properties |
Always |
The path to a Java properties file that will contain the connection details of the database the data privacy command line tool will connect to. Refer to Configure the Configuration Files for additional details. |
|
use.jdbc.oracle.wallet |
Always |
Set to true to use Oracle Wallet files as a source for database credentials. Refer to Creating and Configuring Oracle Wallet for additional details. |
|
oracle.net.wallet_location |
Always |
The path to the Oracle Wallet directory. Refer to Creating and Configuring Oracle Wallet for additional details. |
|
config.xml.dir |
Always |
The directory that contains the DATAPRIV configuration XML files. |
|
datapriv.action |
Always |
The data privacy action to be performed: Valid values:
|
|
customer.id |
Always |
The input parameters to the query/update the personal data. |
|
id.type |
Always |
The table for which the data privacy action will be performed. |
|
invoked.by |
Always |
The ID of the user calling the command line tool (for audit purposes). |
|
output.file.dir |
No |
The output files directory. Default is the user's home directory. |
Command Query
Format for datapriv.action=access (Right to Access)
example:
Employee
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=access -Dcustomer.id="-1" -Did.type=employee -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Supplier
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=access -Dcustomer.id="123" -Did.type=supplier -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Customer
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=access -Dcustomer.id="-1" -Did.type=customerRecord -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Customer.id format for datapriv.action= forget (Right to Forget)
Query example:
Employee
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=forget -Dcustomer.id="-1" -Did.type=employee -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Supplier
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=forget -Dcustomer.id="123" -Did.type=supplier -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Customer
java -DContextOverride.properties=D:\EU-GDPR\RI\ContextOverride.properties -Duse.jdbc.oracle.wallet=true -Doracle.net.wallet_location=./tmp_wallet -Dconfig.xml.dir=D:\EU-GDPR\RI\RIDataPrivConfig -Ddatapriv.action=forget -Dcustomer.id="-1" -Did.type= customerRecord -Dinvoked.by=user -Doutput.file.dir=D:\EU-GDPR\RI\out -jar RetailAppsDataPrivServices-7.0.1-RetailAppsDataPrivTool.jar
Data Privacy Services REST Endpoints
Resource URL
http://<server>:<port>/RetailAppsDataPrivServicesRESTApp/rest/privatedata
Required Request Headers
Table C-2 Required Request Header List
| Header | Values |
|---|---|
|
Accept |
application/json or application/xml Refer to endpoint documentation below to see what the endpoint requires. |
|
Authorization |
Base 64 encoded authorization string representation of the user credentials. |
List of Resource Endpoints
Table C-3 List of Resource Endpoints
| Operation | Path | Method | Accept | Description |
|---|---|---|---|---|
|
Access customer's information (JSON) |
/privatedata/{id_type} |
GET |
application/json |
Returns customer information in the system in JSON formats Path Parameters
Query Parameters
Input Payloads
Response Codes and Error Messages
Success Payloads
|
|
Error Payload
Examples GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/customer?customer_id=12::12::12 GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/raf?customer_id=benny_anderson::benny_anderson@acme.com GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/raf?customer_id=12::12::12&jsonFormat=full |
||||
|
Access customer's information (HTML) |
/privatedata/{id_type} |
GET |
application/XML |
Returns customer information in the system in HTML format. Same parameters as getting customer information in JSON format (see above) except that the "jsonFormat" query paramete is not applicable. Note that the Accept value MUST be application/XML to access this endpoint. The Output Payload generated in HTML format instead of JSON. See Access Output Formats for details. |
|
Remove customer's information |
/privatedata/{id_type} |
DELETE |
application/json |
Removes the customer from the system. Path Parameters
Query Parameters
Input Payloads
Response Codes and Error Messages
Error Payload
Examples: DELETE http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/customer?customer_id=12::12::12 |
|
Validate if customer's information can be removed |
/privatedata/{id_type}/validateForget |
GET |
application/json |
Validates whether a customer can be removed from the system. Path Parameters
Query Parameters
Input Payloads
Response Codes and Error Messages
Error Payload
Examples: GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/customer/validateForget?customer_id=12::12::12 |
|
Get query group types for Access requests |
/privatedata/config/access |
GET |
application/json |
Returns the valid ID types that can be used in access calls. Path Parameters
Query Parameters
Input Payloads
Response Codes and Error Messages
Success Payloads {
"types": [
"raf",
"supplier",
"customer"
]
} |
|
Get query group type information for access requests |
/privatedata/config/access/{id_type} |
GET |
application/json |
Returns details of the id type to be used for access requests. Path Parameters
Query Parameters
Input Payloads
Response Codes and Error Messages
Invalid input type
Success Payloads {
"customerIdFormat": "{%customerId%}::{%divisionId%}::{%groupId%}",
"type": "customer"
}Error Payload
Examples: GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/config/access/customer GET http://127.0.0.1:7101/RetailAppsDataPrivServicesRESTApp/rest/privatedata/config/access/supplier |
|
Get query group types for Forget Access requests |
/privatedata/config/forget |
GET |
application/json |
Similar to "Get query group types for Access requests" but retrieves types from the Forget configuration xml |
|
Get query group type information for Forget requests |
/privatedata/config/forget/{id_type} |
GET |
application/json |
Similar to "Get query group type information for access requests" but retrieves type information from the Forget configuration xml |
|
Get query group types for Validate Forget Access requests |
/privatedata/config/validateForget |
GET |
application/json |
Similar to "Get query group types for Access requests" but retrieves types from the Validate Forget configuration xml |
|
Get query group type information for Validate Forget requests |
/privatedata/config/validateForget/{id_type} |
GET |
application/json |
Similar to "Get query group type information for access requests" but retrieves types from the Validate Forget configuration xml |
Access Output Formats
The following output formats are supported by the REST endpoint for Access requests:
Table C-4 Access Output Format List
| Format | Description |
|---|---|
|
Concise JSON (default) |
Human readable JSON format. Concise but cannot be parsed into a generic stucture at runtime. |
|
Full JSON |
Full JSON format that can be parsed as a generic QueryGroupResult object. Ideal for importing data into the system (a future functionality) |
|
Human Readable HTML |
Human readable HTML format. |
Concise JSON
{
"Customer Information": {
"Basic Information": {
"list": [
[
{
"Customer ID": "12344",
"First Name": "Joe",
"Middle Name": "Steven",
"LastName": "Smith",
"Division": "Division 4444",
"Group": "Group 5555"
},
{
"Customer ID": "12344",
"First Name": "Joseph",
"Middle Name": "Steven",
"LastName": "Smith",
"Division": "Legacy Division 89-4444",
"Group": "Legacy Group 76-5555"
}
]
],
"Phone Numbers": {
"list": [
[
{
"Home Phone": "123-123-1234",
"Mobile Phone": "123-123-1234"
}
]
]
},
"Addresses": {
"list": [
[
{
"Address Line 1": "123 Stoney Lake Road",
"Address Line 2": "Apartment 2C30",
"City": "Toledo",
"State": "Ohio",
"Postal Code": "85225",
"Country": "United States"
},
{
"Address Line 1": "444 Hill Trail Road",
"Address Line 2": "null",
"City": "Cleveland",
"State": "Ohio",
"Postal Code": "44444",
"Country": "United States"
},
{
"Address Line 1": "123 Lyndale Avenue",
"Address Line 2": "Apartment 5B",
"City": "Minneapolis",
"State": "Minnesota",
"Postal Code": "554333",
"Country": "United States"
}
]
]
},
"Email Addresses": {
"list": [
[
{
"Email": "jssmith@gmail.com"
},
{
"Email": "j.s.smith@yahoo.com"
},
{
"Email": "joe.steven.smith@aol.com"
},
{
"Email": "joe.s.smith@outlook.com"
},
{
"Email": "the.smithster@yahoo.com"
}
]
]
}
}
}
}
Full JSON
[
{
"name": "Customer Information",
"type": "customer",
"showAsList": false,
"queryResults": [],
"subgroups": [
{
"name": "Basic Information",
"type": null,
"showAsList": false,
"queryResults": [
{
"rows": [
{
"attributes": [
{
"name": "Customer ID",
"value": "12344"
},
{
"name": "First Name",
"value": "Joe"
},
{
"name": "Middle Name",
"value": "Steven"
},
{
"name": "LastName",
"value": "Smith"
},
{
"name": "Division",
"value": "Division 444"
},
{
"name": "Group",
"value": "Group 5555"
}
]
},
{
"attributes": [
{
"name": "Customer ID",
"value": "12344"
},
{
"name": "First Name",
"value": "Joseph"
},
{
"name": "Middle Name",
"value": "Steven"
},
{
"name": "LastName",
"value": "Smith"
},
{
"name": "Division",
"value": "Legacy Division 89-444"
},
{
"name": "Group",
"value": "Legacy Group 76-5555"
}
]
}
],
"rowLimitReached": false,
"maxRowLimit": 5
}
],
"subgroups": [
{
"name": "Phone Numbers",
"type": null,
"showAsList": true,
"queryResults": [
{
"rows": [
{
"attributes": [
{
"name": "Home Phone",
"value": "123-123-1234"
},
{
"name": "Mobile Phone",
"value": "123-123-1234"
}
]
}
],
"rowLimitReached": false,
"maxRowLimit": 5
}
], "subgroups": [] }, { "name": "Addresses", "type": null, "showAsList": true, "queryResults": [ { "rows": [ { "attributes": [ { "name": "Address Line 1", "value": "123 Stoney Lake Road" }, { "name": "Address Line 2", "value": "Apartment 2C30" }, { "name": "City", "value": "Toledo" }, { "name": "State", "value": "Ohio" }, { "name": "Postal Code", "value": "85225" }, { "name": "Country", "value": "United States" } ] }, { "attributes": [ { "name": "Address Line 1",
"value": "444 Hill Trail Road" }, { "name": "Address Line 2", "value": null }, { "name": "City", "value": "Cleveland" }, { "name": "State", "value": "Ohio" }, { "name": "Postal Code", "value": "44444" }, { "name": "Country", "value": "United States" } ] }, { "attributes": [ { "name": "Address Line 1", "value": "123 Lyndale Avenue" }, { "name": "Address Line 2", "value": "Apartment 5B" }, { "name": "City", "value": "Minneapolis" }, { "name":
"State", "value": "Minnesota" }, { "name": "Postal Code", "value": "554333" }, { "name": "Country", "value": "United States" } ] } ], "rowLimitReached": false, "maxRowLimit": 5 } ], "subgroups": [] }, { "name": "Email Addresses", "type": null, "showAsList": true, "queryResults": [ { "rows": [ { "attributes": [ { "name": "Email", "value": "jssmith@gmail.com" } ] }, { "attributes": [ { "name": "Email", "value": "j.s.smith@yahoo.com" } ] }, { "attributes": [
{ "name": "Email", "value": "joe.steven.smith@aol.com" } ] }, { "attributes": [ { "name": "Email", "value": "joe.s.smith@outlook.com" } ] }, { "attributes": [ { "name": "Email", "value": "the.smithster@yahoo.com" } ] } ], "rowLimitReached": true, "maxRowLimit": 5 } ], "subgroups": [] } ] } ] }]
Error Payloads
For Bad Request and Precondition Failure Errors (400, 412)
{
"errors": [
"Invalid value for query parameter, jsonFormat. Expecting 'concise' or 'full' but received 'saf'."
]
}
For Internal Server Errors (500):
{
"errors": [
"ORA-123: SQL not properly terminated"
],
"stackTrace": [
"sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)",
::
]
}