Sample ForgetMe client

The ForgetMe service offers a simple Python client that you may download and use to request data removal. The client runs on Linux or Windows platforms. To run it, you need:

  • Python 3.6 or later.
  • The generated Python stubs from gRPC setup.
  • The Python requests module. Install it with pip install requests
  • The user ID of the data you wish to delete, from a Mix runtime request.
  • Your client ID, secret, and asr.forgetme scope from Prerequisites.
  • The Python client files: sample-forgetme-client.zip.

Download the zip file and extract its files into the directory above nuance, which contains your proto files and Python stubs.

For example, on Linux:

$ unzip sample-forgetme-python-client.zip
Archive:  sample-forgetme-python-client.zip
  inflating: fabric-forgetme-client.py
  inflating: fabric-forgetme-flow.py
  inflating: util.py

$ pip install requests

These are the resulting client files, above the nuance directory holding your Python stubs:

├── fabric-forgetme-client.py
├── fabric-forgetme-flow.py
├── init.py
└── nuance
    ├── fabric
    │   └── forgetme  
    │       ├── forget_pb2_grpc.py  
    │       └── forgetme_pb2.py  
    └── rpc
        ├── error_details_pb2.py
        ├── status_code_pb2.py
        └── status_pb2.py 

Get help

For a quick check that the client is working, and to see the arguments it accepts, run it using the help option.

See the results below and notice:

  • -f or --files: An input file or files. By default the file is fabric-forgetme-flow.py, as provided in the download package.

  • -s or --serverUrl: The URL of the ForgetMe service, log.api.nuance.com.

  • Authorization arguments: Include --oauthURL, --clientID, and --clientSecret. See Prerequisites. The oauthURL is https://auth.crt.nuance.com/oauth2/token.

  • --oauthScope: The default is log.forgetme.

  • --secure: Always include this argument when calling the Mix environment.

  • rootCerts, privateKey, and certChain: Ignore these arguments in the Mix environment.

  • --forgetId: The user or session ID of the events to be deleted. This argument overrides request.forget_id in fabric-forgetme-flow.py.

  • --forgetType: Whether the forget ID is a user or session ID. This argument overrides request.forget_type in fabric-forgetme-flow.py.

$ python3 fabric-forgetme-client.py --help
usage: fabric-forgetme-client.py [-options]

options:
  -h, --help                     Show this help message and exit
  -f file [file ...], --files file [file ...]
                                 List of flow files to execute sequentially,
                                 default='fabric-forgetme-flow.py'
  -l lvl, --loglevel lvl         Log level: fatal, error, warn, default=info, debug
  -L [fn], --logfile [fn]        log to file, default fn=fmsgcli-{datetimestamp}.log
  -q, --quiet                    Disable console logging
  -p, --parallel                 Run each flow in a separate thread
  -i [num], --iterations [num]   Number of times to run the list of files, default=1
  -s [url], --serverUrl [url]    ForgetMe service URL, default=localhost:9080
  -b, --disableBasicAuth         Basic auth is required for Mix-generated credentials,
                                 disable for others
  --oauthURL [url]               OAuth 2.0 URL
  --clientID [url]               OAuth 2.0 Client ID
  --clientSecret [url]           OAuth 2.0 Client Secret
  --oauthScope [url]             OAuth 2.0 Scope, default=log.forgetme
  --secure                       Connect to the server using a secure gRPC channel
  --rootCerts [file]             Root certificates when using a secure gRPC channel
  --privateKey [file]            Certificate private key when using a secure gRPC
                                 channel
  --certChain [file]             Certificate chain when using a secure gRPC channel
  --jaeger [addr]                Send UDP opentrace spans, default
                                 addr=udp://localhost:6831
  --maxReceiveSizeMB [megabytes] Maximum length of gRPC server response in megabytes,
                                 default=50 MB
  --forgetId [value]             User or session ID from original request. If provided
                                 overrides request.forget_id in flow file
  --forgetType [value]           Forget type: USER or SESSION. Default is USER. If
                                 provided overrides request.forget_type in flow file

Set credentials

The client uses your Mix credentials to obtain an token, which authorizes the client to call the ForgetMe service. You may pass the credentials directly to the client or set them first as environment variables. When entering your client ID, replace colons (:) with %3A, for example, appID%3ANMDPTRIAL_your_name_etc.

On Linux:

CLIENT_ID=<Mix client ID, replace colons with %3A>
CLIENT_SECRET=<Mix client secret>

On Windows:

set CLIENT_ID=<Mix client ID, replace colons with %3A>
set CLIENT_SECRET=<Mix client secret>

Run client for user ID

This scenario requests the deletion of log data associated with a user ID in this previous ASRaaS request:

# Include a user_id in RecognitionInitMessage   
init = RecognitionInitMessage(   
    parameters = RecognitionParameters( ... ), 
    user_id = 'eric@aardvark.com'
)

Edit input file

Edit the input file, fabric-forgetme-flow.py, to set your user ID as the forget ID. (Alternatively, you can specify this when you run the client.) Optionally change the client data values.

from nuance.fabric.forget.v1.forget_pb2 import *

list_of_requests = []

request = ForgetRequest()

request.forget_id = "eric@aardvark.com"
request.forget_type = USER
request.client_data["app_os"] = "CentOS"

#Add request to list
list_of_requests.append(request)

# ---

Run client

Make sure your client credentials are set as variables (see Set credentials). Then run the client to request the deletion of data associated with the user ID as set in forget_id in the flow file. For example, on Linux:

python3 fabric-forgetme-client.py --secure \
--clientID $CLIENT_ID --clientSecret $CLIENT_SECRET \
--oauthURL https://auth.crt.nuance.com/oauth2/token \
--serverUrl log.api.nuance.com 

2023-02-20 13:21:50,709 INFO : Iteration #1
2023-02-20 13:21:50,741 INFO : Running flows in serial
2023-02-20 13:21:50,741 INFO : Obtaining auth token using basicAuth(Client ID: appID%3A...)
2023-02-20 13:21:51,584 INFO : Running file [fabric-forgetme-flow.py]
2023-02-20 13:21:51,584 INFO : Sending Forget request
2023-02-20 13:21:51,584 INFO : Sending request: forget_id: "eric@aardvark.com"
client_data {
  key: "app_os"
  value: "CentOS"
}

2023-02-20 13:21:51,584 INFO : Sending metadata: []
2023-02-20 13:21:52,392 INFO : Received response: status {
  status_code: OK
  status_details {
    message: "Forgetme request is accepted, traceId: c807a1b6-b3b7-4227-862e-a6fa7775e6a0"
  }
}

2023-02-20 13:21:52,392 INFO : First chunk latency: 0.8080893770093098 seconds
2023-02-20 13:21:52,392 INFO : Done running file [fabric-forgetme-flow.py]
2023-02-20 13:21:52,394 INFO : Iteration #1 complete
2023-02-20 13:21:52,394 INFO : Average first-chunk latency (over 1 requests): 0.8080893770093098 seconds
Done

Optionally provide the forget ID and/or forget type on the command line. For example:

$ python3 fabric-forgetme-client.py --secure \
--clientID $CLIENT_ID --clientSecret $CLIENT_SECRET \
--oauthURL https://auth.crt.nuance.com/oauth2/token \
--serverUrl log.api.nuance.com \
--forgetId "james@aardvark.com"

Run client for session ID

This scenario requests the deletion of log data associated with a session ID returned in this previous DLGaaS request:

# A unique session ID is returned as a StartReponse:
'payload': {'session_id': '92705444-cd59-4a04-b79c-e67203f04f0d'}

Edit input file

Edit fabric-forgetme-flow.py to set your session ID as the forget ID. (Alternatively, you can specify this when you run the client.) Optionally change the client data values.

from nuance.fabric.forget.v1.forget_pb2 import *

list_of_requests = []

request = ForgetRequest()

request.forget_id = "92705444-cd59-4a04-b79c-e67203f04f0d"
request.forget_type = SESSION
request.client_data["app_os"] = "Windows"

#Add request to list
list_of_requests.append(request)

# ---

Run client

Make sure your client credentials are set as variables (see Set credentials). Then run the client to request the deletion of data associated with the session ID set as the forget_id in the flow file. For example, on Windows:

python fabric-forgetme-client.py --secure ^
--clientID %CLIENT_ID% --clientSecret %CLIENT_SECRET% ^
--oauthURL https://auth.crt.nuance.com/oauth2/token ^
--serverUrl log.api.nuance.com 

2023-02-20 13:51:54,421 INFO : Iteration #1
2023-02-20 13:51:54,428 INFO : Running flows in serial
2023-02-20 13:51:54,428 INFO : Obtaining auth token using basicAuth(Client ID: appID%3A...)
2023-02-20 13:51:54,836 INFO : Running file [fabric-forgetme-flow.py]
2023-02-20 13:51:54,836 INFO : Sending Forget request
2023-02-20 13:51:54,838 INFO : Sending request: forget_id: "92705444-cd59-4a04-b79c-e67203f04f0d"
forget_type: SESSION
client_data {
  key: "app_os"
  value: "Windows"
}

2023-02-20 13:51:54,841 INFO : Sending metadata: []
2023-02-20 13:51:55,455 INFO : Received response: status {
  status_code: OK
  status_details {
    message: "Forgetme request is accepted, traceId: 0ee9c96e-67cf-4214-99f1-4c26f0f7c6b6"
  }
}

2023-02-20 13:51:55,456 INFO : First chunk latency: 0.625 seconds
2023-02-20 13:51:55,461 INFO : Done running file [fabric-forgetme-flow.py]
2023-02-20 13:51:55,467 INFO : Iteration #1 complete
2023-02-20 13:51:55,469 INFO : Average first-chunk latency (over 1 requests): 0.625 seconds
Done

View results in event logs

The ForgetMe requests are entered in the event logs. Nuance administrators poll these logs regularly and delete the matching logs in their data stores.

If you wish to see the logs, obtain the logs for your app ID. For example, this is request to delete user ID logs. The forgetmeid field contains the hashed version of the user ID, the same value as in the original XaaS request. Some fields are omitted for clarity:

[{
  "topic": "NMDPTRIAL_your_name_20200123T153120765439"

  {
    "value":{
      "service":"Fabric",
      "type":"Forgetme",
      "data":{
        "forgetmeid":"f299b37de699b999c9e1ebb3c8dfddb38786521680da61c007181f577c3286d0",
        "forgetmeType":"USER"
      }
    }
  }
}]

And this records the request to delete session ID logs. The forgetmeid field contains the session ID in plain text, as in the original XaaS request:

[{
  "topic": "NMDPTRIAL_your_name_20200123T153120765439"

  {
    "value":{
      "service":"Fabric",
      "type":"Forgetme",
      "data":{
        "forgetmeid":"92705444-cd59-4a04-b79c-e67203f04f0d",
        "forgetmeType":"SESSION"
      }
    }
  }
}]