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.

UpgradeConnectionInformation Settings

SourceDataPersistenceEngine

A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the source database.

SourceSystemDatabaseConnectionString

The connection string to use when connecting to the system schema on the source database.

SourceTenantDatabaseConnectionString

The connection string to use when connecting to the tenant schema on the source database.

SourceDatabaseSchema

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

The assembly containing the custom data helper class for the Engine instance. Used only in .NET.

SourceDataHelperClassName

The fully-qualified name of the class to be used as the Data Helper for the source database.

TargetDataPersistenceEngine

A string (`sqlserver`, `mysql`, `postgresql`, or `oracle`) corresponding to the DBMS flavor in use for the target database.

TargetSystemDatabaseConnectionString

The connection string to use when connecting to the system schema on the target database.

TargetTenantDatabaseConnectionString

The connection string to use when connecting to the tenant schema on the target database.

TargetDatabaseSchema

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

The assembly containing the custom data helper class for the Engine instance. Used only in .NET.

TargetDataHelperClassName

The fully-qualified name of the class to be used as the Data Helper for the target database.

UpgradeTenancy Settings

TargetTenant

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

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

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

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

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

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.

UpgradePerformance Settings

BatchSize

The number of rows to process in a single batch.

BatchSizeOverrides

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

The maximum number of batches that can be queued up at once.

ThreadCountOverrides

A mapping of worker names to thread counts to allocate a given number of threads for a specific worker.

ThreadCountMultiplier

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

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

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

The number of threads available for workers that write to the database.

FilesystemThreads

The number of threads available for workers that access the filesystem.

OnlineIndexingSupported

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

If given, only copy rows after this date.

Schema Settings

DropExternalForeignKeys

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

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

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

A comma-delimited list of column specifications for columns the customer added to ScormPackage, but are NOT part of the external key.

ExtraRegistrationColumns

A comma-delimited list of column specifications for columns the customer added to ScormRegistration, but are NOT part of the external key.

IncludeApiIntegration

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

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

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

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

If enabled, drops and recreates all xAPI-related tables instead of upgrading them.

DropLaunchHistory

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

If enabled, skips any migration or phase related to xAPI File Store.

SkippedPhases

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

If enabled for an LWS upgrade, upgrades the postback configuration for each registration to the new configuration schema.

Deduplication Settings

DeduplicateExternalKeysMode

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

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

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

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

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

The index to use for deduplication, if different from the index we are upgrading to. Required when external key columns are removed or renamed.