Prerequisites and References
Complete the checks on this page before starting any part of the nevisIDM User Migration Tool guide. Working through these steps first will prevent the most common setup problems and save time during the migration itself.
System requirements
| Component | Requirement |
|---|---|
| Java | JDK 25 or later (see step 1 below to verify your installation) |
| Build tool | Gradle (the Gradle wrapper gradlew is included — no separate installation needed) |
| Operating system | Any OS that supports Java 25 (Linux, macOS, Windows) |
| Disk space | Sufficient for tool binaries plus local JDBC database (job repository and event tables) |
1. Verify your Java installation
The migration tool requires Java 25 or later. Run the following command to confirm:
java -version
The output should show version 25 or higher, for example:
openjdk version "25" 2025-09-16
⚠️ WARNING : If Java is not installed or the version is below 25, install a current JDK before proceeding. The tool will not start without Java 25+.
2. Confirm access to the nevisIDM SCIM API
You need the following from your nevisIDM administrator before starting:
| Item | Example | Where to get it |
|---|---|---|
| nevisID SCIM base URL | https://idm.example.com/nevisidm/api/scim/v1 | |
| nevisIDM administrator | ||
| Service account username | scim-migration | nevisIDM administrator |
| Service account password or client certificate (PKCS12) | —- | nevisIDM administrator |
nevisID client external ID (extId) | my-tenant | nevisIDM admin console → Clients |
The tool supports two authentication methods. Prepare the credentials for whichever method your nevisIDM instance requires:
| Method | What you need |
|---|---|
| Basic Auth (default) | Username and password for the nevisIDM service account. Basic Auth takes precedence if both methods are configured. |
| Mutual TLS (mTLS) | A PKCS12 keystore containing the client certificate and private key, plus the corresponding truststore. Note the keystore path and passwords. |
Verify that the SCIM endpoint is reachable from the machine where you will run the tool:
curl -u scim-migration:yourpassword \
https://idm.example.com/nevisidm/api/scim/v1/ServiceProviderConfig
A 200 OK response confirms connectivity and that the credentials are valid. If you receive 401 Unauthorized or a connection error, resolve this before continuing.
3. Decide which mode you will use
The migration tool has four operating modes. Choose the one that matches your scenario now — it affects which prerequisites and configuration steps apply to you.
| Mode | Gradle task | Use when… | Extra prerequisites |
|---|---|---|---|
| Bulk | runBulk | You want a one-time full import from a file or database | |
| Source data exported and accessible | |||
| Continuous Inbound | runCInbound | Changes from the foreign system must flow into nevisID in real time | inbound_event database table created; integration layer ready to insert rows |
| Continuous Outbound (legacy) | runCOutbound | nevisID changes must be propagated back to the foreign system | JMS broker running; SampleUserRepository implementation ready |
| SCIM outbound | runCOutbound -Pbackend=scim | Downstream system is itself a SCIM-capable identity store |
4. Prepare your source data
The tool reads from one of five source profiles. Confirm your source is ready:
| Profile | Ready when… |
|---|---|
jdbc | You have the JDBC URL, driver class, username, and password for the legacy database, and the database is reachable from the migration host. The JDBC driver is bundled; for other databases, add the driver JAR to the classpath. |
csv | Export file exists on the migration host; you know the delimiter and whether there is a header row. |
json | Export file exists on the migration host. |
xml | Export file exists on the migration host. |
scim | Source SCIM endpoint URL, credentials, and pagination settings are available. |
The example implementation reads source data from a file by default; however, switching to a live SCIM endpoint is also supported, though it requires a code modification.
5. Map your fields (at least on paper)
Before writing configuration, sketch out how your source fields map to nevisIDM SCIM attributes. At minimum, confirm:
- Which source field becomes
userName— it must be unique across all users. - Which credential types are present in the source (e.g.
PASSWORD,CERTIFICATE). See the full list of 22 supported types in Field Mapping Configuration. - Whether any transformation is needed (date format conversion, concatenation, conditional logic).
- Whether users belong to one nevisIDM client or multiple (multi-tenancy).
6. Check JMS broker access (Continuous modes only)
If you are using the Outbound Continuous mode, verify that your JMS broker is running and reachable:
# Example using ActiveMQ's built-in check (adjust host/port as needed)
curl -u admin:admin http://jms-broker:8161/api/jolokia/read/org.apache.activemq:type=Broker,brokerName=localhost/BrokerVersion
Confirm you have the broker URL (tcp://jms-broker:61616), username, password, and the name of the provisioning queue.
ℹ️ NOTE : Continuous Inbound mode does not use any queue infrastructure — it polls the inbound_event database table directly.
7. Run the pre-flight checklist
- Java 25+ installed and confirmed with java -version
- nevisID SCIM URL noted and reachable (curl returns 200)
- Service account credentials (username/password or PKCS12) obtained
- nevisID client external ID (extId) confirmed
- Operating mode decided
- Source data accessible and profile identified
- Field mapping sketched (userName uniqueness confirmed)
- JMS broker accessible (Continuous modes only)
ℹ️ INFO : Once all items above are checked, you are ready to start. The recommended reading order is: Installation and Authentication Setup → Field Mapping Configuration → Running Your First Migration.
8. How to create properties
Before running any migration job, all custom attributes referenced in your mapping files must be pre-declared as property definitions in nevisIDM, as the SCIM API will reject any operation referencing an undefined property key.
9. SCIM APIs
The migration application uses the nevisIDM SCIM 2.0 API to create, update, and delete users — supporting operations such as bulk import, patch updates for credentials and custom properties, and filtered user searches. The API follows the SCIM 2.0 standard, making it straightforward to integrate with existing identity systems. For the full API reference, see the nevisIDM SCIM 2.0 documentation.
10. Developer's guide
The Migration Example Application is a reference implementation that covers the full lifecycle of synchronizing user identities between a foreign system and nevisID — including one-time bulk import, continuous inbound migration, and outbound sync via a SCIM relay. It details the mapping layer, configuration reference, and integration procedures needed to connect your existing user store to nevisIDM.