Migration

Overview

With Socotra Insurance Suite’s dedicated migration service, you can put your entire book of business into the system in a precise, efficient way.

The basic migration process looks like this:

  1. Deploy a configuration to the target tenant that will receive migrated data.

  2. Convert your source data to the form specified in the AccountMigrationRequest or MigrationRequest.

  3. Upload your data to the appropriate migration service endpoint.

  4. If necessary, address any errors reported during migration and re-submit problematic entities.

Migration Structure

You can easily import policies, accounts, invoices, payments, and disbursements from other systems by providing those entities in a form natural to the Socotra data model.

These are the top-level entities that you can provide in a migration request:

  • Accounts

  • Policies

  • Invoices

  • Payments

  • Disbursements

A policy is the atomic unit for a migration request: when you supply a policy, you should supply all necessary transaction history, along with any applicable invoices, payments, and disbursements. Once a policy has been migrated, it is a full-fledged policy in Socotra, and cannot be altered further through the migration service.

Since you may wish to import accounts, or already have accounts in the target tenant for which you would like to import data, the service offers two distinct entry points:

  1. Start Migration: takes an AccountMigrationRequest

  2. Start Migrations for an Existing Account: takes a MigrationRequest

In either case, the key is that the migration request contains all information required for Socotra to create supplied entities in the platform. Where possible, essential relationships are conveyed in Socotra’s natural hierarchy: a policy contains one or more terms, each of which contains one of more transactions, each of which may have one or more installments, and so on. This essential structure is reflected in the PolicyMigrationRequest. Likewise, InvoiceMigrationRequest, PaymentMigrationRequest, and DisbursementMigrationRequest allow you to specify related sub-entities as children of the parent entity.

Invoices, payments, and disbursements are not required for a migration request. If you specify installments but do not assign them to invoices provided in the migration request, the system will generate invoices for those installments, following typical system behavior for unbilled installments.

../_images/migration-request-overview.png

Note

We recommend that you limit migration requests to 50 megabytes, which ensures rapid completion for a range of scenarios, such as “many policies with few transactions” or “few policies with many transactions”. Contact your Socotra representative for performance and request size limit details relevant to your specific needs.

Bring Your Own Identifiers

Most migration request entities allow you the option to assign your own identifier to an id property. To specify a relationship that cannot be inferred from the migration hierarchy, such as an installment (contained in a transaction on a policy) that should be assigned to an invoice (a peer of policies in the migration request), you can assign your own identifiers to entities and refer to them elsewhere in the request. Socotra will convert custom identifiers to platform identifiers, maintaining referential integrity. Two migration endpoints expose the mappings from your own identifiers to Socotra identifiers:

Migration Management

A migration request to Start Migration or Start Migration for Account will receive a MigrationResponse with information that can be used to track the status of the migration, which is processed asynchronously. You can check on migration progress using the Get Migration Summary endpoint.

Note

A forthcoming release will allow you to fetch migration events in the event stream and set up webhooks to listen for key events, eliminating the need for status polling.

If a migration is processing, you may pause it with Pause Migration and resume it with Resume Migration. Any in-flight transactions will be fully processed before the pause takes effect, and you may interact with accounts and policies that had already been migrated prior to the pause. To view detailed lists of migrated entities, use the migration mappings endpoints.

Remediation

The migration service distinguishes between failure and error states: if any migrated entity in the request set fails validation – for example, you supply an account to be migrated with some data that violates some rule in your validation plugin – then the migration service will have a migrationState of failed. If a system error causes the migration to fail, then the migrationState will be error.

You can attempt to recover from an error state with the recoverMigration endpoint. For migration failures due to invalid data, you can follow this procedure:

  1. Determine which specific elements failed, and why, with Get Migration Failures.

  2. Patch the migration request, supplying updated versions of the entities that failed validation.

  3. Issue a recoverMigration request.