1. BitTitan Help Center
  2. Perform a Migration
  3. Google Workspace Migrations
  4. Google Vault
  5. Google Vault Extractor

Use the Google Vault Extractor

BitTitan’s Google Vault Extractor is a command-line tool that automates the creation of Google Matters. After the creation and configuration of the matters, Google Vault will search the values (based on input from BitTitan’s Google Vault Extractor) and prepare the results for export. Once the results are prepared, then BitTitan’s Google Vault Extractor will download the results.

The Google Vault Extractor must be run from a locally managed server, which can be a local workstation an on-premise server, or a virtual server. This export server is set up and maintained by the customer and is a requirement and not provided by BitTitan.

Set up and Configure the Google Vault Extractor 

Command Options

  1. GoogleVaultExport.lnk -process-start-args (mandatory)
  2. Command (export -or- exportandupload) (mandatory).
    • Defines what action(s) the extractor should take.
      • exportandupload (most commonly used) will export and download the results to the Export Server. Once the results are downloaded to the Export Server, it will use UploaderWiz to upload the results to the Azure BLOB.
      • export will export and download the results to the Export Server.
    • If using exportandupload (most commonly used), UploaderWiz is required.
  3. clientid ClientID (suggested).
    • The ClientID is generated when you create an OAuth Client API in your Google tenant.
  4. clientSecret ClientSecret(suggested).
    • The ClientSecret is generated when you create an OAuth Client API in your Google tenant.
  5. newEmailsTimeout86400000 (suggested).
    • Specifies the wait time in milliseconds for new email during an export.
    • Not defining this results in the default value, of 15 minutes.
  6. compressionTimeout 86400000(suggested)
    • Specifies the wait time in milliseconds for Exporter while Google Vault compresses the export. Not defining this results in the default value, of 15 minutes.
  7. missingEmailThresholdxxxx (optional)
    • Replace xxxx with a number that is an acceptable number of missing items.
    • By default 0 is the acceptable number of missing items.
    • For more information, see Mismatch in number of emails export.
  8. inputFile c:\GVE\input.txt (mandatory)
    • This file contains a list of the Google Vault users that will be exported.
    • Read Google Vault Best Practices for more information on formatting.
  9. outputFolder c:\GVE\export (mandatory)
    • This defines where Google Vault Extractor should store the data extracted from Google Vault.
  10. uploadAccessKeyStorageAccountName (mandatory if using exportandupload command)
  11. uploadSecretKey (mandatory if using exportandupload command)
  12. uploadBucketNamePublicBlobContainerName (mandatory if using exportandupload command)
    • Name of the public blob container where UploaderWiz should place Google Vault's files.
    • For more information, read the Google Vault Migration Guide.
  13. searchTerms ""label:^deleted AND -label:chats""
    • Search term is used within a Matter to retrieve a specific data set for export. Not defining this will result in Google Vault exporting all mail for the specified user. Read more: Use search operators. 
    • The example above would export all permanently deleted mail except those labeled "Draft" or existing in "Spam".
    • A search operator using a – in front will result in excluding it.
    • Google Vault chats are not migrated so must be excluded in the export using searchTerms.
    • SearchTerms labels must be enclosed in two double quotes such as -searchTerms ""label:^deleted AND -label:^Chats"".

Search Terms

It’s strongly recommended that you review the Google website and be familiar with how the search operators work. These are a function of Google and if they are not used correctly, it may result in missing email or not exporting the results that you were expecting. Using search search terms is the key to what is extracted from the Google Vault Mailbox.

 Use Search Operators

Common Search Terms 

Anything with a dash (-) in front of it means that it will be excluded from the export.

  • label:^deleted - This option is used when you want to extract the permanently deleted items. 
  • in:trash - This option is used when you want to extract the items in the trash. 
  • -in:trash - This option is used when you don’t want to extract the items in the trash.
  • in:drafts - This option is used when you only want to extract the items in the drafts folder. 
  • -in:drafts - This option is used when you don’t want to extract the items in the drafts folder. 
  • older_than:1y - This option is used when you only want to extract items older than one year.
  • newer_than:1y - This option is used when you only want to extract items newer than one year. 

Building the Right Syntax

Building the right syntax for the BitTitan Google Vault Extractor is all dependent on what data needs to be extracted from Google Vault. The commands can be structured to fit your needs and be customized depending on velocity, security requirements, extractor server size, data export requirements, and throttling on the Google side.

To launch the extractor utility, open the command prompt as an administrator and  navigate to the working directory.

Example: Search, Export, Download then Upload automatically using your own Google Vault OAuth Client API Setup: 
GoogleVaultExport.lnk -process-start-args "-command exportandupload -clientid GOOGLE CLIENT ID -clientSecret GOOGLE CLIENT SECRET -NewEmailsTimeout 86400000 -CompressionTimeout 86400000 -inputFile C:\GVault\input.txt -outputFolder c:\GVault\Export -uploadAccessKey AZURE CLIENT -uploadSecretKey AZURE SECRET KEY -uploadBucketName AZURE BUCKET -searchTerms ""label:^deleted AND -label:^chats""" 

  • -command exportandupload option is used when you plan to use BitTitan’s UploaderWiz to automatically upload the exported results to the Azure BLOB.
  • -clientid GOOGLE CLIENT ID -clientSecret GOOGLE CLIENT SECRET option is used when using your own Google Vault OAuth Client API setup.
  • -searchTerms ""label:^deleted AND -label:^chats"” option is used when you want to export only the permanently deleted items from Google Vault. 

Example: Search, Export, and only Download. This option is most commonly used when you plan to use another tool (e.g. AzCopy) to upload the data into the Azure BLOB. 

GoogleVaultExport.lnk -process-start-args "-command export -clientid GOOGLE CLIENT ID -clientSecret GOOGLE CLIENT SECRET -NewEmailsTimeout 86400000 -CompressionTimeout 86400000 -inputFile C:\GVault\input.txt -outputFolder c:\GVault\Export -searchTerms ""label:^deleted AND -label:^chats""" 

  • -command export If you use this option, you will have to manually upload the data into the Azure BLOB, before MigrationWiz can migrate it. 
  • -clientid GOOGLE CLIENT ID -clientSecret GOOGLE CLIENT SECRET is used when using your own Google Vault OAuth Client API setup.  
  • -searchTerms ""label:^deleted AND -label:^chats"" is used when you only want to export the permanently deleted items in the trash from Google Vault. 

Example: Search, Export, Download then Upload automatically, using BitTitan Shared Client API: 

GoogleVaultExport.lnk -process-start-args "-command exportandupload -NewEmailsTimeout 86400000 -CompressionTimeout 86400000 -inputFile C:\GVault\input.txt -outputFolder c:\GVault\Export -uploadAccessKey AZURE CLIENT -uploadSecretKey AZURE SECRET KEY -uploadBucketName AZURE BUCKET -searchTerms ""label:^deleted AND -label:^chats""" 

  • Automatic upload: "-command exportandupload is used if you plan to use BitTitan’s UploaderWiz to automatically upload the exported results to the Azure BLOB.
  • Exporting permanently deleted items:-searchTerms ""label:^deleted AND -label:^chats"" is used if you only want to export only the permanently deleted items from Google Vault.

This option will use the BitTitan Shared Client API.

This will automatically launch a browser window for authentication. Log in with the Google Administrator Account and select that account to authenticate for access to Google Vault data. To switch to a different Google Administrator account after logging in with this command, you can use the reset option GoogleVaultExport.exe "-command reset".

Extraction Process

BitTitan Google Vault Extractor will create and configure the matter based on a list of users. When the matter is created, we instruct Google to search the matter based on the terms specified. Google searches Vault, prepares, and exports. During the search, we log the number of anticipated items Google will return in the export. When Google has the export results ready for download, BitTitan Google Vault Extractor will automatically download the export from Google. The export is downloaded to a local Export Server and stored until it can be uploaded back into an Azure BLOB. BitTitan Google Vault Extractor can be set to sequentially download from Google, and then upload to Azure. The extractor will download two files from Google: the compressed zip folder with the data and an XML file. It will also create a .done file that indicates a successful extraction. If the extractor fails, it will create a .fail file for the user.

blobid0.png

The export needs to be in Azure because that is where MigrationWiz can read the file and start the migration of data into the Office 365 mailbox. Since Google Vault is a compliance system and not an archive, the typical destination for the data is in the Recoverable Items Folder in the user’s primary mailbox. It’s important to place the user's mailbox on Litigation Hold before migrating any content. 

Running the Google Vault Extractor

  1. From the Export Server, open an administrative command prompt.
  2. Navigate to your& working directory.
  3. Run the command to Search, Export, Download, and Upload (optional).
    Example: Search, Export, Download then Upload automatically using your own Google Vault OAuth Client API Setup: 
    GoogleVaultExport.lnk -process-start-args "-command exportandupload -clientid GOOGLE CLIENT ID -clientSecret GOOGLE CLIENT SECRET -NewEmailsTimeout 86400000 -CompressionTimeout 86400000 -inputFile C:\GVault\input.txt -outputFolder c:\GVault\Export -uploadAccessKey AZURE CLIENT -uploadSecretKey AZURE SECRET KEY -uploadBucketName AZURE BUCKET -searchTerms ""label:^deleted AND -label:^chats""" 
    Example: Search, Export, Download then Upload automatically NOT using your own Google Vault OAuth Client API Setup: 
    GoogleVaultExport.lnk -process-start-args "-command exportandupload -NewEmailsTimeout 86400000 -CompressionTimeout 86400000 -inputFile C:\GVault\input.txt -outputFolder c:\GVault\Export -uploadAccessKey AZURE CLIENT -uploadSecretKey AZURE SECRET KEY -uploadBucketName AZURE BUCKET -searchTerms ""label:^deleted AND -label:^chats""" 
  4. This will automatically launch a browser window for authentication. Log in with the Google Administrator Account and select that account to authenticate for access to Google Vault data.
    • Switching Google Administrator accounts: To switch to a different Google Administrator account after logging in with this command, you can use the reset option GoogleVaultExport.exe "-command reset".
  5. Once access is granted, the extractor will run in the command window.
  6. When completed:
    1. Confirm that all expected Google Vault data is available in the Azure BLOB if you used the option to extract and upload or
    2. Manually upload the results to the Azure BLOB if you used the option to only extract.

      Important

      The extractor will download two files from Google. The compressed zip folder with the data and an XML file. It will also create a .done file, which indicates a successful extraction. It will do this for each user in the input file.  

      Fail States

      If the extractor fails on a user, it will create a .fail file for the user.
Was this article helpful?
0 out of 0 found this helpful

Articles in this section