It is possible to control certain rules and behavior of the zendesk migration utility through the setting of properties in the zenmigration.properties file.
Note: Unlike the exception polices that can be set for each individual migration (see Setting Exception Policies for a Migration), these properties apply to all migrations performed using the installation of the zenmig utility.
As such it is important to understand how each configuration property will affect the behaviour and results of a migration and reset accordingly before each migration is invoked.
Locating the Configuration Properties
The zenmigration.properties (2) file can be located within the conf (1) directory of your zenmig application installation.
The contents of this file should be updated using a basic text editor such as notepad.
Defining Limits for Attachments
The Zendesk Import Limits determine the size (1) and number (2) of attachments that can be imported for tickets and ticket comments.
If the maximum number of attachments is exceeded the migration utility will return a warning message only and will still attempt to import the tickets and comments.
It is still possible that Zendesk will reject the attempt to import one or more attachments if the limits in place for the target account are exceeded.
However, if the maximum attachment size is exceeded the offending ticket or comment will be rejected with no attempt to import.
The maximum size and number of attachments will differ depending upon the payment plan in place for the target Zendesk.
Even though Zendesk will ultimately reject invalid attachments, setting these parameters can reduce the time taken to complete a migration by rejecting tickets and comments without attempting a failed import via the Zendesk API.
Controlling Re-attempts for Import and Search Failures
It is possible that during initial attempts to run a migration the format and structure of the data is incorrect, or that an environmental or missing policy for the target Zendesk will cause the rejection of a large number, if not all items during import.
The max_consecutive_import_faliures parameter (1) can be set in order to prevent the migration utility running on through the entire set of data when the probability is that the migration will have completely failed.
If the number of consecutive failures exceeds the value of this parameter during the import, then the migration will be terminated in a controlled fashion.
During import for a migration there are often cases in which a query of the search index fails to correctly identify the existence of a user.
Then when an attempt is made to create the user the operation fails since a user already exists for the given email address.
This is usually due to a delay in the rebuilding of the Zendesk search index, or a temporary loss of communication with Zendesk during the migration.
Setting the max_search_attempts (2) parameter will determine the number of attempts to retry the search before accepting the failure.
*Note: increasing this value will extend the time taken to complete an import in the case when there are many failed search attempts, however, it might reduce the number of failed tickets and/or alternative user policies invoked during the import.
Controlling the Import of External User ID's
By default when users are migrated, the external id is not imported into Zendesk.
However, this can be controlled by setting the user_external_ids (1) parameter to true.
*Note: it will of course be necessary to supply an external id for each user in the source data.
*Note: also, if a user already exists in the target Zendesk account with a matching external id and alternative email address, then the import of the user will be rejected by Zendesk since the external id has already been taken by another user.
Optimizing the Use of Available Memory on the Migration Server
Depending upon the resources available on the server used to host the migration utility, it might be necessary or appropriate to configure the way in which data is managed during the export and consolidation stages of the migration.
Use the max_records_per_file (1) parameter to determine how many users, topics or tickets are processed in memory at any time.
The larger the value in this parameter, the more memory will be consumed during export and consolidation.
If memory allows, the value can be increased to improve performance and speed up these stages of the migration.
Similarly, the number of attachments processed in memory at any time can be controlled using the max_cumulative_attachments_size_per_file (2).
Controlling Re-attempts for Failed REST API Calls during Export
During the export stage of a migration there are sometimes occasions during which a REST API call made to Zendesk fails while attempting to read and extract data.
These are often caused by short, temporary loss of connection to Zendesk and there is a high probability that the call will succeed during a subsequent attempt.
However, it is also possible that the call will never succeed, for example if the source Zendesk account has become unavailable, or something has changed in the database since the export started.
Setting a value in the max_rest_export_attempts (1) parameter will determine the number of reattempts to make in the event of a failed REST API call.
If this number is exceeded for a single instance of a call, or the value is set to zero, then the migration will be terminated in a controlled fashion.
*Note: setting this value too high could result in a failure to recognize that there are currently connection or availability issues and cause the migration to continue unnecessarily, filling up the log with failed REST API call messages.
An additional level of control can be gained by setting a value in the rest_export_call_sleep (2) parameter.
This value will determine the length of time in milliseconds to wait between re-attempts, in order to give chance for the connection to recover itself.
Controlling the Migration of Custom Fields during a Zendesk to Zendesk Migration
When using the migration utility to migrate from one Zendesk account to another, it may or may not be a requirement to take across the values held in custom ticket fields.
Set the zendesk_custom_fields (1) parameter to true or false to control if custom fields should be migrated.
*Note: in order to be able to migrate custom fields between Zendesk accounts, all of the custom fields in the source account must exists in the target account.
Each field must have an exact match on name and type and include matching option values and tags in any drop downs.
Any missing fields, values or mismatches will be reported before attempt is made to start the export stage and it won't be possible to continue with the migration.
Comments
0 comments
Please sign in to leave a comment.