Upgrade Configuration
The following is a reference of all the additional configuration settings that can be used in the context of an upgrade.
The format here follows that in the main configuration setting reference.
SourceDataPersistenceEngine
Type |
Level Specificity |
Default |
string |
Upgrade |
|
A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the source database.
SourceSystemDatabaseConnectionString
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The connection string to use when connecting to the system schema on the source database.
SourceTenantDatabaseConnectionString
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The connection string to use when connecting to the tenant schema on the source database.
SourceDatabaseSchema
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The DBMS-level schema to use when connecting to the source database. At this moment, it is not possible to specify different tenant and system DBMS schemas.
SourceDataHelperAssemblyName
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The assembly containing the custom data helper class for the Engine instance. Used only in .NET.
SourceDataHelperClassName
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The fully-qualified name of the class to be used as the Data Helper for the source database.
TargetDataPersistenceEngine
Type |
Level Specificity |
Default |
string |
Upgrade |
|
A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the target database.
TargetSystemDatabaseConnectionString
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The connection string to use when connecting to the system schema on the target database.
TargetTenantDatabaseConnectionString
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The connection string to use when connecting to the tenant schema on the target database.
TargetDatabaseSchema
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The DBMS-level schema to use when connecting to the target database. At this moment, it is not possible to specify different tenant and system DBMS schemas.
TargetDataHelperAssemblyName
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The assembly containing the custom data helper class for the Engine instance. Used only in .NET.
TargetDataHelperClassName
Type |
Level Specificity |
Default |
string |
Upgrade |
|
The fully-qualified name of the class to be used as the Data Helper for the target database.
UpgradeTenancy Settings
TargetTenant
Type |
Level Specificity |
Default |
string |
Upgrade |
|
If given, use this tenant's ID anytime we need to determine the value of an engine_tenant_id column. For single-tenant single-database customers (most customers), the recommended value of this setting is 'default'. For multi-tenant multi-database customers, this should be the name of the tenant associated with the database you are currently upgrading. For multi-tenant single-database customers, this setting should be omitted or left blank.
PackageToTenantQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
SELECT app_id FROM SCHEMA_PREFIX.ScormPackage WHERE scorm_package_id = @scorm_package_id |
For multi-tenant upgrades, this setting allows the user to specify a query that takes a scorm_package_id as input and returns the name of the associated tenant as output. This setting is required for multi-tenant upgrades.
TenantIdCacheSize
Type |
Level Specificity |
Default |
int |
Upgrade |
1000000 |
For multi-tenant upgrades, this setting affects the size of the cache used to map various kinds of internal Engine database IDs to tenants. Keep in mind that there are four such caches that will use this setting!
ZeroTenantOverride
Type |
Level Specificity |
Default |
string |
Upgrade |
default |
This setting allows the user to specify what name the 'zero' tenant has. This will go on to determine what the default value of their external configuration's tenant name parameter will be post-upgrade.
UpgradeSystemTables
Type |
Level Specificity |
Default |
bool |
Upgrade |
true |
This setting can be disabled in order to skip upgrading the system tables. A system connection string will still need to be provided when upgrading tenant tables.
UpgradeTenantTables
Type |
Level Specificity |
Default |
bool |
Upgrade |
true |
This setting can be disabled in order to skip upgrading the tenant tables. A system connection string will still need to be provided when upgrading tenant tables.
BatchSize
Type |
Level Specificity |
Default |
int |
Upgrade |
500 |
The number of rows to process in a single batch.
BatchSizeOverrides
Type |
Level Specificity |
Default |
IDictionary<string, int> |
Upgrade |
|
A mapping of phase names to batch sizes which will override the BatchSize setting, for situations where different phases call for different batch sizes.
MaxProcessingQueueSize
Type |
Level Specificity |
Default |
int |
Upgrade |
3 |
The maximum number of batches that can be queued up at once.
ThreadCountOverrides
Type |
Level Specificity |
Default |
IDictionary<string, int> |
Upgrade |
|
A mapping of worker names to thread counts to allocate a given number of threads for a specific worker.
ThreadCountMultiplier
Type |
Level Specificity |
Default |
int |
Upgrade |
1 |
A multiplier that will be applied to the configured thread counts. This allows customers to increase the number of active threads easily while maintaining the default proportions.
DatabaseReadThreads
Type |
Level Specificity |
Default |
int |
Upgrade |
2 |
The number of threads available for workers that read from the database. This does not affect the number of threads devoted to getting the rows into the batch pipeline in the first place, which is always a single-threaded operation.
ProcessingThreads
Type |
Level Specificity |
Default |
int |
Upgrade |
1 |
The number of threads available for workers that process data in memory. Since I/O is not involved in these threads, the benefit from multi-threading is presumably small.
DatabaseWriteThreads
Type |
Level Specificity |
Default |
int |
Upgrade |
4 |
The number of threads available for workers that write to the database.
FilesystemThreads
Type |
Level Specificity |
Default |
int |
Upgrade |
2 |
The number of threads available for workers that access the filesystem.
OnlineIndexingSupported
Type |
Level Specificity |
Default |
bool |
Upgrade |
true |
Stipulates whether the CREATE INDEX statements used during phase 1 of an online upgrade can be used without locking the table. This setting is not checked for PostgreSQL. For technical reasons we can't do lock-free indexing on PostgreSQL. This setting should only be marked false if you are running a non-Enterprise Edition of Oracle/SQL Server.
RowCopyStartAfter
Type |
Level Specificity |
Default |
NullableDateTime |
Upgrade |
|
If given, only copy rows after this date.
Schema Settings
DropExternalForeignKeys
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
If false (default), the upgrade will fail upon encountering foreign keys that involve an Engine table and a customer's table. If true, the upgrade will instead issue a warning and then drop those foreign keys. It will not add the foreign key back at the end of the upgrade.
ExternalPackageKeyColumns
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
Allows a customer to explicitly specify the definitions of external package key columns on ScormPackage. If used, the columns must match with the properties of the integration layer's implementation of ExternalPackageId.
ExternalRegistrationKeyColumns
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
Allows a customer to explicitly specify the definitions of external registration key columns on ScormRegistration. If used, the columns must match with the properties of the integration layer's implementation of ExternalRegistrationId.
ExtraPackageColumns
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
A comma-delimited list of column specifications for columns the customer added to ScormPackage, but are NOT part of the external key.
ExtraRegistrationColumns
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
A comma-delimited list of column specifications for columns the customer added to ScormRegistration, but are NOT part of the external key.
IncludeApiIntegration
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
This setting is often set automatically, but can sometimes be set manually. If given, tells the upgrade tool that it should include the Engine API-related columns.
IntegrationToApiRegistrationIdQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
|
This setting must be provided for customers that are migrating from an integration layer to our API integration. This query returns a string that will be used as the registrations' IDs when communicating with the API. The customer's current integration columns will be passed in as parameters.
IntegrationToApiCourseIdQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
|
This setting must be provided for customers that are migrating from an integration layer to our API integration. This query returns a string that will be used as this packages' IDs when communicating with the API. The customer's current integration columns will be passed in as parameters.
RegistrationToApiLearnerQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
|
This setting must be provided for customers that are migrating from an integration layer to our API integration. Given a row from ScormRegistration (which will contain any integration layer-defined columns), the query must return a learner_id (which must be a unique varchar), learner_first_name, and learner_last_name for the learner associated with that registration.
Migration Settings
DropXapiTables
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
If enabled, drops and recreates all xAPI-related tables instead of upgrading them.
DropLaunchHistory
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
If enabled, drops the ScormLaunchHistory table and recreates it instead of upgrading it. This table generally has a lot of data, and therefore this can result in significant time savings for the upgrade.
SkipxAPIFileStoreMigrations
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
If enabled, skips any migration or phase related to xAPI File Store.
SkippedPhases
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
A comma-delimited list of phases that the upgrade should skip entirely. Ask Rustici Support for the name of particular steps you want to skip.
MigrateLwsPostbackConfig
Type |
Level Specificity |
Default |
bool |
Upgrade |
|
If enabled for an LWS upgrade, upgrades the postback configuration for each registration to the new configuration schema.
Deduplication Settings
DeduplicateExternalKeysMode
Type |
Level Specificity |
Default |
Enum |
Upgrade |
ERROR |
The external key deduplication mode to use. Using this setting may result in lost data, so be warned! Recommended values are DELETE or REASSIGN.
MaxCasualtiesPerDuplicate
Type |
Level Specificity |
Default |
int |
Upgrade |
5 |
When deduplicating external keys, imposes an upper limit on the number of duplicates that can be reassigned. If the limit is exceeded, the upgrade stops in error. If you are having problems, the limit can be raised, but be sure to clear this with the support team first.
ScormPackageDeduplicationQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
|
If DeduplicateExternalKeys is enabled, this query will be run for each duplicated package row. Contact the Engine support team if you wish to use this setting.
ScormRegistrationDeduplicationQuery
Type |
Level Specificity |
Default |
string |
Upgrade |
|
If DeduplicateExternalKeys is enabled, this query will be run for each duplicated registration row. Contact the Engine support team if you wish to use this setting.
ScormPackageDeduplicationIndex
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
The index to use for deduplication, if different from the index we are upgrading to. Required when external key columns are removed or renamed.
ScormRegistrationDeduplicationIndex
Type |
Level Specificity |
Default |
string[] |
Upgrade |
|
The index to use for deduplication, if different from the index we are upgrading to. Required when external key columns are removed or renamed.