Difference between revisions of "Scripting"
| [unchecked revision] | [checked revision] |
Ltalaschus (talk | contribs) |
|||
| (18 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
| − | + | MailStore Server provides powerful interfaces, such as the [[MailStore Server Management Shell]] and the [[MailStore Server Administration API]], that can be used to automate many tasks through scripts. This makes it possible to realize scenarios that would be difficult or impossible to implement through the GUI. Furthermore, scripting allows to integrate MailStore Server in existing workflows or business processes. | |
| − | |||
This article exemplifies the usage of the MailStore Server Administration API in several scripting languages. In our scripting section we assorted various scripts that make use of the demonstrated techniques and solve frequently posed problems. These scripts can be used freely and may be adapted to a specific environment or serve as a basis for further solutions. | This article exemplifies the usage of the MailStore Server Administration API in several scripting languages. In our scripting section we assorted various scripts that make use of the demonstrated techniques and solve frequently posed problems. These scripts can be used freely and may be adapted to a specific environment or serve as a basis for further solutions. | ||
| − | <p class=msnote>'''Important Notice:''' The scripting code published in this section must be considered as reference and example implementations. | + | <p class=msnote>'''Important Notice:''' The scripting code published in this section must be considered as reference and example implementations. Unless stated otherwise, the scripts are released under the terms an conditions of the [[wikipedia:MIT_License|MIT License]].</p> |
| − | == | + | == Using Window Batch Scripts == |
| − | + | For simple tasks, such as bulk import or export of PST files, Window batch scripts may also be used. Usually, these scripts do not control MailStore Server through the [[MailStore Server Administration API]] but through the [[MailStore_Server_Management_Shell|command line interpreter]]. | |
| − | + | Before you are able to execute [[Media:Batchscripts.zip|Windows batch scripts]] on the command line ''cmd.exe'', you need to open the script file in a text editor such as ''Notepad''. Adjust the configuration variables above the ''DON'T CHANGE ANYTHING BEYOND THIS LINE'' line to your local environment. Please take care not to change any single or double quotes. | |
| − | + | To obtain the the thumbprint (fingerprint, hash) of the MailStore Server certificate, follow these steps: | |
| − | |||
| − | + | * Open the [[MailStore_Server_Service_Configuration#IP_Addresses_and_Ports|MailStore Server Service Configuration]] | |
| + | * Navigate to ''Network Settings'' | ||
| + | : [[File:tech_config_02.png|center|550px]] | ||
| + | * Click on the name of the server certificate that is used for ''MailStore Client'' | ||
| + | * Find the thumbprint in the details of the certificate | ||
| + | : [[File:GPO_Client_2012R2_13.png]] | ||
| − | + | Be aware that when copying the thumbprint there may be an invisible character in front of the first character of the thumbprint. This invisible character must not be present in the script files. See [https://support.microsoft.com/en-us/help/2023835/certificate-thumbprint-displayed-in-mmc-certificate-snap-in-has-extra] for details. | |
| − | |||
=== Available Windows Batch Scripts === | === Available Windows Batch Scripts === | ||
| − | |||
{| class="wikitable" | {| class="wikitable" | ||
! scope="col" | File Name | ! scope="col" | File Name | ||
| Line 27: | Line 28: | ||
|- | |- | ||
| <tt>bulkImportPST.bat</tt> | | <tt>bulkImportPST.bat</tt> | ||
| − | | Import multiple PST files from a given directory into the archive of a the given MailStore user. | + | | Import multiple PST files from a given directory into the archive of a the given MailStore user. A PST archiving profile of the type ''Single User'' with the name 'templateBulkImportPST' must be created manually beforehand. |
|- | |- | ||
| <tt>bulkImportMBOX.bat</tt> | | <tt>bulkImportMBOX.bat</tt> | ||
| − | | Import multiple MBOX files from a given directory into the archive of a the given MailStore user. | + | | Import multiple MBOX files from a given directory into the archive of a the given MailStore user. An MBOX archiving profile with the name 'templateBulkImportMBOX' must be created manually beforehand. |
|- | |- | ||
| <tt>bulkExportPST.bat</tt> | | <tt>bulkExportPST.bat</tt> | ||
| − | | Export of all archives into multiple PST files seperated by MailStore users. | + | | Export of all archives into multiple PST files seperated by MailStore users. A PST export profile with the name 'templateBulkExportPST' must be created manually beforehand. |
|- | |- | ||
| <tt>bulkDeleteUsers.bat</tt> | | <tt>bulkDeleteUsers.bat</tt> | ||
| Line 44: | Line 45: | ||
To be able to execute Python scripts you need to install the Python runtime. The Windows installer of the Python runtime can be downloaded from [http://www.python.org Python.org]. For Linux operating systems, please follow the instructions of your distributor's package manager to install the Python runtime. | To be able to execute Python scripts you need to install the Python runtime. The Windows installer of the Python runtime can be downloaded from [http://www.python.org Python.org]. For Linux operating systems, please follow the instructions of your distributor's package manager to install the Python runtime. | ||
| − | For executing our scripts, a version of the [ | + | For executing our scripts, a version of the [[Media:Python-api-wrapper.zip|Python API Wrapper]] is required. Installation instructions for the wrapper are available in the corresponding section of the [[Python API Wrapper Tutorial]]. |
In order to execute Python scripts, you have to open the script file you want to execute with IDLE (shipped with Python's Windows installer) and adjust the configuration section above the line stating ''DON'T CHANGE ANYTHING BEYOND THIS LINE''. Please take care not to change any double or single quotes. | In order to execute Python scripts, you have to open the script file you want to execute with IDLE (shipped with Python's Windows installer) and adjust the configuration section above the line stating ''DON'T CHANGE ANYTHING BEYOND THIS LINE''. Please take care not to change any double or single quotes. | ||
| Line 50: | Line 51: | ||
To execute the script, click on ''Run'' > ''Run Module'' or press the F5-key in IDLE. A new window pops up where you can follow the standard output of the script and see possible execution errors. | To execute the script, click on ''Run'' > ''Run Module'' or press the F5-key in IDLE. A new window pops up where you can follow the standard output of the script and see possible execution errors. | ||
| − | If you are planning to write your own scripts in Python to automate MailStore Server tasks, the [[Python API Wrapper Tutorial]] offers a good starting point. Otherwise, if you just want to make use of the provided [[Python Scripts]], you can download them from | + | If you are planning to write your own scripts in Python to automate MailStore Server tasks, the [[Python API Wrapper Tutorial]] offers a good starting point. Otherwise, if you just want to make use of the provided [[Media:Scripts.zip|Python Scripts]], you can download them from here. |
* [[Python API Wrapper Tutorial]] | * [[Python API Wrapper Tutorial]] | ||
| − | * [[Python Scripts]] | + | * [[Media:Scripts.zip|Python Scripts]] |
=== Available Python Scripts === | === Available Python Scripts === | ||
| Line 61: | Line 62: | ||
! scope="col" | Description | ! scope="col" | Description | ||
|- | |- | ||
| − | | <tt> | + | | <tt>merge_folders_server.py</tt><br/><tt>merge_folders_spe.py</tt> |
| − | | | + | | Merges the first level of sub folders of a user archive. Can be used after archiving multiple PSTs of a user. |
|- | |- | ||
| − | | <tt> | + | | <tt>create_user_folders_server.py</tt><br/><tt>create_user_folders_spe.py</tt> |
| Create folders in file system based on MailStore user names. Can be used in preparation of bulk imports of EML, MSG or PST files. | | Create folders in file system based on MailStore user names. Can be used in preparation of bulk imports of EML, MSG or PST files. | ||
|- | |- | ||
| − | | <tt> | + | | <tt>rename_inbox_server.py</tt><br/><tt>rename_inbox_spe.py</tt> |
| + | | In some cases there are two Inbox folders in the archive (Inbox and INBOX). This scripts merges them. You should merge them in the Inbox folder, that is filled by active archiving profiles. | ||
| + | |- | ||
| + | | <tt>update_user_names_server.py</tt><br/><tt>update_user_names_spe.py</tt> | ||
| + | | When the directory service changes, the usernames might change as well. When this happens, new archives will be created and the archiving might fill up these new archives. This script can be used before MailStore synchronizes with the changed directory service. It prepares usernames, archives and privileges on the own archive. When there are set up privileges on other archive, these privileges have to be adjusted manually. | ||
| + | |- | ||
| + | | <tt>check_mailstore_server_license.py</tt><br/><tt>check_mailstore_spe_license.py</tt> | ||
| Nagios/Icinga plugin for monitoring available licenses. See [[Monitoring]] for further details. | | Nagios/Icinga plugin for monitoring available licenses. See [[Monitoring]] for further details. | ||
|- | |- | ||
| − | | <tt> | + | | <tt>check_mailstore_server_results.py</tt><br/><tt>check_mailstore_spe_results.py</tt> |
| − | | Nagios/Icinga plugin for monitoring recent results. See [[Monitoring]] for further details. | + | | Nagios/Icinga plugin for monitoring recent results. See [[Monitoring]] for further details. |
| + | |- | ||
| + | | <tt>bulk_import.py</tt> | ||
| + | | Imports email files for multiple users, see [[Bulk Import of Email Files]] for further details. | ||
|} | |} | ||
== Using PowerShell Scripts == | == Using PowerShell Scripts == | ||
| − | As the standard shell that is shipped with every newer version of Windows, the .NET framework based Windows PowerShell is also well suited to control MailStore Server through the MailStore Server Administration API. | + | As the standard shell that is shipped with every newer version of Windows, the .NET framework based Windows PowerShell is also well suited to control MailStore Server through the [[MailStore Server Administration API]]. |
The MailStore PowerShell API Wrapper and the scripts are compatible with Windows PowerShell 3.0 and higher. Depending on the version of Windows, the Windows PowerShell has to be installed separately; it can be downloaded at the [https://www.microsoft.com/en-us/download/default.aspx Microsoft Download Center] free of charge. | The MailStore PowerShell API Wrapper and the scripts are compatible with Windows PowerShell 3.0 and higher. Depending on the version of Windows, the Windows PowerShell has to be installed separately; it can be downloaded at the [https://www.microsoft.com/en-us/download/default.aspx Microsoft Download Center] free of charge. | ||
| − | If you want to implement your own scripts to automate MailStore Server tasks, the PowerShell API Wrapper Tutorial is ideal to start with. If you just want to use the scripts offered by MailStore, you can simply navigate to that section directly. | + | If you want to implement your own scripts to automate MailStore Server tasks, the [[PowerShell API Wrapper Tutorial]] is ideal to start with. If you just want to use the scripts offered by MailStore, you can simply navigate to that section directly. |
* [[PowerShell API Wrapper Tutorial]] | * [[PowerShell API Wrapper Tutorial]] | ||
| − | * PowerShell Scripts | + | * [[Media:PowershellScripts.zip|PowerShell Scripts]] |
| + | |||
| + | === Available Powershell Scripts === | ||
| + | |||
| + | {| class="wikitable" | ||
| + | ! scope="col" | File Name | ||
| + | ! scope="col" | Description | ||
| + | |- | ||
| + | | <tt>GrantUsersPrivilegesOnSelectedFolders_Server.ps1</tt><br/><tt>GrantUsersPrivilegesOnSelectedFolders_SPE.ps1</tt> | ||
| + | | Grants selected users permissions on all archives, except for archives that are explicitly excluded. | ||
| + | |} | ||
| + | |||
[[de:Scripting]] | [[de:Scripting]] | ||
[[en:Scripting]] | [[en:Scripting]] | ||
Latest revision as of 09:49, 26 September 2024
MailStore Server provides powerful interfaces, such as the MailStore Server Management Shell and the MailStore Server Administration API, that can be used to automate many tasks through scripts. This makes it possible to realize scenarios that would be difficult or impossible to implement through the GUI. Furthermore, scripting allows to integrate MailStore Server in existing workflows or business processes.
This article exemplifies the usage of the MailStore Server Administration API in several scripting languages. In our scripting section we assorted various scripts that make use of the demonstrated techniques and solve frequently posed problems. These scripts can be used freely and may be adapted to a specific environment or serve as a basis for further solutions.
Important Notice: The scripting code published in this section must be considered as reference and example implementations. Unless stated otherwise, the scripts are released under the terms an conditions of the MIT License.
Using Window Batch Scripts
For simple tasks, such as bulk import or export of PST files, Window batch scripts may also be used. Usually, these scripts do not control MailStore Server through the MailStore Server Administration API but through the command line interpreter.
Before you are able to execute Windows batch scripts on the command line cmd.exe, you need to open the script file in a text editor such as Notepad. Adjust the configuration variables above the DON'T CHANGE ANYTHING BEYOND THIS LINE line to your local environment. Please take care not to change any single or double quotes.
To obtain the the thumbprint (fingerprint, hash) of the MailStore Server certificate, follow these steps:
- Open the MailStore Server Service Configuration
- Navigate to Network Settings
- Click on the name of the server certificate that is used for MailStore Client
- Find the thumbprint in the details of the certificate
Be aware that when copying the thumbprint there may be an invisible character in front of the first character of the thumbprint. This invisible character must not be present in the script files. See [1] for details.
Available Windows Batch Scripts
| File Name | Description |
|---|---|
| bulkImportPST.bat | Import multiple PST files from a given directory into the archive of a the given MailStore user. A PST archiving profile of the type Single User with the name 'templateBulkImportPST' must be created manually beforehand. |
| bulkImportMBOX.bat | Import multiple MBOX files from a given directory into the archive of a the given MailStore user. An MBOX archiving profile with the name 'templateBulkImportMBOX' must be created manually beforehand. |
| bulkExportPST.bat | Export of all archives into multiple PST files seperated by MailStore users. A PST export profile with the name 'templateBulkExportPST' must be created manually beforehand. |
| bulkDeleteUsers.bat | Delete all MailStore users except the default admin user 'admin'. |
Using Python Scripts
Complex processes can more easily be automated with a higher level scripting language than simple Windows batch scripts. As a widely used, platform independent and easy to learn but powerful scripting language, Python is well suited to control MailStore Server through the MailStore Server Administration API.
To be able to execute Python scripts you need to install the Python runtime. The Windows installer of the Python runtime can be downloaded from Python.org. For Linux operating systems, please follow the instructions of your distributor's package manager to install the Python runtime.
For executing our scripts, a version of the Python API Wrapper is required. Installation instructions for the wrapper are available in the corresponding section of the Python API Wrapper Tutorial.
In order to execute Python scripts, you have to open the script file you want to execute with IDLE (shipped with Python's Windows installer) and adjust the configuration section above the line stating DON'T CHANGE ANYTHING BEYOND THIS LINE. Please take care not to change any double or single quotes.
To execute the script, click on Run > Run Module or press the F5-key in IDLE. A new window pops up where you can follow the standard output of the script and see possible execution errors.
If you are planning to write your own scripts in Python to automate MailStore Server tasks, the Python API Wrapper Tutorial offers a good starting point. Otherwise, if you just want to make use of the provided Python Scripts, you can download them from here.
Available Python Scripts
| File Name | Description |
|---|---|
| merge_folders_server.py merge_folders_spe.py |
Merges the first level of sub folders of a user archive. Can be used after archiving multiple PSTs of a user. |
| create_user_folders_server.py create_user_folders_spe.py |
Create folders in file system based on MailStore user names. Can be used in preparation of bulk imports of EML, MSG or PST files. |
| rename_inbox_server.py rename_inbox_spe.py |
In some cases there are two Inbox folders in the archive (Inbox and INBOX). This scripts merges them. You should merge them in the Inbox folder, that is filled by active archiving profiles. |
| update_user_names_server.py update_user_names_spe.py |
When the directory service changes, the usernames might change as well. When this happens, new archives will be created and the archiving might fill up these new archives. This script can be used before MailStore synchronizes with the changed directory service. It prepares usernames, archives and privileges on the own archive. When there are set up privileges on other archive, these privileges have to be adjusted manually. |
| check_mailstore_server_license.py check_mailstore_spe_license.py |
Nagios/Icinga plugin for monitoring available licenses. See Monitoring for further details. |
| check_mailstore_server_results.py check_mailstore_spe_results.py |
Nagios/Icinga plugin for monitoring recent results. See Monitoring for further details. |
| bulk_import.py | Imports email files for multiple users, see Bulk Import of Email Files for further details. |
Using PowerShell Scripts
As the standard shell that is shipped with every newer version of Windows, the .NET framework based Windows PowerShell is also well suited to control MailStore Server through the MailStore Server Administration API.
The MailStore PowerShell API Wrapper and the scripts are compatible with Windows PowerShell 3.0 and higher. Depending on the version of Windows, the Windows PowerShell has to be installed separately; it can be downloaded at the Microsoft Download Center free of charge.
If you want to implement your own scripts to automate MailStore Server tasks, the PowerShell API Wrapper Tutorial is ideal to start with. If you just want to use the scripts offered by MailStore, you can simply navigate to that section directly.
Available Powershell Scripts
| File Name | Description |
|---|---|
| GrantUsersPrivilegesOnSelectedFolders_Server.ps1 GrantUsersPrivilegesOnSelectedFolders_SPE.ps1 |
Grants selected users permissions on all archives, except for archives that are explicitly excluded. |
