1. Home
  2. Installation and Set-up
  3. Setting a User-Defined Data Location

Setting a User-Defined Data Location

NOTE: For version 9, Diplomat expects the DiplomatData environment variable to be the full explicit path for the desired configuration directory, not a base folder in which to create a Coviant Software folder with a Diplomat-j subfolder.

 

How does Diplomat Managed File Transfer determine where to write data?
Each time the Diplomat MFT Service starts, it checks for environment variables named DIPLOMATDATA and PROGRAMDATA.
 

  • If a DIPLOMATDATA environment variable exists, the Diplomat MFT Service attempts to access it and, if necessary, create sub-directories under the directory defined by the DIPLOMATDATA environment variable.
     
    NOTE: System environment variables are strongly recommended over user environment variables. User-specific environment variables take precedence over system variables, and user variables are not easily viewable and editable unless interactively logged in as the service account.
  • If a PROGRAMDATA environment variable exists and a DIPLOMATDATA environment variable does NOT exist, the Diplomat MFT Service attempts to access it and, if necessary, create sub-directories under the directory defined by the PROGRAMDATA environment variable.

If I want to control where Diplomat MFT writes data, how do I decide which environment variable to set?
On Windows systems that enforce User Account Control (UAC), use a DIPLOMATDATA environment variable to override the system PROGRAMDATA environment variable, which is always set to C:\ProgramData and is not editable by the user. On Windows systems that do not enforce UAC, create a user-defined PROGRAMDATA environment variable.

NOTE: The directories defined by DIPLOMATDATA or PROGRAMDATA environment variables must exist on the same system as the Diplomat MFT Service. They cannot be defined using mapped drives or UNC paths to other systems.

NOTE: When you create either a DIPLOMATDATA or PROGRAMDATA environment variable, you must also create the directory defined by the environment variable and the Diplomat MFT Service must have read and write access to it, including the ability to create sub-directories.

NOTE: C:\Program Files is always set to Read Only and is not editable by the user. So, it cannot be the directory defined by either the DIPLOMATDATA or PROGRAMDATA environment variable.

NOTE: Both the DIPLOMATDATA and PROGRAMDATA are case sensitive.

How do I know whether DiplomatData or ProgramData environment variables exist on my system?
You can check the existence and location of the DIPLOMATDATA or PROGRAMDATA directory by opening a DOS window and typing the command ‘set’. All environment variables are listed.

NOTE: If you look at environment variables under Control Panel, the PROGRAMDATA variable may not be displayed, since it is typically not editable by the user.

Where do I “install” new license files that I receive from Coviant Software support?
If a DIPLOMATDATA environment variable exists, the Diplomat MFT Service attempts to locate license files in the …\Coviant Software\Diplomat-j sub-directory of the directory defined by the DIPLOMATDATA environment variable. If no license file is found, the Diplomat MFT Service looks in the install directory as it does in older versions of Diplomat MFT (pre-v4.1). If it finds the license file in the installation directory, it copies it to the directory defined by the DIPLOMATDATA environment variable.

If a DIPLOMATDATA environment variable does NOT exist and a PROGRAMDATA environment variable exists, the Diplomat MFT Service attempts to locate license files in the …\Coviant Software\Diplomat-j sub-directory of the directory defined by the PROGRAMDATA environment variable. If no license file is found, the Diplomat MFT Service looks in the install directory as it does in older versions of Diplomat MFT (pre-v4.1).& If it finds the license file in the installation directory, it copies it to the directory defined by the PROGRAMDATA environment variable.

If neither the DIPLOMATDATA nor a PROGRAMDATA environment variable exists, then the Diplomat MFT Service looks in the install directory as it does in older versions of Diplomat MFT (pre-v4.1).

Where is Diplomat MFT data written?
The Diplomat MFT data files and their locations are as shown below, where <InstallDirectory> indicates the directory where the Diplomat MFT Service or other Diplomat MFT components are installed. <ProgramData> indicates the directory defined by the PROGRAMDATA environment variable and <DiplomatData> indicates the directory defined by the DIPLOMATDATA environment variable. Defaults for the Diplomat Service, Client and Job Monitor cannot be overridden.
 

Diplomat MFT Data File Locations
  File Type Without DIPLOMATDATA With DIPLOMATDATA
Without PROGRAMDATA With PROGRAMDATA
Service Audit (non-SQL) <InstallDirectory>\auditDb <ProgramData>\Coviant Software\Diplomat-j\auditDb <DiplomatData>\Coviant Software\Diplomat-j\auditDb
Diplomat MFT transaction database <InstallDirectory>\db\derby\diplomatDb <ProgramData>\Coviant Software \Diplomat-j\db\derby\diplomatDb <DiplomatData>\Coviant Software \Diplomat-j\db\derby\diplomatDb
Heap dumps <InstallDirectory>\tomcatWebserver\bin <InstallDirectory>\tomcatWebserver\bin <InstallDirectory>\tomcatWebserver\bin
Job history <InstallDirectory>\db\derby\jobHistory <ProgramData>\Coviant Software \Diplomat-j\db\derby\jobHistory <DiplomatData>\Coviant Software \Diplomat-j\db\derby\jobHistory
Key import <InstallDirectory>\keys <ProgramData>\Coviant Software\Diplomat-j\keys <DiplomatData>\Coviant Software\Diplomat-j\keys
License <InstallDirectory> <ProgramData>\Coviant Software\Diplomat-j <DiplomatData>\Coviant Software\Diplomat-j
SSL certificate import <InstallDirectory>\certs <ProgramData>\Coviant Software\Diplomat-j\certs <DiplomatData>\Coviant Software\Diplomat-j\certs
Temporary <InstallDirectory>\temp <ProgramData>\Coviant Software\Diplomat-j\temp <DiplomatData>\Coviant Software\Diplomat-j\temp
Troubleshooting <InstallDirectory>\troubleshooting <ProgramData>\Coviant Software\Diplomat-j\troubleshooting <DiplomatData>\Coviant Software\Diplomat-j\troubleshooting
Client Client initialization <InstallDirectory> <ProgramData>\Coviant Software\Diplomat-j <DiplomatData>\Coviant Software\Diplomat-j
Heap dump* <InstallDirectory> <ProgramData>\Coviant Software\diplomat-j <DiplomatData>\Coviant Software\diplomat-j
Client logs** <InstallDirectory>\logs\client <ProgramData>\Coviant Software\Diplomat-j\logs\client <DiplomatData>\Coviant Software\Diplomat-j\logs\client
Job Monitor Job monitor initialization <InstallDirectory> <ProgramData>\Coviant Software\Diplomat-j <DiplomatData>\Coviant Software\Diplomat-j
User Defaults Primary archives <InstallDirectory>\archive <ProgramData>\Coviant Software\Diplomat-j\archive <DiplomatData>\Coviant Software\Diplomat-j\archive
Backups <InstallDirectory>\backup <ProgramData>\Coviant Software\Diplomat-j\backup <DiplomatData>\Coviant Software\Diplomat-j\backup
Logs <InstallDirectory>\logs <ProgramData>\Coviant Software\Diplomat-j\logs <DiplomatData>\Coviant Software\Diplomat-j\logs

* Client heap dumps are determined by the working directory as specified in the Diplomat MFT Client desktop icon, which can be changed by the user, if desired. Users of systems without a C:\ProgramData\Coviant Software directory will need to manually create this directory before a client heap dump can be written.

** The location of client log files can be overridden by manually updating the diplomat.ini.xml file.

How do I migrate existing data from a Windows implementation of Diplomat Managed File Transfer to a new location on the same system?
Below is a summary of the steps to move to the new data location:

1. Suspend your transactions.

2. Create a backup file of your Diplomat MFT transaction database.

3. Exit from the Diplomat MFT Client. Stop the Diplomat MFT Service.

4. Create the <DiplomatData>/Coviant Software/Diplomat-j or <ProgramData>/Coviant Software/Diplomat-j directory where <DiplomatData> or <ProgramData> is to be defined by the environment variable. Ensure that the user account attached to the Diplomat MFT Service has read and write access to the new directory, including the ability to create sub-directories.

5. Create a new PROGRAMDATA or DIPLOMATDATA environment variable using Control Panel > User Accounts > Change my environment variables for Windows 7, Windows Server 2008 and follow-on products.

6. On Windows7, Windows Server 2008 or follow-on systems, copy all files and folders from the current <ProgramData>/Coviant Software/Diplomat-j directory to the newly created directory. On Windows XP systems, copy the diplomat.lic and the diplomat.ini.xml files in the …/Program Files/Coviant Software/Diplomat-j directory to the new <ProgramData>/Coviant Software/Diplomat-j or <DiplomatData>/Coviant Software/Diplomat-j directory.

7. Install the new version of Diplomat Managed File Transfer, if you are upgrading versions.

8. Start the Diplomat MFT Service.

9. Start the Diplomat MFT Client.

10. Restore your Diplomat MFT transaction database using the backup file you made in Step 2. DO NOT unsuspend after the restore. Check the messages in the Restore window for any errors.

NOTE: If you are unsure of how your configuration settings will be interpreted in the new environment, DO NOT RESTORE configuration data. Re-enter the configuration data under Settings from the top menu bar after the restore has completed.

NOTE: When a backup file was created using an earlier Diplomat MFT version and is restored onto a system with PROGRAMDATA or DIPLOMATDATA environment variables defined, all user-defined configuration settings are retained. However, configuration settings set to default directories under … Program Files\Coviant Software\Diplomat-j are automatically updated to directories under <ProgramData> or <DiplomatData> directories. Configuration settings set to default directories under …\ProgramData\Coviant Software\Diplomat-j are NOT automatically updated to directories under <ProgramData> or <DiplomatData> directories.

11. From Settings > System on the top menu bar check Backup, Logs, Paging and Primary Archive settings to ensure files will be written to the desired locations.

​12. Where the Diplomat MFT Service was previously installed, check the directories listed above for files that you need to retain – typically audit, job history, keys, and SSL certificates.

NOTE: If you have chosen to store files (e.g., keys and SSL certificates) in other locations, you may want to move these files as well. Move all files under the existing directories to the new directories shown on the table above.

13. After all data has been migrated, unsuspend transactions for each transaction.

Updated on February 19, 2022

Was this article helpful?

Related Articles