Legal Hold - Targeted Download API
Targeted Download is an API-based method for remote data retrieval, designed to gather data linked to specific users under a Legal-Hold policy. This approach allows legal administrators to employ their scripting skills and create customized automated workflows, using languages like Python or PowerShell, to selectively gather the necessary metadata or actual data. By eliminating irrelevant and duplicate data, this process reduces eDiscovery costs effectively.
As a Druva Cloud Administrator or a Legal Hold Administrator, you can use the - Targeted Downloads API to list and download the files and folders on the devices or SaaS Apps of the users put on Legal Hold. You can also apply the available filters to list the metadata of the files as per your requirements.
Supported Data Sources
- Endpoint - Files
- SaaS Apps - Files and Emails
- For Emails - Email files, Calendar, Contacts, and Tasks are supported.
Before you begin
- Ensure you are a Druva Cloud or a Legal Hold administrator.
- The users for whom you want to view the data are placed on Legal Hold.
Step 1 - Generate API Credentials
inSync uses HTTP Basic authentication for API requests. inSync Cloud administrator can create the authentication information from the Endpoint Management Console.
The authentication information consists of the following components:
- Username: Email ID of the inSync Cloud administrator who creates the authentication token.
- Password: Authentication token that is generated.
inSync stores the authentication information in the database, that is encrypted with the ekey of your organization. Whenever you request to access the API, you must specify the username and the password.
For detailed instructions, see How to obtain the authentication information.
Step 2 - Access WebDAV URL
To access Legal Hold data, you must obtain the WebDAV access details. The WebDAV access details include your credentials and URLs to the storage where user data resides. If the users’ data is backed up on multiple storages, multiple WebDAV URLs are created.
To obtain the WebDAV access details,
- Click the relevant Legal Hold policy.
- Click Data Access. The data access URL and authentication details appear in the WebDAV Access Details area.
Alternatively, you can also obtain the WebDAV URL using the API - List the users on Legal Hold v3.
Typical format of WebDAV URL
https://restore-c11-cloud.druva.com/webdav/<legalhold_name>/<user_name>/
Where,
<legalhold_name> - Name of the legal hold policy that is used to place data on legal hold.
<user_name> - Username of the user whose data is placed on legal hold.
Step 3 - Run the API
Run the API which can include the appropriate filters and operators as listed follows -
Available Filters
The following filters are supported to enable you filter data using the WebDAV URL.
| Filter Name | Format to include in API response | Filter Description | Value & Validations | Request Body Example |
|---|---|---|---|---|
| Name | name | Specify this filter to list all files and folders with only a specific name or substrings within their name. Matching files and folders are returned in XML format. Note - filter is applicable on the 'Actual name' of the file or folder and not the 'Display name'. | Specify a single file or folder name. It is case-sensitive. | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name></D:name> </D:filters> </D:propfind> |
| Include Extension | ext_include | Specify this filter to list all files with specific file extensions. Specify comma-separated file extensions (without dot) to include results with multiple extensions. | 1. No wildcards in extensions are allowed. 2. Only ASCII characters are allowed in the list of extensions. 3. A maximum number of 50 extensions can be provided at a time. | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:ext_include></D:ext_include> </D:filters> </D:propfind> |
| Exclude Extension | ext_exclude | Specify this filter to list all files excluding the specified file extensions. Specify comma-separated file extensions (without dot) to exclude multiple extensions. | 1. No wildcards in extensions are allowed. 2. Only ASCII characters are allowed in the list of extensions. 3. A maximum number of 50 extensions can be provided at a time. | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:ext_exclude></D:ext_exclude> </D:filters> </D:propfind> |
| Root Directory Name | root_dir_name | Specify this filter to list all the contents in a specific root directory. All the files and folders in the root directory are returned in XML format. Specify a directory or comma-separated list of directories to list all the content. Example - Folder names, Documents, Desktop Note - This filter is applicable only at the device level. | Exact directory name | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:root_dir_name></D:root_dir_name> </D:filters> </D:propfind> |
| Snapshot ID | snapshot_id | Specify this filter to list all the contents in a snapshot. Get the snapshot ID using the List all Snapshots API. Format - | ||
| List only folders | list_only_folders | Specify this filter to list all the folders. | True, False | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:list_only_folders></D:list_only_folders> </D:filters> </D:propfind> |
| Match any one | match_any_one | Specify this filter to list the matching files and folders that match any of the criteria mentioned in the filters. This filter can be used in combination with the following filters only - - Name + Include Extension - Name + Exclude Extension If you specify True, the operation is an OR operation. If you specify False, the operation is an AND operation. | True = OR False = AND |
Supported Operators
The AND and OR operators are supported to enable you to apply filters in a conditional way and filter data using the WebDAV URL.
| Supported Operators | Filters supporting the Operators | Match any one |
|---|---|---|
| AND | Snapshot ID, Root Directory Name, List only folders | Not Applicable |
| AND, OR | Name, Include Extension, Exclude Extension | True/False |
Invalid Combination of Filters
The following combinations are invalid and not allowed while performing a listing operation.
| Filter | Invalid Filter Combinations |
|---|---|
| List only folders | - 'Include Extension' & 'Exclude Extension' filters are not allowed as 'List only folders' lists only folders. - Cannot be used with 'Match any one' |
| File Extension filters | 'Include Extension' & 'Exclude Extension' filters cannot be used simultaneously. |
Sample API Call
Sample API Request format
| Field | Description |
|---|---|
| Path | https://restore-c11-cloud.druva.com/webdav/<legalhold_name>/<user_name>/\ |
| Method | PROPFIND |
| Authorization | Bearer and Basic Authorization |
| Header | depth: Possible values - 1 (recommended) = If you specify '1', the API returns the resource and its immediate children. This is recommended in case you have a large data set to get the details. - infinity = If you specify 'infinity', the API returns the resource and all of its children. Using this option may take a longer time to return the response. Data type - String |
| Input Parameters | Use the filter specified in Step 4 above. Specify the file or folder name |
| Body | Using the Name filter <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name>textfile</D:name> </D:filters> </D:propfind> Use the suggested combination of filters to create your request. |
Sample Format of Combination of Available Filters
| Combination of the filters | Request Body |
|---|---|
| Name based filter + Include Extension Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name></D:name> <D:ext_include></D:ext_include> </D:filters> </D:propfind> |
| Name based filter + Exclude Extension Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name></D:name> <D:ext_exclude></D:ext_exclude> </D:filters> </D:propfind> |
| Include Extension Filter + Root Directory Name Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:ext_include></D:ext_include> <D:root_dir_name></D:root_dir_name> </D:filters> </D:propfind> |
| Exclude Extension Filter + Root Directory Name Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:ext_exclude></D:ext_exclude> <D:root_dir_name></D:root_dir_name> </D:filters> </D:propfind> |
| Root Directory Name Filter+ Name based filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:root_dir_name></D:root_dir_name> <D:name></D:name> </D:filters> </D:propfind> |
| Name based filter + Include Extension Filter + Root Directory Name Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name></D:name> <D:ext_include></D:ext_include> <D:root_dir_name></D:root_dir_name> </D:filters> </D:propfind> |
| Name based filter + Exclude Extension Filter + Root Directory Name Filter | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:name></D:name> <D:ext_exclude></D:ext_exclude> <D:root_dir_name></D:root_dir_name> </D:filters> </D:propfind> |
| Match any one + Name based filter + Include Extension filter This filter lists all the files with and with extensions that are listed | <D:propfind xmlns:D="DAV:"> <D:allprop/> <D:filters> <D:match_any_one>False</D:match_any_one> <D:name></D:name> <D:ext_include></D:ext_include> |
API response codes
This section lists the API response codes generated based on the request to access Legal Hold APIs.
inSync processes the API request and displays the following response codes:
| Response Code | Description |
|---|---|
| HTTP 200 | The request is successful. |
| HTTP 207 | The request is successful. Multistatus response. |
| HTTP 400 | The request syntax is incorrect. For example, Request Headers are not present. |
| HTTP 401 | Authentication was not successful. This response code is generated in one of the following scenarios: The access request does not have the required parameters. The access request has invalid parameters, like incorrect Username and/or Password. |
| HTTP 403 | WebDAV URL is incorrect. Specify a valid URL and ensure it is reachable. |
| HTTP 404 | Requested API or data not found. Ensure the requested API is valid. |
| HTTP 500 | Some other internal server errors in processing the Legal Hold API request. An Internal Error message appears. |
Updated about 1 year ago