Skip to main content

Migration Procedures

Overview​

The SCIM migration procedures fundamentally rely on the sample migration app provided. All procedure types (one time or continuous) rely on the same simple architecture of the sample app. Depending on the direction a reader, processor and mapper is defined together with an appropriate mapping of data. This is then executed one time for all users, and in case of continuous integrations executed for updated users over an extended period of time.

Spring Batch Step

One-time-bulk migration​

Overview​

A one‑time migration is typically required when transitioning from an existing identity provider to the NevisID stack to support frictionless user services. The Nevis SCIM REST Service provides a standards‑based interface for importing identity data using the SCIM 2.0 protocol, the provided sample app relies on these interface. This approach ensures interoperability, predictable data structures, and a consistent method for provisioning users and groups during the migration process.

The SCIM interface supports searching, exporting, and importing SCIM‑compliant entities, making it suitable for controlled, large‑scale onboarding scenarios.

Migration Approach​

1. Data Preparation​

Before initiating the migration, user data must be extracted from the third‑party system and transformed into SCIM‑compliant JSON structures. Key considerations include:

  • Mapping source attributes to SCIM core schema fields (for example, userName, name, emails, groups).
  • Ensuring mandatory SCIM attributes are present.
  • Validating data consistency to reduce import errors.
  • Normalizing identifiers to avoid conflicts during import.

2. Batch‑Based Import Strategy​

Although SCIM is not inherently optimized for bulk‑file ingestion, it can reliably support large migrations when executed in controlled batches.

Recommended practice:

  • Divide the migration into sequential batches (e.g., up to 1,000 users per request). the sample app provides out of the box support for this
  • Process each batch independently to maintain system stability and simplify error handling.
  • Avoid excessively small batches unless required for troubleshooting.

This approach ensures predictable performance and reduces the risk of partial failures during large‑scale imports.

3. Import Execution via SCIM Endpoints​

The Nevis SCIM REST Service exposes endpoints for creating and updating SCIM entities. During migration:

  • Each batch is sent to the SCIM /Users endpoint using standard SCIM POST or PUT operations by the sample app.
  • The service validates incoming data against SCIM schema definitions.

The SCIM REST Service supports both required and optional SCIM 2.0 functionalities, enabling flexible import workflows.

Error Handling and Validation​

During import, Nevis performs schema validation and integrity checks. If issues are detected:

  • The migration can continue, with errors collected and reported after the batch completes.
  • Or the process can be halted immediately, depending on the chosen strategy.

Typical validation errors include missing mandatory attributes, invalid formats, or conflicting identifiers.

A structured error report allows administrators to correct data and re‑submit only the affected records.

Post‑Migration Verification​

After all batches are processed:

  • Use the NevisID GUI or SCIM search endpoints to verify that all users and groups were successfully created
  • Validate key attributes (e.g., usernames, email addresses, group memberships)
  • Perform authentication tests to ensure migrated accounts function as expected
  • Optionally, export SCIM entities from Nevis to compare with the original dataset.

Continuous inbound migration​

Overview​

Continuous inbound migration is a strategy in which user data is synchronized one time or incrementally and continuously afterwards from a third‑party identity source into the Nevis Stack. Instead of migrating all users at once, the legacy system remains the primary system of record during the transition period, while Nevis gradually takes over as the authoritative identity provider.

This approach leverages the Nevis SCIM REST Service, which provides a standards‑based interface for creating, updating, and maintaining user and group data in real time.

When to Use Continuous Inbound Migration​

This method is ideal for scenarios where:

  • The migration must occur gradually over days, weeks, or months, and / or when
  • Both the legacy system and Nevis must operate in parallel
  • The organization wants to minimize downtime and avoid a “big bang” cutover
  • The source system remains authoritative until a defined point in the transition

Use this approach when you need to maintain operational continuity while progressively shifting identity management responsibilities to Nevis.

How Continuous Inbound Migration Works​

1. Source System as the Initial System of Record​

At the start of the migration:

  • The legacy identity store remains the authoritative source
  • All user lifecycle events—creation, updates, deactivation—occur in the legacy system
  • A synchronization mechanism (SCIM client or else) pushes updates to Nevis

Nevis receives these updates through its SCIM 2.0 endpoints, supported by a sample app, ensuring consistent and standards‑based data ingestion.

2. Incremental Synchronization via SCIM​

The migration engine continuously sends SCIM requests to Nevis:

  • POST /Users → Create new users
  • PUT /Users/{id} → Replace existing users
  • PATCH /Users/{id} → Apply partial updates
  • DELETE /Users/{id} → Remove or deactivate users (optional)

Nevis validates incoming data against SCIM schemas and applies changes to its internal identity store.

Synchronization can be triggered by:

  • Change events in the source system
  • Scheduled synchronization cycles (e.g., hourly, daily)
  • Login‑time provisioning
  • Delta‑based batch updates

3. Parallel Operation of Both Systems​

During the migration window:

  • Both systems remain active
  • Applications may authenticate against Nevis while still relying on attributes from the source system
  • User data is kept aligned through continuous SCIM updates
  • Conflicts are resolved based on the chosen master‑data strategy (source‑of‑truth rules)

This ensures a smooth transition without service disruption.

4. Transitioning the System of Record to Nevis​

Once a cutoff time has been reached:

  • The authoritative role shifts from the legacy system to NevisID
  • New user creation and updates begin to occur directly in NevisID
  • The source system can be decommissioned or moved into read‑only mode
  • SCIM synchronization is reduced or disabled

At this point, Nevis becomes the primary source of truth for all applications.

Continuous outbound migration​

Overview​

Continuous outbound migration is a synchronization approach in which Nevis acts as the primary system of record, and user data is continuously synchronized from Nevis back to a legacy system.

This model ensures that both systems remain aligned over time, even as NevisID becomes the authoritative identity provider. After an initial bulk load of all users synchronization occurs in outbound directions, from NevisID towards the legacy system.

This approach leverages the Nevis SCIM REST Service, which exposes SCIM 2.0‑compliant endpoints for reading, updating, and managing identity data.

When to Use Continuous Outbound Migration​

This method is particularly suitable for:

  • Complex system landscapes where multiple identity systems must remain aligned
  • Hybrid environments where foreign systems cannot be retired immediately
  • Long‑term coexistence between NevisID and external systems
  • Scenarios where Nevis becomes the primary identity provider
  • Ongoing legacysystem integration where data must flow back to the legacy system

How Continuous Outbound Migration Works​

1. Nevis as the Primary Data Source​

In this model:

  • Nevis becomes the authoritative identity store at start, after a one time bulk user migration
  • All user lifecycle events - creation, updates, deactivation - occur in Nevis
  • The legacy system becomes secondary and receives updates from Nevis

Nevis exposes identity data through its SCIM 2.0 endpoints, enabling standardized synchronization

2. Continuous Synchronization from Nevis → Source System​

A synchronization component periodically reads user data from NevisID and updates the external system.

Typical SCIM operations include:

  • GET /Users or POST /.search → Retrieve users from NevisID
  • GET /Users/{id} → Retrieve specific users
  • PATCH /Users/{id} or PUT /Users/{id} → Apply updates in the external system
  • DELETE /Users/{id} → Deactivate users in the external system (optional)

Synchronization can be:

  • Event‑driven (triggered by changes in Nevis)
  • Scheduled (e.g., every 5 minutes, hourly, daily)
  • Delta‑based (only changed users)

The external system is kept aligned with Nevis throughout the migration period seamlessly by the support of the provided sample app.

Provisioning Outbound Event Flow

3. Parallel Operation of Both Systems​

During the migration window:

  • Both systems remain active
  • Applications may rely on NevisID for authentication while still depending on attributes stored in the external system
  • Synchronization ensures both systems remain aligned
  • Conflict resolution rules determine which system “wins” for each attribute

This allows organizations to modernize without disrupting existing processes.

5. Final Phase: Decommissioning or Minimizing the Legacy System​

Once all applications and processes rely on NevisID:

  • The external system can be moved to limited use mode or decommissioned completely
  • Outbound synchronization can be reduced or stopped
  • Nevis becomes the sole authoritative identity provider

Next steps​

  • Plan your migration
  • Assess existing user data
  • Create new user structure in NevisID
  • Configure your field mappings
  • Customize your continuous migration apps
  • Execute migration